Outdated version of the documentation. Find the latest one here.

단계별 기고 방법

주석

이번 과정을 설명하는 데 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 문서에 기고하는 데엔 여러 가지 방법이 있습니다. 다음 단락에서 각각의 방법을 소개하고 있긴 하나, 서로 배타적인 것은 아닙니다. 즉 어느 때에라도, 작성자가 어떤 과정에서 다른 과정으로 어떤 문제도 없이 바꿀 수 있다는 뜻입니다. 모든 방법은 다음 규칙을 따르기 때문입니다.

  1. 작성자 저장소의 임시 분기에 수정 사항을 적용합니다.

  2. 작성자의 변경 사항을 적용한 다음 풀 요청(PR; pull request)을 통해 주 문서로 합치도록 요청합니다.

  3. 다른 개발자들이 변경 사항을 리뷰하고 토의해서, 아무 문제도 없을 경우 주 분기에 작성자의 작업 내용을 통합합니다.

GitHub 웹 인터페이스 사용

작성자가 복사한 저장소에서, 주 문서로 변경 사항을 제안할 수 있습니다. GitHub 웹 인터페이스를 통해 쉽게 작업할 수 있습니다.

  • 파일을 편집하고, 작성자의 변경 사항을 평가하고 제출(commit)할 수 있습니다.

  • 주 저장소에 작성자의 변경 사항을 삽입하도록 풀 요청을 전달할 수 있습니다.

  • 분기를 생성하거나, 업데이트하거나, 삭제할 수 있습니다.

다음 단락에서 이용할 몇몇 기본 용어 및 액션을 숙지하기 위해 GitHub Hello-world 프로젝트를 읽어보시기 바랍니다.

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

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

대안 1: 목록에서 문제점 선택

  1. 작성자가 수정하려 하는 문제점 을 선택하십시오. 많은 사람들이 동일한 문제점을 동시에 수정하려 하는 사태를 피하기 위해, 문제점 보고에 코멘트를 달고 스스로에게 할당해서 기고자들에게 작성자가 어떤 문제점을 선택했는지 알려줄 수 있습니다.

  2. 작성자의 저장소에서, 어떤 문제점을 수정할 것인지 알려줄 명칭으로 분기를 생성(해서 전환)하십시오.

  3. 소스 파일들을 탐색해서 변경해야 할 파일을 찾으십시오.

  4. 연필 아이콘을 사용해서 파일을 편집 모드로 토글한 다음, 문서 작성 지침 에 따라 수정하십시오.

  5. Commit Changes 양식을 채워 작성자의 변경 사항을 승인한 다음, 작성자의 분기로 직접 커밋하십시오.

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

대안 2: 현재 페이지 수정 바로가기 사용

QGIS 프로젝트는 온라인 문서에서 소스 파일로 접근할 수 있는 쉬운 방법을 제공합니다. 실제로, 문제점을 수정할 수 있는 파일을 찾기 위해 GitHub에 있는 소스 파일들을 뒤지는 대신, 사용자 설명서를 읽는 동안 문제점을 발견했을 때 해당 페이지 하단에 있는 “현재 페이지 수정” 링크를 클릭하기만 하면 해당 소스 파일을 편집 모드로 열 수 있습니다.

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

  2. http://docs.qgis.org/testing/en/docs/documentation_guidelines/ 에서 찾아볼 수 있는 문서 작성 지침에 따라 문서를 수정하십시오.

  3. 수정 작업이 끝나면, 페이지 하단에 작성자가 변경한 내용에 대해 간단히 설명하는 코멘트를 작성한 다음 Propose File change 를 클릭하십시오. 작성자의 저장소에 새 분기(patch-xxx)를 생성할 것입니다.

참고

작성자의 master 분기가 qgis:master 와 동일한 상태일 경우, 링크의 qgis 를 안전하게 <YourName> 로 대체할 수 있습니다. 이 경우, 작성자가 수정 작업을 완료했을 때, radioButtonOn Create a new branch for this commit and start a pull request 를 체크해서 master 가 수정되는 일을 피해야 합니다.

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

이제, 작성자는 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-Documentationmaster 를 선택했는지 확인하고, 헤드 포크(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. 원한다면, 작성자의 저장소가 너무 많은 (사용되지 않고 오래된) 분기들로 넘쳐나는 일을 피하기 위해 작성자가 사용했던 분기를 삭제할 수 있습니다.

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

경고

작성자 자신의 master 분기가 아니라 qgis:master 분기에 풀 요청을 전달하도록 주의해야 합니다. 그렇지 않으면 작성자의 변경 사항을 아무도 모를 것이며, 스스로의 변경 사항을 실수로 자신의 master 분기로 통합, 문서 이력을 망칠 수도 있습니다.

참고

풀 요청으로부터 자동적으로 문제점 보고를 폐지합니다.

문제점 보고 관리를 손쉽게 하기 위해, 작성자의 풀 요청에 작성자가 다루고 있는 문제점의 번호를 언급해주십시오. #문제점_번호 양식을 이용하면 됩니다. fix, close... 와 같은 용어 뒤에 번호를 삽입하면, 풀 요청이 통합되는 대로 해당 문제점을 폐지할 겁니다.

Git 명령 프롬프트 도구 이용

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

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

  • 필요할 경우 주 저장소와의 충돌을 해결

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

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

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

로컬 저장소

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

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

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

참고

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

권한 거부 (퍼블릭키) 오류가 반환됐다면 작성자의 SSH 키에 문제가 있을 수 있습니다. 자세한 내용은 GitHub 도움말 을 참조하십시오.

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

$ 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 은 라벨일 뿐으로, 일종의 표준 명칭이지만 원하는 대로 명명할 수 있습니다.

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

테스트용 (master 분기) 문서의 경우

새 작성 작업을 시작하기 전에, 항상 작성자의 로컬 저장소에 있는 로컬 마스터 분기를 업데이트해야 합니다. 다음 명령어를 수행하십시오.

# 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 분기를 보유한 로컬 및 원격 저장소를 얻었습니다. 문서를 작성하기 시작할 수 있습니다.

배포판 (manual_en_ 분기) 문서의 경우

문서를 테스트하는 동시에, 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

작성자의 변경 사항 공유

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

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

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

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

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