풀 리퀘스트 가이드라인

풀 요청(PR)은 Matplotlibs 코드 및 문서에 기여하기 위한 메커니즘입니다.

풀 리퀘스트 작성자 요약

메모

• 우리는 모든 수준의 경험을 가진 사람들의 기여를 소중히 여깁니다. 특히 이것이 첫 번째 PR인 경우 모든 것이 완벽할 필요는 없습니다. PR 프로세스를 안내해 드립니다.

• 그럼에도 불구하고 PR 프로세스가 빠르고 원활하게 진행될 수 있도록 아래 지침을 최대한 따르십시오.

• 리뷰어에게 인내심을 가지십시오. 신속하게 대응하기 위해 최선을 다하고 있지만 대역폭이 제한되어 있습니다. 며칠 내에 피드백이 없으면 PR에 의견을 게시하여 ping을 보내주십시오.

PR을 할 때 다음 사항에 주의하십시오.

• 주요 지점을 대상으로 합니다 .

• 코딩 지침 을 준수하십시오 .

• 필요한 경우 문서 를 업데이트하십시오 .

• PR을 가능한 한 "준비" 상태로 만드는 것을 목표로 하십시오. 이는 검토 프로세스의 속도를 높이는 데 도움이 됩니다.

• 개발자의 도움이나 피드백이 필요한 경우 불완전하거나 진행 중인 PR을 열어도 됩니다. GitHub에서 이를 초안 끌어오기 요청 으로 표시할 수 있습니다.

• PR을 업데이트할 때 무언가를 수정하기 위해 새 커밋을 추가하는 대신 기록을 깨끗하게 유지하기 위해 초기 커밋을 수정하는 것을 고려하십시오. 다음을 사용하여 이를 달성할 수 있습니다.

  git commit --amend --no-edit
  git push [your-remote-repo] [your-branch] --force-with-lease
  

PR을 만드는 방법에 대한 기여도 참조하십시오 .

풀 리퀘스트 검토자를 위한 요약

메모

• 커밋 권한이 있는 경우 해당 권한을 사용할 수 있습니다. PR을 검토하고 병합하도록 도와주세요!

• 기여자들 에게 인내심을 갖고 친절 하게 대하십시오.

내용 주제:

• 기능/버그 수정이 합리적입니까?

• PR이 코딩 지침 을 준수 합니까?

• 설명서 (docstrings, 예제 , 새로운 기능, API 변경 사항)가 업데이트되었습니까?

조직 주제:

• 모든 자동화된 테스트 가 통과하는지 확인하십시오.

• PR은 주요 지점을 대상으로 해야 합니다 .

• 설명 레이블 이 있는 태그 .

• 이정표 를 설정합니다 .

• 커밋 수를 주시하십시오 .

• 위의 주제가 모두 처리되면 승인합니다.

• 충분한 수의 승인에 도달하면 병합 합니다.

세부 가이드라인

문서

• 모든 새로운 기능은 문서화되어야 합니다. 새 모듈인 경우 API 문서에 새 첫 번째 파일을 추가하는 것을 잊지 마십시오.

• 각각의 고수준 플로팅 함수는 Examplesdocstring 섹션에 작은 예제가 있어야 합니다. 이는 방법을 시연하기 위해 가능한 한 간단해야 합니다. 더 복잡한 예제는 디렉터리의 전용 예제 파일에 들어가야 합니다. 이 파일 examples은 설명서의 예제 갤러리에 렌더링됩니다.

• 문서를 작성하고 모든 형식 경고가 해결되었는지 확인하십시오.

• 문서 스타일 가이드는 문서 작성 을 참조하세요 .

• 변경 사항이 주요 새 기능인 경우 에 항목을 추가하십시오 doc/users/whats_new.rst.

• 이전 버전과 호환되지 않는 방식으로 API를 변경하는 경우 의 관련 하위 디렉터리 doc/api/next_api_changes/(아마도 하위 디렉터리)에 파일을 추가하여 문서화하십시오 behavior/ .

레이블

• 레이블을 설정할 수 있는 권한이 있는 경우 설명 레이블로 PR에 태그를 지정하십시오. 레이블 목록을 참조하십시오 .

• PR이 휠 빌딩 작업을 변경하는 경우 "Cibuildwheel 실행" 레이블을 추가하여 테스트 휠을 활성화하십시오.

이정표

• 다음 규칙에 따라 이정표를 설정합니다.

  • 새로운 기능 및 API 변경 사항 은 다음 마이너 릴리스에 대한 마일스톤입니다 v3.X.0.

  • 버그 수정 및 docstring 변경 사항 은 다음 패치 릴리스에 대한 마일스톤입니다.v3.X.Y

  • 문서 변경 사항 (모든 .rst 파일 및 예제)이 중요합니다 .v3.X-doc

  여러 규칙이 적용되는 경우 위 목록에서 첫 번째로 일치하는 규칙을 선택합니다.

  이정표를 설정한다고 해서 PR이 해당 릴리스에 대해 병합된다는 것을 의미하거나 보장하는 것은 아니지만, 병합될 경우 어떤 릴리스에 포함될 것인지를 의미합니다.

  이러한 모든 PR은 기본 분기를 대상으로 해야 합니다. 이정표 태그 는 해당 분기가 있는 이정표에 대한 자동 백포트 를 트리거합니다.

