GitHub에서 기여하기#

이 가이드는 Flower에 참여하고 싶지만 GitHub 프로젝트에 기여하는 데 익숙하지 않은 분들을 위한 것입니다.

깃허브에서 기여하는 방식에 익숙하다면 :doc:`기여자를 위한 시작 가이드<contributor-tutorial-get-started-as-a-contributor>`를 직접 확인하세요.

레포지토리 설정하기#

  1. GitHub 계정을 만들고 Git을 설정합니다

    Git은 분산 버전 관리 도구입니다. 이를 통해 전체 코드베이스의 히스토리와 모든 개발자의 컴퓨터를 저장할 수 있습니다. 로컬 컴퓨터에 설치해야 하는 소프트웨어로, 이 `가이드 <https://docs.github.com/en/get-started/getting-started-with-git/set-up-git>`_를 따라 설정할 수 있습니다.

    GitHub는 그 자체로 버전 관리 및 협업을 위한 코드 호스팅 플랫폼입니다. 누구나 원격 레포지토리에서 어디서든 협업하고 작업할 수 있습니다.

    아직 계정을 만들지 않았다면 `GitHub <https://github.com/signup>`_에서 계정을 만들어야 합니다.

    일반적인 Git 및 GitHub 워크플로우의 기본 개념은 다음과 같이 요약됩니다. GitHub의 원격 레포지토리에서 코드를 다운로드하고 로컬에서 변경한 후 Git을 사용하여 추적한 다음 새 기록을 다시 GitHub에 업로드하는 것입니다.

  2. Flower 레포지토리 포크하기

    포크는 GitHub 리포지토리의 개인 복사본입니다. Flower용 포크를 만들려면 <https://github.com/adap/flower>`_로 이동하여(GitHub 계정에 연결된 상태에서) 페이지 오른쪽 상단에 있는 ``포크` 버튼을 클릭해야 합니다.

    _images/fork_button.png

    원하는 경우 이름을 변경할 수 있지만, 이 버전의 Flower는 자신의 계정(즉, 자신의 리포지토리 목록)에 위치하게 되므로 변경할 필요는 없습니다. 만들기가 완료되면 왼쪽 상단에Flower 버전이 표시되는 것을 볼 수 있습니다.

    _images/fork_link.png
  3. 포크된 레포지토리 클론하기

    다음 단계는 컴퓨터에서 포크된 레포지토리를 변경할 수 있도록 다운로드하는 것입니다. 포크된 포지토리 페이지에서 먼저 오른쪽의 Code 버튼을 클릭하면 레포지토리의 HTTPS 링크를 복사할 수 있습니다.

    _images/cloning_fork.png

    <URL>를 복사한 후에는 컴퓨터에서 터미널을 열고 레포지토리를 다운로드할 위치로 이동하여 입력하면 됩니다:

    $ git clone <URL>

    현재 작업 디렉터리에``flower/``(또는 포크 이름을 변경한 경우 포크 이름) 폴더가 생성됩니다.

  4. origin 추가

    그런 다음 레포지토리 폴더로 이동할 수 있습니다:

    $ cd flower

    여기에 레포지토리에 origin을 추가해야 합니다. origin은 원격 포크 레포지토리의 <URL>입니다. origin을 얻으려면 앞서 설명한 대로 GitHub 계정의 포크 레포지토리로 이동하여 링크를 복사하면 됩니다.

    _images/cloning_fork.png

    <URL> 이 복사되면 터미널에 다음 명령을 입력하면 됩니다:

    $ git remote add origin <URL>
  5. Upstream 추가하기

    이제 레포지토리에 upstream 주소를 추가하겠습니다. 여전히 같은 디렉터리에서 다음 명령을 실행해야 합니다:

    $ git remote add upstream https://github.com/adap/flower.git

    다음 다이어그램은 이전 단계에서 수행한 작업을 시각적으로 설명합니다:

    _images/github_schema.png

    upstream은 부모 레포지토리(이 경우 Flower)의 GitHub 원격 주소, 즉 우리가 최종적으로 기여하고 싶고 따라서 최신 기록이 필요한 레포지토리입니다. origin은 우리가 만든 포크된 레포지토리의 GitHub 원격 주소, 즉 우리 계정에 있는 사본(포크)입니다.

    로컬 버전의 포크가 Flower 레포지토리의 최신 변경 사항으로 최신 상태인지 확인하려면 다음 명령을 실행하면 됩니다:

    $ git pull upstream main

코딩 환경 설정#

:doc:’기여자를 위한 시작 가이드 <contributor-tutorial-get-started-as-a-contributor>’를 참조하세요(레포지토리를 복제할 필요는 없습니다). 코드를 작성하고 테스트할 수 있게 되면 드디어 변경을 시작할 수 있습니다!

변경하기#

변경하기 전에 레포지토리를 최신 상태로 유지하세요:

$ git pull origin main

Flower의 레포지토리도 있습니다:

