주석
이번 과정을 설명하는 데 QGIS 문서를 예로 들긴 했지만, 다음 단락부터 보여줄 모든 명령어 및 단계는 QGIS 웹사이트에도 적용할 수 있습니다.
이제 QGIS를 위해 깔끔한 문서를 작성하기 위한 규칙 을 알게 됐으니, 이 문서를 생산하는 과정 및 그 변경 사항을 커뮤니티와 빠르고 안전하게 공유하는 방법을 알아봅시다.
작성자가 이미 GitHub 계정 을 보유하고 있다고 가정하고, 작성자가 작업할 문서를 얻으려면 먼저 문서의 소스 파일들을 복사해야 합니다. QGIS 문서 저장소 페이지로 가서 (편의를 위해, 다음부터 이 저장소를 qgis/QGIS-Documentation 라고 부르겠습니다) 우상단에 있는 Fork 버튼을 클릭하십시오.
몇 초 후, 작성자의 GitHub 계정에서 QGIS 문서 저장소(https://github.com/<YourName>/QGIS-Documentation)를 찾을 수 있을 겁니다. 이 저장소는 공식 문서에 영향을 끼칠 위험이 없이, 완전한 문서 작성 접근 권한을 보장하며 작성자의 모든 기고를 업데이트할 수 있는 안전한 사본입니다. 처음엔 이 저장소가 qgis/QGIS-Documentation 과 동일한 분기를 담고 있으며 기본적으로 master 분기로 설정돼 있습니다. 분기란 서로 통합될 수도 나뉠 수도 있는 문서의 서로 다른 스냅샷(snapshot)들을 담고 있는 평행한 작업선(線)들을 말합니다. 작성자가 원하는 문서마다 새 분기를 만드는 것이 좋습니다. 작성자는 원하는만큼 많은 분기를 생성할 수 있습니다.
참고
절대 master 를 변경하지 말고, 임시 분기를 변경하십시오.
관례에 따라, qgis/QGIS-Documentation 의 (qgis:master 라 불리는) master 분기에 발생한 수정 사항을 합치는 작업 이외에 작성자의 master 분기를 변경하지 마십시오. 작성자의 master 분기는 깔끔한 문서 이력 및 스냅샷을 생성하는 모델로 이용하시기 바랍니다.
QGIS 문서에 기고하는 데엔 여러 가지 방법이 있습니다. 다음 단락에서 각각의 방법을 소개하고 있긴 하나, 서로 배타적인 것은 아닙니다. 즉 어느 때에라도, 작성자가 어떤 과정에서 다른 과정으로 어떤 문제도 없이 바꿀 수 있다는 뜻입니다. 모든 방법은 다음 규칙을 따르기 때문입니다.
작성자 저장소의 임시 분기에 수정 사항을 적용합니다.
작성자의 변경 사항을 적용한 다음 풀 요청(PR; pull request)을 통해 주 문서로 합치도록 요청합니다.
다른 개발자들이 변경 사항을 리뷰하고 토의해서, 아무 문제도 없을 경우 주 분기에 작성자의 작업 내용을 통합합니다.
작성자가 복사한 저장소에서, 주 문서로 변경 사항을 제안할 수 있습니다. GitHub 웹 인터페이스를 통해 쉽게 작업할 수 있습니다.
파일을 편집하고, 작성자의 변경 사항을 평가하고 제출(commit)할 수 있습니다.
주 저장소에 작성자의 변경 사항을 삽입하도록 풀 요청을 전달할 수 있습니다.
분기를 생성하거나, 업데이트하거나, 삭제할 수 있습니다.
다음 단락에서 이용할 몇몇 기본 용어 및 액션을 숙지하기 위해 GitHub Hello-world 프로젝트를 읽어보시기 바랍니다.
https://github.com/qgis/QGIS-Documentation/issues 에 보고된 문제점들 또는 작성자가 문서를 읽다가 발견한 문제점들을 다룬다면 문서를 향상시킬 수 있습니다. 문제점들은 서로 다른 유형일 수 있겠죠. 오타, 도형 누락, 잘못 됐거나 업데이트 안 된 설명...
작성자가 수정하려 하는 문제점 을 선택하십시오. 많은 사람들이 동일한 문제점을 동시에 수정하려 하는 사태를 피하기 위해, 문제점 보고에 코멘트를 달고 스스로에게 할당해서 기고자들에게 작성자가 어떤 문제점을 선택했는지 알려줄 수 있습니다.
작성자의 저장소에서, 어떤 문제점을 수정할 것인지 알려줄 명칭으로 분기를 생성(해서 전환)하십시오.
소스 파일들을 탐색해서 변경해야 할 파일을 찾으십시오.
연필 아이콘을 사용해서 파일을 편집 모드로 토글한 다음, 문서 작성 지침 에 따라 수정하십시오.
Commit Changes 양식을 채워 작성자의 변경 사항을 승인한 다음, 작성자의 분기로 직접 커밋하십시오.
문제점을 해결하기 위해 업데이트해야 하는 다른 파일에 대해서도 이 단계들을 반복하십시오.
QGIS 프로젝트는 온라인 문서에서 소스 파일로 접근할 수 있는 쉬운 방법을 제공합니다. 실제로, 문제점을 수정할 수 있는 파일을 찾기 위해 GitHub에 있는 소스 파일들을 뒤지는 대신, 사용자 설명서를 읽는 동안 문제점을 발견했을 때 해당 페이지 하단에 있는 “현재 페이지 수정” 링크를 클릭하기만 하면 해당 소스 파일을 편집 모드로 열 수 있습니다.
이때 열리는 파일은 qgis:master 분기에 있는 파일로, 페이지 상단에 작성자는 이 저장소에 대한 작성 권한이 없으며 작성자가 변경한 내용은 작성자의 저장소에 새로운 분기로 저장될 것이라는 메시지가 뜰 것입니다.
http://docs.qgis.org/testing/en/docs/documentation_guidelines/ 에서 찾아볼 수 있는 문서 작성 지침에 따라 문서를 수정하십시오.
수정 작업이 끝나면, 페이지 하단에 작성자가 변경한 내용에 대해 간단히 설명하는 코멘트를 작성한 다음 Propose File change 를 클릭하십시오. 작성자의 저장소에 새 분기(patch-xxx)를 생성할 것입니다.
참고
작성자의 master 분기가 qgis:master 와 동일한 상태일 경우, 링크의 qgis 를 안전하게 <YourName> 로 대체할 수 있습니다. 이 경우, 작성자가 수정 작업을 완료했을 때, Create a new branch for this commit and start a pull request 를 체크해서 master 가 수정되는 일을 피해야 합니다.
GitHub 웹 인터페이스는 저장소에 작성자의 기고 내용을 쉽게 업데이트하도록 도와주지만, 다음과 같은 도구들을 제공하진 않습니다.
작성자의 커밋을 그룹화하고 변경 이력을 삭제
필요할 경우 주 저장소와의 충돌을 해결
작성자의 변경 사항을 테스트하기 위한 문서를 빌드
더 강력하고 더 고급인 도구에 접근하려면 그리고 저장소의 로컬 사본을 보유하려면 먼저 작성자의 하드드라이브에 Git을 설치 해야 합니다. 작성자가 자주 필요로 할 몇몇 기본 사항들을 다음 단락에서 소개합니다. 웹 인터페이스를 사용하기로 결정한 경우에도 신경 써야 할 규칙들도 함께 찾을 수 있을 겁니다.
다음에 나오는 코드 예시에서, # 로 시작하는 줄은 주석을 의미하지만 $ 로 시작하는 줄은 작성자가 입력해야 하는 명령어를 나타냅니다.
이제 작성자의 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
주석
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
이제 작성자는 QGIS.org의 QGIS 문서와 동일한 master 분기를 보유한 로컬 및 원격 저장소를 얻었습니다. 문서를 작성하기 시작할 수 있습니다.
문서를 테스트하는 동시에, QGIS 2.14 문서의 문제점들을 해결해 나갑니다. 즉 변경 내용을 반영할 수 있다는 뜻입니다. 앞 단락의 예시 코드를 따르면, 대응하는 분기를 선택해서 쉽게 작업할 수 있습니다.
저장소를 복사할 경우 (로컬 저장소 참조) 작성자의 복사본은 upstream 저장소의 모든 분기들을 보유하게 됩니다. 앞의 내용처럼, 작성자는 자신의 분기가 upstream 의 분기와 동일한지 확인해야 합니다.
# 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
이런 방법으로 2.14 버전에 대한 작성자의 로컬 및 원격 분기를 공식 upstream 저장소의 분기와 동일하게 유지할 수 있습니다.
이제 작성자의 기반 분기가 업데이트됐으니, 작성 내용을 추가할 전용 분기를 생성해야 합니다. 언제나 기반 분기가 아닌 다른 분기에서 작업하십시오! 언제나요!
$ 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
작성자의 풀 요청이 공식 QGIS 문서에 통합된 다음, 작성자의 분기를 삭제할 수 있습니다. 이런 방식으로 많은 작업을 하는 경우, 몇 주만 지나도 쓸데없는 분기들을 많이 보유하게 될 겁니다. 따라서 다음 방법을 통해 작성자의 저장소를 말끔히 유지하십시오.
# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch
그리고 작성자의 로컬 저장소에 있는 master 분기를 업데이트하는 것도 잊지 마십시오!