풀 리퀘스트 설명에 노력을 기울여야 하는 이유

풀 요청은 새 코드가 제안, 검토 및 병합되는 기본 방법입니다. 우리는 풀 리퀘스트가 중요하다는 것을 알고 있습니다.

그러나 프로그래머는 풀 리퀘스트 설명을 작성하는 데 다양한 수준의 노력을 기울입니다.

최소한의 노력 PR

최소 노력 PR의 예는 다음과 같습니다.

# Description

Added column feature to table.

변경이 이루어진 이유나 근거를 제공하지 않으며 어떤 동작이 변경되었는지에 대한 힌트를 제공하거나 시청자가 이 정보를 찾을 수 있도록 문제 추적기에 대한 링크를 제공하지도 않습니다.

이 문제가 발생하는 이유

우리 프로그래머는 코드에 집중하기 쉽고 풀 리퀘스트를 성가시지만 검토를 위해 코드를 가져오는 데 필요한 단계로 간주할 수 있습니다.

우리는 PR이 단순히 형식적인 것이고 내용은 중요하지 않다고 생각하는 실수를 범할 수 있습니다.

우리는 생각할 수 있습니다

"궁금하면 질문을 합니다"

또는 "궁금하면 관련 티켓을 검색할 수 있습니다."

또는 "요점은 일단 병합되면 어쨌든 역사입니다."

그러나 이런 생각은 근시안적이다.

부주의한 홍보 콘텐츠가 해로운 이유

예, 검토자는 상황이 이해되지 않는 경우 질문을 해야 합니다. 하지만 당신은:

A. 필요 이상으로 리뷰어를 어렵게 만듭니다. 그리고
B. 더 중요한 것은 코드 조각이 추가된 이유와 중요한 정보에 대한 링크에 대한 귀중한 컨텍스트를 제거하고 있다는 것입니다.

(B)에 대해 좀 더 깊이 파고들겠습니다.

코드는 거의 정적으로 유지되지 않습니다. 그것은 진화하고 시간이 지남에 따라 원래 개념화되고 생성되었을 때와는 매우 다른 것으로 변형됩니다. 동일한 코드 조각이 다른 시점에서 다른 지식을 기반으로 할 수 있습니다.

앞으로 귀하 또는 다른 사람들이 특정 코드 변경이 이루어진 이유를 이해해야 하는 상황이 있을 것입니다. git Blame 또는 history를 사용하여 코드 변경 사항을 찾을 수 있습니다. 그러나 적절한 PR 설명이 없으면 컨텍스트가 역사에서 손실됩니다.

이런 생각은 근시안적이다.

그러나 적절한 설명을 작성하면 미래의 프로그래머가 이 풍부한 정보와 컨텍스트를 사용하여 코드 이면의 근거를 이해하고 더 빠르고 품질 높은 코드 결정을 내릴 수 있습니다.

팁

나를 위해 일한 몇 가지 사항은 다음과 같습니다.

PR에 대한 설명 제목 추가

feat [ENG-1234]: Add ability to add feedback column to PR table

설명에 적용된 모든 중요한 변경 사항을 상위 수준에서 지정합니다. 자세히 설명할 필요는 없지만 적어도 해당 코드에 대한 컨텍스트를 제공할 수 있을 정도로 높은 수준에서 나열해야 합니다.

This PR adds the following updates to PR Table:
1. Users can now add a column to add feedback.
2. Touch support.
3. Updates to unit tests to reflect new interactions.
4. Update third-party packages to add animation support.

코드 변경에 대한 메모가 있는 경우 이를 PR에 지정합니다.

Note. This PR results in visual regressions to support better touch targets. See the images below...

코드 뒤에 근거를 포함합니다. 에세이가 아니라 기능이 추가된 이유에 대한 짧은 설명이 필요합니다.

To allow users to add a column to add feedback information. For more information about the rationale check out this `[slack link](url)`.

문제 추적기 티켓에 대한 링크를 포함합니다. 근거를 포함하지 않기로 결정했다면 이는 두 배로 중요합니다.

[https://this-is-an-issue-tracker.com/eng-1234](https://this-is-an-issue-tracker.com/eng-1234)

(프론트 엔드의 경우) 시각적인 변경 사항이 있는 경우 이미지 또는 동영상이 포함됩니다.

PR 템플릿을 사용하여 설명, 근거 및 PR 체크리스트와 같은 정보를 포함하도록 권장합니다.