병합

• 문서와 예제는 첫 번째 검토자가 병합할 수 있습니다. 임계값을 사용하여 "이것이 이전보다 더 나은가요?" 검토 기준으로.

• 코드 변경( src또는 에 있는 모든 것 lib)의 경우 최소 두 명의 핵심 개발자(커밋 권한이 있는 사람)가 모든 풀 요청을 검토해야 합니다. PR을 처음으로 검토하고 변경 사항을 승인하는 경우 GitHub '검토 승인' 도구를 사용하여 이를 표시합니다. 후속 리뷰어인 경우 리뷰를 승인하고 더 이상 리뷰가 필요하지 않다고 생각되면 PR을 병합하십시오.

  모든 API 변경 사항이 의 하위 디렉토리 중 하나에 있는 파일에 문서화되어 doc/api/next_api_changes있고 중요한 새 기능이 에 항목이 있는지 확인하십시오 doc/user/whats_new.

  • PR에 이미 긍정적인 리뷰가 있는 경우 핵심 개발자(예: 첫 번째 리뷰어이지만 반드시 그렇지는 않음)는 병합을 위해 해당 PR을 옹호할 수 있습니다. 그렇게 하기 위해서는 GitHub와 개발자 메일링 리스트 모두에서 모든 핵심 개발자를 ping하고 PR에 "단일 리뷰로 병합하시겠습니까?"라는 레이블을 지정해야 합니다. 상표. 그런 다음 다른 핵심 개발자는 PR을 검토하고 병합하거나 거부하거나 병합되기 전에 두 번째 검토를 받도록 요청할 수 있습니다. 아무도 일주일 이내에 두 번째 검토를 요청하지 않으면 해당 단일 검토를 기반으로 PR을 병합할 수 있습니다.

    핵심 개발자는 한 번에 하나의 PR만 옹호해야 하며 우리는 옹호된 PR의 흐름을 합리적으로 유지하려고 노력해야 합니다.

• CI를 해제하기 위한 '작은' 패치 또는 다른 검토자가 명시적으로 허용하는 경우(예: "모듈로 CI 통과 승인, 녹색일 때 자체 병합 가능")를 제외하고 자체 병합하지 마십시오.

자동화된 테스트

풀 요청이 생성되거나 업데이트될 때마다 다양한 자동화 테스트 도구가 지원되는 모든 플랫폼 및 Python 버전에서 실행됩니다.

• 병합하기 전에 Linting, GitHub Actions, AppVeyor, CircleCI 및 Azure 파이프라인이 통과하는지 확인하십시오(모든 검사는 풀 요청의 GitHub 페이지 하단에 나열됨). 다음은 테스트 실패의 원인을 찾기 위한 몇 가지 팁입니다.

  • Linting 이 실패 하면 풀 요청의 diff에 주석으로 나열되는 코드 스타일 문제가 있는 것입니다.

  • GitHub Actions 또는 AppVeyor 실행이 실패하면 로그에서 FAILURES. 다음 섹션에는 실패한 테스트에 대한 정보가 포함됩니다.

  • CircleCI가 실패하면 문서에 reStructuredText 스타일 문제가 있을 수 있습니다. CircleCI 로그에서 WARNING.

  • 이미지 비교 오류로 인해 Azure 파이프라인이 실패하면 이미지를 Azure 작업의 아티팩트 로 찾을 수 있습니다 .

    • GitHub PR 페이지의 확인에서 세부 정보 를 클릭 합니다.

    • Azure 파이프라인에 대한 자세한 정보 보기를 클릭 하여 Azure 로 이동합니다.

    • 개요 페이지 에서 아티팩트 는 관련 섹션에 나열됩니다 .

• Codecov 및 LGTM은 현재 정보용으로만 제공됩니다. 그들의 실패가 반드시 장애물은 아닙니다.

• tox 는 자동 테스트에 사용되지 않습니다. 로컬 테스트용으로 지원됩니다.

• 변경 사항을 테스트할 필요가 없다는 것을 알고 있는 경우(매우 드문 일입니다!) 커밋 메시지에 또는 포함하여 지정된 커밋에 대한 모든 CI를 건너뛸 수 있습니다. CI의 하위 집합만 실행해야 하는 경우(예: 일반 reStructuredText의 일부 블록을 변경하고 결과를 렌더링하기 위해 CircleCI만 실행하려는 경우) 다음을 사용하여 개별 커밋에서 개별 CI를 건너뛸 수 있습니다. 커밋 메시지의 하위 문자열:[ci skip][skip ci]

  • GitHub 작업:[skip actions]

  • AppVeyor: (커밋의 첫 줄에 있어야 함)[skip appveyor]

  • Azure 파이프라인:[skip azp]

  • Circle CI:[skip circle]

커밋 및 스쿼싱 수