$ git pull upstream main
  1. 새 브랜치 만들기

    히스토리를 더 깔끔하고 작업하기 쉽게 만들려면 구현해야 하는 각 기능/프로젝트에 대해 새 브랜치를 만드는 것이 좋습니다.

    이렇게 하려면 레포지토리 디렉토리에서 다음 명령을 실행하면 됩니다:

    $ git switch -c <branch_name>
  2. 변경하기

    선호하는 편집기를 사용하여 멋진 코드를 작성하고 훌륭한 변화를 만들어 보세요!

  3. 코드 테스트 및 서식 지정

    코드를 테스트하고 서식을 지정하는 것을 잊지 마세요! 그렇지 않으면 코드를 Flower 레포지토리에 병합할 수 없습니다. 이는 코드베이스가 일관성을 유지하고 이해하기 쉽도록 하기 위한 것입니다.

    이를 위해 실행할 수 있는 몇 가지 스크립트를 작성했습니다:

    $ ./dev/format.sh # to format your code
$ ./dev/test.sh # to test that your code can be accepted
$ ./baselines/dev/format.sh # same as above but for code added to baselines
$ ./baselines/dev/test.sh # same as above but for code added to baselines
  4. Stage 변경

    기록을 업데이트할 커밋을 만들기 전에 어떤 파일을 고려해야 하는지 Git에 지정해야 합니다.

    이 작업을 수행할 수 있습니다:

    $ git add <path_of_file_to_stage_for_commit>

    마지막 버전(마지막 커밋)과 비교하여 수정된 파일을 확인하고 커밋을 위해 스테이징된 파일을 확인하려면 git status 명령을 사용하면 됩니다.

  5. Commit 변경

    :code:`git add`를 사용하여 커밋하려는 모든 파일을 추가한 후, 마지막으로 이 명령을 사용하여 커밋을 생성할 수 있습니다:

    $ git commit -m "<commit_message>"

    커밋의 내용을 다른 사람에게 설명하기 위해 <commit_message>가 있습니다. 명령형 스타일로 작성해야 하며 간결해야 합니다. 예를 들면 git commit -m "Add images to README".

  6. 변경 사항을 포크에 푸시

    변경 사항을 커밋하면 로컬 히스토리를 효과적으로 업데이트한 것이지만, 변경 사항을 원본의 원격 주소로 푸시하지 않는 한 GitHub는 이를 알 방법이 없습니다:

    $ git push -u origin <branch_name>

    이 작업이 완료되면 변경한 내용으로 포크된 레포지토리가 업데이트된 것을 GitHub에서 확인할 수 있습니다.

pull request(PR) 만들기 및 병합하기#

  1. PR 만들기

    변경 사항을 푸시하고 나면 레포지토리의 GitHub 웹페이지에 다음 메시지가 표시됩니다:

    _images/compare_and_pr.png

    그렇지 않으면 언제든지 Branches 페이지에서 이 옵션을 찾을 수 있습니다.

    Compare & pull request 버튼을 클릭하면 이와 비슷한 화면이 표시됩니다:

    _images/creating_pr.png

    상단에는 어느 지점이 어디에 병합될 것인지에 대한 설명이 있습니다:

    _images/merging_branch.png

    이 예제에서는 내 포크된 레포지토리의 doc-fixes 브랜치를 Flower 레포지토리의 main 브랜치에 병합하라는 요청을 볼 수 있습니다.

    제목은 PR 제목 형식 가이드라인을 준수하도록 변경해야 하며, 그렇지 않으면 PR을 병합할 수 없습니다. 따라서 이 경우 올바른 제목은 ``docs(framework:skip) Fix typos``이 될 수 있습니다.

    가운데에 있는 입력 상자는 PR의 기능을 설명하고 기존 이슈에 연결할 수 있는 곳입니다. 프로세스를 안내하기 위해 코멘트(PR이 열리면 렌더링되지 않음)를 배치했습니다.

    코멘트에 설명된 지침을 따르는 것이 중요합니다.

    하단에는 PR을 여는 버튼이 있습니다. 이렇게 하면 검토자에게 새 PR이 열렸으며 병합하거나 변경을 요청하기 위해 검토해야 함을 알립니다.

    PR이 아직 검토할 준비가 되지 않았고 다른 사람에게 알리고 싶지 않은 경우 pull request 초안을 만드는 옵션이 있습니다:

    _images/draft_pr.png
  2. new changes 만들기

    PR이 초안으로 열렸든 아니든, PR과 연결된 브랜치를 변경하여 이전과 같은 방식으로 새 커밋을 푸시할 수 있습니다.

  3. PR 검토하기

    PR이 열리거나 초안 PR이 준비됨으로 표시되면 코드 소유자의 검토가 자동으로 요청됩니다:

    _images/opened_pr.png

    그러면 코드 소유자는 코드를 살펴보고, 질문하고, 변경을 요청하거나 PR의 유효성을 검사합니다.

    진행 중인 변경 요청이 있는 경우 병합이 차단됩니다.

    _images/changes_requested.png

    이를 해결하려면 PR과 연결된 브랜치에 필요한 변경 사항을 푸시하면 됩니다:

    _images/make_changes.png

    그리고 소통을 통해 해결하세요:

    _images/resolve_conv.png

    모든 대화가 해결되면 검토를 다시 요청할 수 있습니다.

  4. PR이 병합되면

    모든 자동 테스트가 통과되고 검토자가 더 이상 요청할 변경 사항이 없는 경우 PR을 승인하고 병합할 수 있습니다.

    _images/merging_pr.png

    병합이 완료되면 GitHub에서 브랜치를 삭제할 수 있으며(삭제 버튼이 표시되어야 함), 로컬에서도 삭제할 수 있습니다:

    $ git switch main
