단계별 기고 방법¶

작성자 저장소에서 변경 사항 작성¶

https://github.com/qgis/QGIS-Documentation/issues 에 보고된 문제점들 또는 작성자가 문서를 읽다가 발견한 문제점들을 다룬다면 문서를 향상시킬 수 있습니다. 문제점들은 서로 다른 유형일 수 있겠죠. 오타, 도형 누락, 잘못 됐거나 업데이트 안 된 설명...

풀 요청을 통해 변경 사항 공유¶

이제, 작성자는 QGIS에 qgis:master 에서 갈라져 나온 파일이 담긴 새 분기를 보유하게 됐습니다. 작성자의 변경 사항을 공식 문서로 통합하려면, 풀 요청을 전달해야 합니다.

1. 사실, 작성자가 변경 사항을 커밋하면, GitHub은 분기들을 비교하는 새 대화창을 엽니다.

   • 작성자가 URL을 변경하지 않고 현재 페이지 수정 을 사용한 경우, 작성자의 patch-xxx 분기와 qgis:master (기반 포크는 qgis/QGIS-Documentation 이며 이 포크의 분기인 master 입니다)를 비교합니다.

   • 작성자가 직접 명명한 분기를 사용했을 경우, 해당 분기와 작성자의 master 분기(기반 포크는 그냥 master 입니다)를 비교합니다. 따라서 이 대화창은 내버려두고 다음 단계를 따라야 합니다.

2. 어떤 경우든 간에 (명령 프롬프트에서 분기를 GitHub으로 푸시하는 걸 포함해서) 어떤 때에라도 대부분의 페이지에서 신규 풀 요청을 생성할 수 있습니다. (작성자 또는 QGIS의) 저장소의 메인 페이지로 가서, New Pull Request 와 (필요할 경우) Compare across forks 를 클릭하면 됩니다. 작성자가 기반 분기로 qgis/QGIS-Documentation 의 master 를 선택했는지 확인하고, 헤드 포크(head fork)가 작성자가 수정한 분기를 담은 작성자의 저장소 <YourName>/QGIS-Documentation 인지 확인하십시오.

   참고

   이미 배포된 상태로 번역 중이긴 하지만, QGIS 2.14 문서는 지금도 계속 관리되며 기존 문제점들을 수정하고 있습니다. 현재 배포판의 문서에 존재하는 문제점을 수정하고자 할 경우, 앞에서 소개했던 어떤 단계에서든 master 분기를 적절한 manual_en_... 분기로 대체하십시오.

3. 비교 중인 분기들에 붙는 녹색 체크 표시는 작성자의 변경 사항을 공식 문서에 자동적으로 통합할 수 있다는 뜻입니다. Create pull request 버튼을 클릭하십시오. 적색 가위표가 붙을 경우, 작성자가 수정 중인 파일이 목표 분기의 최신 버전이 아니라는 뜻입니다. (작성자가 분기를 생성하거나 마지막으로 업데이트한 이후 커밋이 발생한 겁니다.) 이 경우 git command line tools 를 통해 문제를 해결해야 합니다.

4. 필요한 경우 양식을 채운 다음, 다시 Create pull request 버튼을 클릭하십시오.

5. 새 풀 요청(PR)이 https://github.com/qgis/QGIS-Documentation/pulls 에 추가돼 누구나 해당 요청을 보고 코멘트할 수 있게 됩니다.

6. 이때 작성자의 기고 내용이 빌드 오류를 포함하고 있지는 않은지 자동적으로 확인하는 Travis CI build 가 작동됩니다. 오류가 있을 경우, 작성자의 커밋에 적색 가위표가 붙습니다. 그냥 해당 가위표를 클릭하거나, 페이지 하단에 있는 요약 부분에 있는 Details 를 클릭해서 자세한 오류 내용을 확인하십시오. 여기 보고된 모든 오류나 경고를 해결해야 저장소에 작성자의 변경 사항을 커밋할 수 있습니다.

7. 작성자의 풀 요청이 주 저장소와 통합될 때까지, 작성자는 제안 내용에 수정 사항을 추가할 수 있습니다. 실제로 작성자의 분기에 추가되는 어떤 새 변경 사항도 풀 요청에 첨부될 겁니다. 다만 작성자가 수정 중인 문제점과 관련된 변경 사항일 경우에만 이렇게 하고, 다른 문제점일 경우 새 분기를 생성해서 앞의 단계를 따르십시오.

8. 모든 것이 작성자 및 다른 기고자들에게 괜찮게 보일 경우에만 제출자(committer)가 작성자의 분기를 주 저장소와 통합합니다. 작성자의 기고가 승인된 겁니다.

9. 원한다면, 작성자의 저장소가 너무 많은 (사용되지 않고 오래된) 분기들로 넘쳐나는 일을 피하기 위해 작성자가 사용했던 분기를 삭제할 수 있습니다.

이 짧은 단계들을 따라 한다면 문서 처리 과정을 더 쉽게 배울 수 있을 겁니다.

로컬 저장소¶

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

$ cd ~/Documents/Development/QGIS/
$ git clone [email protected]:<YourName>/QGIS-Documentation.git

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

다음 예시를 확인해보세요.

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

• origin 은 작성자의 QGIS 문서 저장소의 원격 저장소의 명칭입니다.

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

여기서 작업을 시작해도 괜찮지만, 길게 봤을 때 작성자의 작업 내용을 푸시할 경우 (GitHub 처리 과정에서는 풀 요청이라고 합니다) 작성자의 로컬/원격 저장소에서 QGIS 문서 저장소의 주 분기가 갈라져 나올 것이기 때문에 수많은 문제점이 발생할 것입니다.

또다른 원격 저장소 추가¶

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

$ 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

작성자의 기반 분기 업데이트¶

# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in 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
$ git push origin master

# change branch e.g. for 2.14 LTR
$ git checkout manual_en_2.14
# get "information" from the manual_en_2.14 branch in upstream repository
$ git fetch upstream manual_en_2.14
# merge update from upstream/manual_en_2.14 to the current local branch
$ git merge upstream/manual_en_2.14
# update **your** remote repository
$ git push origin manual_en_2.14

작성자의 작업 분기로 기고¶

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

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

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

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

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

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

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

$ git push origin myNewBranch

작성자의 변경 사항 공유¶

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

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

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

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

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