• 스쿼시는 경우에 따라 다릅니다. 균형은 기여자에 대한 부담, 상대적으로 깨끗한 기록 유지 및 이등분에 사용 가능한 기록 유지 사이에 있습니다. 우리가 정말 엄격하게 다루는 유일한 경우는 바이너리 파일(예: 다중 테스트 이미지 재생성)을 제거하고 업스트림 병합을 제거하는 것입니다.

• 특히 문서나 예제 PR의 경우 완벽함을 좋은 것의 적으로 만들지 마십시오. 작은 제안을 많이 하는 경우 원래 브랜치에 대해 PR을 열거나 기여자 브랜치에 변경 사항을 푸시하거나 PR을 병합한 다음 업스트림에 대해 새 PR을 엽니다.

• 기여자 브랜치로 푸시하는 경우 "당신의 작업에 감사드립니다."와 같이 귀하의 브랜치에 작은 정리 PR을 자유롭게 푸시했습니다. PR의 코드나 의도를 크게 변경하려는 경우 먼저 기여자에게 확인하십시오.

브랜치 및 백포트

현재 지점

현재 활성 분기는 다음과 같습니다.

기본

현재 개발 버전입니다. 향후 마이너 릴리스( v3.N.0 )는 여기에서 분기됩니다.

v3.Nx

Matplotlib 3.N의 유지 관리 분기 향후 패치 릴리스는 여기에서 분기됩니다.

v3.NM 문서

현재 릴리스에 대한 설명서입니다. 패치 릴리스에서는 새 릴리스에 대해 적절한 이름의 브랜치로 대체됩니다.

풀 요청에 대한 분기 선택

일반적으로 모든 풀 요청은 기본 분기를 대상으로 해야 합니다.

다른 분기는 자동 또는 수동 을 통해 공급 됩니다 . 다른 분기를 직접 대상으로 지정하는 것은 특별한 유지 관리 작업에 거의 필요하지 않습니다.

백포트 전략

우리는 항상 패치 릴리스 브랜치( v3.Nx )로 백포트할 것입니다.

• 중요한 버그 수정(segfault, 가져오기 실패, 사용자가 해결할 수 없는 것)

• 마지막 두 릴리스에 대한 회귀 수정.

다른 모든 것(이전 릴리스에 대한 회귀, 사용자가 자신의 코드에서 해결할 수 있는 버그/API 불일치)은 사례별로 있고 위험이 낮아야 하며 백포트를 옹호하고 안내할 사람이 필요합니다.

문서 분기( v3.NM-doc ) 로 백포트되는 유일한 변경 사항 은 doc, examples또는 에 대한 변경 사항 tutorials입니다. libdocstring 전용 변경 사항을 포함 하거나 포함 하는 모든 변경 src사항은 이 브랜치로 백포트되지 않아야 합니다.

자동화된 백포트

우리는 meeseeksdev 봇을 사용하여 이정표에서 올바른 유지 관리 분기 기반으로 병합을 자동으로 백포트합니다. 제대로 작동하려면 병합하기 전에 이정표를 설정해야 합니다. 커밋 권한이 있는 경우 PR에 메시지를 남겨 병합 후 봇을 수동으로 트리거할 수도 있습니다 . 충돌이 있는 경우 meeseekdevs는 백포트를 수동으로 수행해야 한다고 알려줍니다.@meeseeksdev backport to BRANCH

대상 분기는 자체 행에 이정표 설명을 입력하여 구성됩니다.on-merge: backport to TARGETBRANCH

봇이 예상대로 작동하지 않으면 Meeseeksdev 에 문제를 보고하십시오 .

수동 백포트

백포트를 수행할 때 meeseekdev에서 사용하는 양식을 복사하십시오 . 충돌을 수동으로 해결해야 하는 경우 커밋 메시지에 충돌과 충돌을 해결한 방법을 기록해 둡니다.Backport PR #XXXX: TITLE OF PR

다음을 가정하여 기본에서 v2.2.x로 백포트를 수행합니다.

• matplotlibmatplotlib/matplotlib 리포지토리의 읽기 전용 원격 브랜치입니다.

TARGET_SHA백포트하려는 병합 커밋의 해시입니다 . 이것은 GitHub PR 페이지(병합 알림이 있는 UI에서) 또는 git CLI 도구를 통해 읽을 수 있습니다.

이미 로컬 분기가 있고 v2.2.x(없으면 ) 원격 포인팅이 다음과 같이 호출 된다고 가정합니다 .git checkout -b v2.2.xhttps://github.com/matplotlib/matplotlibupstream

git fetch upstream
git checkout v2.2.x  # or include -b if you don't already have this.
git reset --hard upstream/v2.2.x
git cherry-pick -m 1 TARGET_SHA
# resolve conflicts and commit if required

충돌이 있는 파일은 에 의해 나열될 수 있으며 직접 수정해야 합니다( 에서 검색 ). 충돌이 해결되면 파일을 분기에 다시 추가한 다음 선별 작업을 계속해야 합니다.git status>>>>>

git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue

재량에 따라 업스트림으로 직접 푸시하거나 PR을 열 수 있습니다. v2.2.x업스트림 브랜치 에 대해 푸시하거나 PR해야 합니다 main.