1. 단계별 공헌 방법

참고

이 과정을 설명하는 데 QGIS 문서를 예로 들긴 했지만, 다음 단락부터 보여줄 모든 명령어 및 단계는 QGIS 웹사이트에도 적용할 수 있습니다.

이 문서를 읽고 있다는 사실은 당신이 QGIS 문서 작성에 공헌할 마음을 가지고 있으며, 그 방법을 찾고 있다는 것이겠죠. 잘 오셨습니다! 이 문서는 QGIS 문서 작성이라는 목표를 달성하기 위한 여러 가지 방법을 알려드리고, 따라야 할 주요 단계와 당신이 사용할 수 있는 요령들 및 주의해야 할 함정들을 보여드릴 것입니다.

도움이 필요하다면 주저하지 말고 당신이 고치려 하는 문제점 보고서에 코멘트를 남겨 질문하거나 QGIS 커뮤니티 팀 메일링 리스트 에 문의하십시오. 자세한 내용은 문서 작성하기 를 참조하세요.

이제 시작해보겠습니다.

문서 소스는 git 버전 제어 시스템을 통해 저장되며 GitHub 에서 사용할 수 있습니다. 고쳐야 할 문제 및 설명해야 할 기능들의 목록은 https://github.com/qgis/QGIS-Documentation/issues 에서 찾아볼 수 있습니다.

처음으로 공헌하는 경우라서 어디서부터 시작해야 할지 모르겠다면, QGIS의 `초보를 위한 문제점 보고서 %3Aissue+is%3Aopen+label%3AEasy>`_ 를 살펴보는 것도 좋습니다.

문서 파일을 수정하는 데에는 결코 상호 배타적이 아닌 두 가지 주요 방법이 있습니다:

  1. GitHub 웹 인터페이스 사용하기

  2. Git 명령어줄 도구 사용하기.

1.1. GitHub 웹 인터페이스 사용하기

GitHub 웹 인터페이스에서 다음과 같은 작업을 실행할 수 있습니다:

  • 파일 편집

  • 변경 사항 미리보기 및 커밋(commit)

  • 주 저장소에 작성자의 변경 사항을 삽입하도록 PR 생성

  • 분기(branch) 생성, 업데이트, 또는 삭제

If you are not yet familiar with git and GitHub vocabulary, you may want to read the GitHub Hello-world project to learn some basic vocabulary and actions that will be used below.

참고

보고된 문제점을 고치려면

문제점 를 고치기 위해 변경 사항을 생성하는 경우, 자신에게 해당 문제점을 할당하기 위해 문제점 보고서에 코멘트를 추가하십시오. 여러 사람이 동시에 동일한 문제를 작업하는 일을 방지할 것입니다.

1.1.1. QGIS-Documentation 포크(fork)

당신이 이미 `GitHub 계정 `_ 을 가지고 있다고 가정하고, 가장 먼저 해야 할 일은 문서 소스 파일을 포크(fork)하는 것입니다.

QGIS-Documentation 저장소 페이지로 가서 우상단에 있는 githubFork 버튼을 클릭하십시오.