$ git branch -D <branch_name>

    그런 다음 다음을 수행하여 포크된 레포지토리를 업데이트해야 합니다:

    $ git pull upstream main # to update the local repository
$ git push origin main # to push the changes to the remote repository

첫 번째 기여의 예#

문제#

저희 문서에는 ‘Diàtaxis 프레임워크 <https://diataxis.fr/>`_’를 사용하기 시작했습니다.

‘How to’ 가이드의 제목은 “How to …”라는 문장을 이어가는 제목이어야 합니다(예: “How to upgrade to Flower 1.0”).

대부분의 가이드는 아직 이 새로운 형식을 따르지 않으며, 안타깝게도 제목을 변경하는 작업은 생각보다 복잡합니다.

이번 이슈는 문서 제목을 현재 연속형에서 현재 단순형으로 변경하는 것에 관한 것입니다.

“How to saving progress”을 “How to save progress”으로 변경한 예를 들어 보겠습니다. 이것이 우리의 점검을 통과했나요?

Before: “How to saving progress” ❌

After: “How to save progress” ✅

해결법#

이것은 사소한 변경이지만 end-to-end 설정을 테스트할 수 있습니다. Flower 레포지토리를 복제하고 설정한 후에는 다음과 같이 하세요:

  • ``doc/source``에서 소스 파일을 찾습니다

  • .rst 파일에서 변경합니다(제목 아래의 대시는 제목 자체의 길이와 같아야 합니다)

  • 문서를 빌드하고 ‘결과 확인 <contributor-how-to-write-documentation.html#edit-an-existing-page>`_’합니다

파일 이름 바꾸기#

파일 이름에 여전히 이전 문구가 반영되어 있는 것을 보셨을 것입니다. 파일만 변경하면 파일에 대한 기존 링크가 모두 끊어지는데, 링크를 끊으면 검색 엔진 순위에 영향을 줄 수 있으므로 이를 방지하는 것이 **매우 중요**합니다.

파일 이름을 변경하는 방법은 다음과 같습니다:

  • 파일 이름을 ``save-progress.rst``로 변경합니다

  • ‘doc/source/conf.py’에 리디렉션 규칙을 추가합니다

이렇게 하면 ``saving-progress.html``에서 ``save-progress.html``로 리디렉션되며, 이전 링크는 계속 작동합니다.

인덱스 파일에 변경 사항 적용#

횡방향 내비게이션 바가 제대로 작동하려면 index.rst 파일도 업데이트하는 것이 매우 중요합니다. 이 파일은 탐색 모음의 전체 배열을 정의하는 곳입니다.

  • ``index.rst``에서 파일 이름을 찾아 수정합니다

PR 열기#

  • 변경 사항을 커밋합니다(커밋 메시지는 항상 필수 메시지입니다:”Do something”(이 경우 는 “Change …” )

  • 변경 사항을 포크에 푸시합니다

  • docs(framework) Update how-to guide title 제목으로 PR(위와 같이)을 엽니다

  • 승인될 때까지 기다리세요!

  • 축하합니다! 이제 공식적으로 Flower 기여자가 되셨습니다!

다음 단계#

첫 번째 PR을 작성하고 더 많은 기여를 하고 싶다면 다음을 확인하세요:

부록#

PR 제목 형식#

다음과 같은 PR 제목 형식을 적용합니다:

<type>(<project>) <subject>

(또는 ``<type>(<project>:skip) <subject>``를 사용하면 변경 로그에서 PR을 무시합니다.)

여기서 <type>``은 ``{ci, fix, feat, docs, refactor, break}, ``<project>``는 ``{framework, baselines, datasets, examples, or ‘*’ ‘:skip’ 플래그를 사용해야 하는 여러 프로젝트를 수정하는 경우}``로 입력해야 하며, ``<subject>``는 대문자로 시작해야 합니다.

유효한 예시입니다:

  • feat(framework) Add flwr build CLI command

  • refactor(examples:skip) Improve quickstart-pytorch logging

  • ci(*:skip) Enforce PR title format

잘못된 예시입니다:

  • feat(framework): Add flwr build CLI command ( ``:``제외)

  • feat(*) Add flwr build CLI command (skip flag와 함께 ``*``누락)

  • feat(skip) Add flwr build CLI command (``<project>``누락)

  • feat(framework) add flwr build CLI command (대문자로 표기되지 않은 동사)

  • feat(framework) Add flwr build CLI command. (끝에 마침표)

  • Add flwr build CLI command. ( ``<type>(<project>)``누락)