당신의 GitHub 계정에서 QGIS-Documentation 저장소(https://github.com/<YourName>/QGIS-Documentation)를 찾을 수 있을 것입니다. 이 저장소는 공식 QGIS-Documentation 저장소의 복사본으로, 공식 문서에 영향을 주는 일 없이 완전한 작성 권한으로 변경 사항을 작성할 수 있습니다.

1.1.2. 변경 사항 작성

QGIS 문서에 기고하는 데엔 여러 가지 방법이 있습니다. 다음 단락에 각각의 방법을 소개하고 있기는 하지만, 작성자가 한 과정에서 다른 과정으로 어떤 문제도 없이 바꿀 수 있습니다.

대안 1: Edit on GitHub 단축키 사용하기

QGIS 문서 웹사이트에 있는 페이지의 우상단에 있는 Edit on GitHub 링크를 클릭하면 각 페이지를 쉽고 빠르게 편집할 수 있습니다.

  1. 이때 열리는 파일은 qgis:master 분기에 있는 파일로, 페이지 상단에 작성자는 이 저장소에 대한 작성 권한이 없으며 작성자가 변경한 내용은 작성자의 저장소에 새로운 분기로 저장될 것이라는 메시지가 뜰 것입니다.

  2. 변경 사항을 작성하십시오. reStructureText 문법을 사용해서 문서를 작성하기 때문에, 당신이 작성하는 변경 사항에 따라 :ref:`문서 작성 가이드 <QGIS-documentation-guidelines>`_ 를 따라야 할 경우도 있습니다.

  3. When you finish, make a short comment about your changes and click on Propose changes. This will generate a new branch (patch-xxx) in your repository.

  4. Propose changes 를 클릭하면 GitHub가 Comparing changes 페이지로 이동할 것입니다.

    • 변경 사항 작성을 완료했다면, 아래에 있는 :ref:`PR을 통해 변경 사항 공유 <sharing_changes>`_ 부분의 :ref:` 변경 사항 비교 <compare_changes>` 로 건너뛰십시오.

    • 작성자가 QGIS에 변경 사항을 커밋하기 전에 추가로 변경하고자 하는 사항이 있다면, 다음 단계를 따르십시오:

      1. 작성자의 QGIS-Documentation 포크(https://github.com/<YourName>/QGIS-Documentation)로 가십시오.

      2. githubBranch 버튼을 클릭한 다음 patch-xxx 분기를 검색하십시오. 해당 분기를 선택하십시오. githubBranch 버튼의 텍스트가 Branch: patch-xxx 로 변했을 것입니다.

      3. 아래 있는 파일 수정하기 로 넘어가십시오.

참고

왼쪽 사이드바 하단에 있는 드롭다운 메뉴에서도 Edit on GitHub 단축키를 사용할 수 있습니다.

대안 2: 작성자의 문서 저장소에 애드혹(ad hoc) 분기 생성하기

QGIS 문서의 작성자 포크(fork)에서 파일을 직접 편집할 수 있습니다.

First, make sure that your master branch is up to date with qgis:master branch. To do so:

  1. Go to the main page of your repository, i.e. https://github.com/<YourName>/QGIS-Documentation. The master branch should be active with a mention whether it is up to date with qgis/QGIS-Documentation:master or not.

    If it has commits ahead the upstream branch, you better use the previous shortcut button alternative until you align your master branch.

    If it only has commits behind:

    1. Expand the Fetch Upstream drop-down menu on the right. You can

      • Compare the branches and see new changes in the main repository

      • Fetch and merge: takes changes from the upstream branch to yours.

    2. Let’s click Fetch and merge: after the process, your branch is mentioned as up to date with qgis/QGIS-Documentation:master.

  2. Click on githubBranch in the upper left corner of your forked QGIS-Documentation repository and enter a unique name in the text field to create a new branch . The name of the new branch should relate to the problem you intend to fix. The githubBranch button should now say Branch: branch_name

  3. You are ready to start new changes on top of it.

주의

절대 master 분기를 변경하지 말고, 애드혹 분기를 변경하십시오.

qgis/QGIS-Documentationmaster 분기의 수정 사항을 작성자의 QGIS 문서 저장소의 복사본으로 병합하는 경우를 제외하면 master 분기를 변경하지 마십시오. 개별 분기들을 구분하면, 다른 분기들을 건드리지 않고 동시에 여러 문제점을 작업할 수 있습니다. 실수가 발생한 경우 언제나 해당 분기를 삭제하고 마스터 분기에서 새 분기를 생성해서 다시 시작할 수 있습니다.

1.1.3. 파일 수정

  1. QGIS 문서의 작성자 포크의 소스 파일 가운데 수정해야 할 파일을 탐색하십시오.

  2. :ref:` 문서 작성 지침 <QGIS-documentation-guidelines>` 에 따라 수정하십시오.

  3. 수정 작업이 끝나면 페이지 하단에 있는 Commit Changes 프레임으로 가서 작성자가 수정한 사항에 대해 간단한 주석을 작성한 다음, Commit Changes 를 클릭해서 작성자 분기에 변경 사항을 직접 커밋하십시오. Commit directly to the branch_name branch. 옵션을 선택했는지 확인하세요.

  4. 문제점을 해결하기 위해 업데이트해야 하는 다른 파일에 대해서도 이 단계들을 반복하십시오.

1.1.4. PR을 통해 변경 사항 공유

공식 문서에 작성자의 변경 사항을 통합시키려면 PR(pull request)을 생성해야 합니다.

참고

Edit on GitHub 링크를 사용한 경우

작성자가 변경 사항을 커밋하면, 깃허브(GitHub)가 작성자의 patch-xxx 분기에서 변경된 사항을 qgis/QGIS-Documentation 마스터 분기와 비교하는 새 페이지를 자동적으로 열 것입니다.

다음 두 번째 단계 로 넘어가십시오.

새 PR 생성

QGIS-Documentation 저장소의 메인 페이지로 가서 New pull request 를 클릭하십시오.

변경 사항 비교

하나는 base:master 이고 다른 하나는 compare:branch_name 인 2개의 대화 상자가 나타난다면 (id7 참조) 작성자 분기 가운데 하나의 변경 사항을 작성자의 마스터 분기로 병합시킬 뿐입니다. 이를 바꾸려면 compare across forks 링크를 클릭하십시오.

../../_images/githubCompareAcrossForks.png

그림 1.1 작성자의 Comparing changes 페이지가 이렇게 보일 경우 compare across forks 링크를 클릭

4개의 드롭다운 메뉴가 나타날 것입니다. 이 메뉴들을 통해 작성자 분기의 변경 사항을, 병합시키고자 하는 마스터 분기와 비교할 수 있습니다. 이 드롭다운 메뉴는 다음과 같습니다:

  • base fork: 작성자 변경 사항을 병합시키고자 하는 포크

  • base: 작성자 변경 사항을 병합시키고자 하는 기반 포크(base fork)의 분기

  • head fork: 작성자가 기반 포크로 통합하려 하는 변경 사항이 있는 포크

  • compare: 해당 변경 사항을 가진 분기

qgis/QGIS-Documentationbase fork 로, masterbase 로 선택하고, 작성자 저장소 <YourName>/QGIS-Documentationhead fork 로, 작성자가 변경한 분기를 compare 로 설정하십시오.

../../_images/githubCreatePullRequestComparison.png

그림 1.2 qgis/QGIS-Documentation 과 작성자 저장소 사이의 변경 사항 비교

녹색 Able to merge 체크 표시는 작성자의 변경 사항을 문제없이 공식 문서로 병합시킬 수 있다는 사실을 나타냅니다.

Create pull request 버튼을 클릭하십시오.

경고

githubCantMerge 표시가 나타난 경우

This means that there are conflicts. The files that you are modifying are not up to date with the branch you are targeting because someone else has made a commit that conflicts with your changes. You can still create the pull request but you’ll need to fix any conflicts to complete the merge.

번역 중에도, QGIS 문서의 최신 버전 은 계속 유지보수되며 기존 문제점들을 해결하고 있습니다. 다른 배포판의 문제점을 해결하는 중이라면, 앞의 단계들에서 basemaster 에서 적절한 release_... 분기로 바꾸십시오.

작성자의 PR을 설명

텍스트란이 나타날 것입니다. 작성자가 제기하는 문제점과 관련된 주석을 작성하십시오.

혹시 특정한 기존 문제점 과 관련된 내용일 경우, 주석에 문제점 번호를 넣어주세요. #과 함께 문제점 번호를 (: #1234) 입력하면 됩니다. fix 또는 close 같은 용어를 앞에 넣어주면, PR이 병합되는 대로 해당 문제점은 종결될 것입니다.

작성자가 변경하는 모든 문서 페이지를 가리키는 링크들도 추가해주세요.

Create pull request 를 클릭하십시오.

PR 검토 및 논평

As seen above, anyone can submit modifications to the documentation through pull requests. Likewise anyone can review pull requests with questions and comments. Perhaps the writing style doesn’t match the project guidelines, the change is missing some major details or screenshots, or maybe everything looks great and is in order. Reviewing helps to improve the quality of the contribution, both in form and substance.

PR을 검토하려면:

  1. PR 페이지 로 가서 작성자가 논평하고 싶은 PR(pull request)을 클릭하십시오.

  2. 페이지 하단에 작성자가 PR에 대해 일반적인 논평을 남길 수 있는 텍스트란이 있을 것입니다.

  3. 특정 행에 대한 논평을 남기고 싶다면,

    1. githubFilesChanged 버튼을 클릭하고 논평하고자 하는 파일을 찾으십시오. 변경 사항을 보려면 Display the source diff 를 클릭해야 할 수도 있습니다.

    2. 작성자가 논평을 남기고 싶은 행으로 스크롤한 다음 githubBluePlus 아이콘을 클릭하십시오. 작성자가 논평을 남길 수 있는 텍스트란이 열릴 것입니다.

특정 행에 대한 논평은 다음 두 가지 방법으로 제출할 수 있습니다:

  • 단일 논평이라면 Add single comment 버튼을 사용하십시오. 그대로 공개될 것입니다. 짧은 논평이거나, 다른 논평에 대한 댓글일 경우에만 이 버튼을 사용하세요.

  • or as part of a review, pressing the Start a review button. Your comments are not automatically sent after validation, allowing you to edit or cancel them afterwards, to add a summary of the main points of the review or global instructions regarding the pull request and whether you approve it or not. This is the convenient way since it’s more flexible and allows you to structure your review, edit the comments, publish when you are ready and send a single notification to the repository followers and not one notification for each comment. Get more details.

../../_images/githubAddLineComment.png

그림 1.3 특정 라인에 변경 사항을 제안하는 논평

행 논평에는 PR 작성자가 PR에 적용할 수도 있는 제안을 내장시킬 수 있습니다. 제안을 추가하려면, 논평 텍스트란 위에 있는 githubSuggestions Insert a suggestion 버튼을 클릭하고 제안 블록 안에서 텍스트를 수정하십시오.

작성자의 PR에 제안을 배치(batch) 프로세스로 커밋하는 것을 선호

PR 작성자로서, 작성자의 PR에 검토자의 피드백을 직접 통합시킬 때 고려해야 할 제안들이 많아 배치 프로세스로 추가하는 편이 좋은 경우, 논평 텍스트란 하단에 있는 Commit suggestion 버튼을 사용하지 말고:

  1. githubFilesChanged 탭으로 전환하십시오.

  2. 작성자가 포함시키고 싶은 각 변경사항마다 Add suggestion to batch 를 클릭하십시오. 추가할 때마다 숫자가 올라가는 것을 볼 수 있습니다.

  3. 작성자의 PR에 제안들을 적용할 준비가 끝나면 Commit suggestions 버튼을 누른 다음, 변경 사항에 대한 설명을 입력하십시오.

이렇게 하면 작성자 분기에 모든 수정 사항을 커밋 한번으로 추가할 것입니다. 변경 사항 이력도 더 알아보기 쉽고, 저장소 팔로워들에게 가는 알림도 줄어듭니다. 의도하지는 않았지만, 작성자가 클릭해야 하는 횟수도 줄어들 겁니다.

수정 작업

새 PR은 자동적으로 PR(pull request) 목록 에 추가될 것입니다. 다른 편집자들과 운영자들이 작성자의 PR을 검토해서 제안을 커밋하거나 수정을 요구할 수도 있습니다.

PR은 자동화된 빌드 점검도 (예: rst(reStructuredText) 서식 작업의 경우 파이썬 코드 문법을 점검) 촉발할 것입니다. 점검 보고서는 페이지 하단에 표시됩니다. 오류를 발견했을 경우, 작성자의 커밋(commit) 옆에 빨간 가위표가 나타날 것입니다. 이 빨간 가위표 또는 PR 페이지 하단의 요약 부분에 있는 Details 를 클릭하면 오류의 세부 정보를 볼 수 있습니다. 보고된 모든 오류 또는 경고를 해결해야 qgis/QGIS-Documentation 저장소에 작성자의 변경 사항을 커밋할 수 있습니다.

작성자의 PR이 메인 저장소와 병합되기 전까지, 작성자의 PR을 향상시키거나 요구받은 수정 사항을 적용하거나 빌드 오류를 해결하기 위해 PR을 수정할 수 있습니다.

PR을 변경하려면 작성자의 PR 페이지의 githubFilesChanged 탭을 클릭한 다음 수정하고자 하는 파일명 옆에 있는 githubEditPencil 연필 버튼을 클릭하십시오.

작성자의 PR에서 커밋한 것과 동일한 분기를 변경하는 경우, 추가한 변경 사항이 PR에 자동적으로 추가될 것입니다. 따라서, 작성자가 해당 PR로 해결하려는 문제에 관련되었을 경우에만 변경 사항을 추가해야 합니다.

또다른 문제점을 해결하고 싶다면, 해당 변경 사항을 위한 새 분기를 생성한 다음 앞의 단계를 반복하십시오.

모든 빌드 오류가 수정되고 작성자와 운영자가 작성자의 변경 사항에 대해 만족한 다음에야 운영자가 작성자의 기고 내용을 병합할 것입니다.

1.1.5. 작성자의 병합된 분기 삭제

작성자의 변경 사항이 병합됐다면, 해당 분기를 삭제해도 됩니다. 목적을 다 한 분기를 삭제하면 사용자 저장소에 사용되지 않거나 이전 버전인 분기를 유지하지 않아도 됩니다.

  1. QGIS 문서 저장소의 사용자 포크(https://github.com/<YourName>/QGIS-Documentation)로 가십시오.

  2. Branches 탭을 클릭하십시오. Your branches 아래 사용자 분기 목록이 있을 겁니다.

  3. deleteSelected Delete this branch 아이콘을 클릭하면 원하지 않는 모든 분기를 삭제할 수 있습니다.

1.2. Git 명령 프롬프트 도구 이용

깃허브(GitHub) 웹 인터페이스는 QGIS 문서 저장소에 작성자의 기고 내용을 쉽게 업데이트하도록 도와주지만, 다음과 같은 도구들을 제공하진 않습니다:

  • 작성자의 커밋을 그룹화하고 변경 이력을 삭제

  • 메인 저장소와 일어날 수 있는 충돌을 해결

  • 작성자의 변경 사항을 테스트하기 위한 문서를 빌드

더 강력하고 더 고급인 도구에 접근하려면 그리고 저장소의 로컬 사본을 보유하려면 먼저 작성자의 하드드라이브에 Git을 설치 해야 합니다. 작성자가 자주 필요로 할 몇몇 기본 사항들을 다음 단락에서 소개합니다. 웹 인터페이스를 사용하기로 결정한 경우에도 신경 써야 할 규칙들도 함께 찾을 수 있을 겁니다.

다음에 나오는 코드 예시에서, # 로 시작하는 줄은 주석을 의미하지만 $ 로 시작하는 줄은 작성자가 입력해야 하는 명령어를 나타냅니다.

1.2.1. 로컬 저장소

이제 작성자의 QGIS 문서 저장소의 로컬 사본을 받을 준비가 됐습니다.

다음 웹 URL을 사용하면 작성자의 QGIS 저장소를 복제할 수 있습니다:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://github.com/<YourName>/QGIS-Documentation.git

이 명령줄은 예시일 뿐입니다. 작성자는 <YourName> 을 작성자의 깃허브 사용자명으로 대체하여 경로 및 저장소 URL 둘 다 작성자의 로컬 환경에 맞춰야 합니다.

다음을 점검하십시오:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
$ git branch
* master
  • origin 은 작성자의 QGIS 문서 저장소의 원격 저장소의 명칭입니다.

  • master 는 기본 주 분기입니다. 기고하는 데 절대로 이 분기를 이용해서는 안 됩니다! 절대로요!!

다른 방법으로는 SSH 프로토콜을 사용해서 작성자의 QGIS 저장소를 복제할 수 있습니다:

# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone [email protected]:<YourName>/QGIS-Documentation.git

권한 거부 (퍼블릭키) 오류?

If you get a Permission denied (publickey) error with the former command, there may be a problem with your SSH key. See GitHub help for details.

SSH 프로토콜을 사용한 경우 다음을 점검하십시오:

# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

여기서 작업을 시작해도 괜찮지만, 길게 봤을 때 작성자의 작업 내용을 푸시할 경우 (깃허브 처리 과정에서는 PR이라고 합니다) 작성자의 로컬/원격 저장소에서 qgis/QGIS-Documentation 저장소의 주 분기가 갈라져 나올 것이기 때문에 수많은 문제점이 발생할 것입니다. 그러면 메인 원격 저장소를 계속 추적하면서 분기와 작업해야 합니다.

1.2.2. 또다른 원격 저장소 추가

주 프로젝트에서 작업을 추적할 수 있으려면, 작성자의 로컬 저장소에 새 원격 저장소를 추가하십시오. 이 새 원격 저장소가 QGIS 프로젝트에서 나온 QGIS 문서 저장소입니다.

$ git remote add upstream https://github.com/qgis/QGIS-Documentation.git
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
upstream        https://github.com/qgis/QGIS-Documentation.git (fetch)
upstream        https://github.com/qgis/QGIS-Documentation.git (push)

마찬가지로, SSH 프로토콜을 사용해서 사용자의 로컬 저장소에 원격 저장소를 추가할 수 있습니다:

$ git remote add upstream [email protected]:qgis/QGIS-Documentation.git
$ git remote -v
origin  [email protected]:<YourName>/QGIS-Documentation.git (fetch)
origin  [email protected]:<YourName>/QGIS-Documentation.git (push)
upstream        [email protected]:qgis/QGIS-Documentation.git (fetch)
upstream        [email protected]:qgis/QGIS-Documentation.git (push)

이제 두 원격 저장소들 사이에서 선택할 수 있습니다.

  • 작성자 의 원격 저장소에 작성자의 로컬 분기를 푸시하는 origin

  • 공식 문서로 작성자의 작업 내용을 (그럴 권한이 있을 경우) 통합하거나, 공식 저장소의 마스터 분기에서 나온 작성자의 로컬 저장소의 마스터 분기를 업데이트하는 upstream

참고

upstream 은 라벨일 뿐으로, 일종의 표준 명칭이지만 원하는 대로 명명할 수 있습니다.

1.2.3. 작성자의 기반 분기 업데이트

새 작성 작업을 시작하기 전에, 항상 작성자의 로컬 저장소에 있는 마스터 분기를 업데이트해야 합니다. 테스트 버전 문서에 변경 사항을 푸시하려 한다고 가정하고, 다음 명령어를 실행하십시오:

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the upstream repository
# (aka qgis/QGIS-Documentation's repository)
$ git fetch upstream master
# merge update from upstream/master to the current local branch
# (which should be master, see step 1)
$ git merge upstream/master
# update **your** remote repository (aka <YourName>/QGIS-Documentation)
$ git push origin master

이제 작성자는 QGIS 문서 저장소의 공식 master 분기와 동일한 버전의 master 분기를 가진 로컬 및 원격 저장소를 얻었습니다. 문서 작성을 시작할 수 있습니다.

참고

배포판 문서에 기고하고자 할 경우 분기를 전환

테스트 버전 문서 작업과 동시에, 최신 배포판 의 문제점들도 계속 고쳐나가고 있습니다. 작성자가 배포판 문서에도 기고할 수 있다는 의미지요. 앞 단락에 나온 예시 코드에서 master 를 최신 문서의 대응하는 분기로 치환하면 됩니다.

1.2.4. 작성자의 작업 분기로 기고

이제 작성자의 기반 분기가 업데이트됐으니, 작성 내용을 추가할 전용 분기를 생성해야 합니다. 언제나 기반 분기가 아닌 다른 분기에서 작업하십시오! 언제나요!

# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

커밋/푸시(commit/push) 명령어에 대해:

  • 오직 하나의 (원자 단위의 변경) 내용만, 예를 들어 오직 문제점 하나만 다루도록 해보십시오.

  • 작성자의 커밋 제목 및 설명에 무엇을 변경했는지 꼼꼼히 서술해보십시오. 첫 줄은 제목으로, 대문자로 시작해야 하고 문자 80개의 길이 제한이 있으며 . 로 끝나서는 안 됩니다. 제목은 간결하게 적으십시오. 설명은 더 길어도 되고, . 로 끝나며, 더 상세하게 서술할 수 있습니다.

  • 어떤 문제점인지 식별하기 위해 # 뒤에 문제점 번호를 적으십시오. 해당 버그 티켓을 해결했다면 그 앞에 Fix 를 입력하십시오. 작성자의 커밋이 해당 티켓을 폐지할 것입니다.

작성자의 로컬 분기에 변경 사항을 저장하고 커밋했으니, 이제 PR을 생성하기 위해 변경 사항을 작성자의 원격 저장소에 전달해야 합니다:

$ git push origin myNewBranch

1.2.5. 작성자의 변경 사항 공유

이제 작성자의 GitHub 저장소로 가서 앞 단락에서 설명한 대로 PR을 생성 할 수 있습니다. 작성자의 분기에서 목표인 공식 QGIS 문서 저장소에 있는 원격 분기로 PR을 생성했는지 확인하십시오.

1.2.6. 작성자의 로컬 및 원격 저장소 청소

작성자의 PR이 공식 QGIS 문서에 통합된 다음, 작성자의 분기를 삭제할 수 있습니다. 이런 방식으로 많은 작업을 하는 경우, 몇 주만 지나도 쓸데없는 분기들을 많이 보유하게 될 겁니다. 따라서 다음 방법을 통해 작성자의 저장소를 말끔히 유지하십시오.

# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

그리고 작성자의 로컬 저장소에 있는 master 분기를 업데이트하는 것도 잊지 마십시오!

1.3. 참고문헌

  • 앞에서 설명한 깃허브 웹 인터페이스와 git 명령 줄 도구 이외에도, 작성자가 문서에 기고 내용을 생성하고 관리하는 데 사용할 수 있는 GUI 응용 프로그램 도 있습니다.

  • PR의 변경 사항이 최근 대상 분기에 푸시된 변경 사항과 충돌을 일으키는 경우, 병합할 수 있으려면 먼저 충돌을 해소해야 합니다:

    • if the conflict relates to few competing lines, a Resolve conflicts button is available in the GitHub pull request page. Press the button and resolve the issue as explained at Resolving a merge conflict on GitHub

    • if the conflict involves files renaming or removal, then you’d need to resolve the conflict using git command lines. Typically, you have to first rebase your branch over the target branch using git rebase targetBranch call and fix the conflicts that are reported. Read more at Resolving a merge conflict using the command line

  • Sometimes, at the end of the proofreading process, you may end up with changes split into multiple commits that are not necessarily worth it. Git command lines help you squash these commits to a smaller number and more meaningful commit messages. Some details at Using git rebase on the command line