1. 단계별 공헌 방법
참고
이 과정을 설명하는 데 QGIS 문서를 예로 들긴 했지만, 다음 단락부터 보여줄 모든 명령어 및 단계는 QGIS 웹사이트에도 적용할 수 있습니다.
이 문서를 읽고 있다는 사실은 당신이 QGIS 문서 작성에 공헌할 마음을 가지고 있으며, 그 방법을 찾고 있다는 것이겠죠. 잘 오셨습니다! 이 문서는 QGIS 문서 작성이라는 목표를 달성하기 위한 여러 가지 방법을 알려드리고, 따라야 할 주요 단계와 당신이 사용할 수 있는 요령들 및 주의해야 할 함정들을 보여드릴 것입니다.
도움이 필요하다면 주저하지 말고 당신이 고치려 하는 문제점 보고서에 코멘트를 남겨 질문하거나 QGIS 커뮤니티 팀 메일링 리스트 에 문의하십시오. 자세한 내용은 문서 작성하기 를 참조하세요.
이제 시작해보겠습니다.
문서 소스는 git 버전 제어 시스템을 통해 저장되며 GitHub 에서 사용할 수 있습니다. 고쳐야 할 문제 및 설명해야 할 기능들의 목록은 https://github.com/qgis/QGIS-Documentation/issues 에서 찾아볼 수 있습니다.
팁
당신이 처음으로 공헌을 결심했기 때문에 어디에서부터 시작할지 잘 모르겠다면, 문제점 보고서 에 도전해보는 것도 좋을 겁니다.
문서 파일을 수정하는 데에는 결코 상호 배타적이 아닌 두 가지 주요 방법이 있습니다:
1.1. GitHub 웹 인터페이스 사용하기
GitHub 웹 인터페이스에서 다음과 같은 작업을 실행할 수 있습니다:
파일 편집
변경 사항 미리보기 및 커밋(commit)
주 저장소에 작성자의 변경 사항을 삽입하도록 끌어오기 요청 생성
분기(branch) 생성, 업데이트, 또는 삭제
아직 git 및 GitHub의 전문 용어에 익숙하지 않다면, 다음 단락부터 이용할 몇몇 기본 용어 및 액션을 숙지하기 위해 GitHub Hello-world 프로젝트를 읽어보시기 바랍니다.
참고
보고된 문제점을 고치려면
문제점 를 고치기 위해 변경 사항을 생성하는 경우, 자신에게 해당 문제점을 할당하기 위해 문제점 보고서에 코멘트를 추가하십시오. 여러 사람이 동시에 동일한 문제를 작업하는 일을 방지할 것입니다.
1.1.1. QGIS-Documentation 포크(fork)
당신이 이미 GitHub 계정 을 가지고 있다고 가정하고, 가장 먼저 해야 할 일은 문서 소스 파일을 포크(fork)하는 것입니다.
QGIS-Documentation 저장소 페이지로 가서 우상단에 있는 
버튼을 클릭하십시오.
당신의 GitHub 계정에서 QGIS-Documentation 저장소(https://github.com/<YourName>/QGIS-Documentation)를 찾을 수 있을 것입니다. 이 저장소는 공식 QGIS-Documentation 저장소의 복사본으로, 공식 문서에 영향을 주는 일 없이 완전한 작성 권한으로 변경 사항을 작성할 수 있습니다.
1.1.2. 변경 사항 작성
QGIS 문서에 기고하는 데엔 여러 가지 방법이 있습니다. 다음 단락에 각각의 방법을 소개하고 있기는 하지만, 작성자가 한 과정에서 다른 과정으로 어떤 문제도 없이 바꿀 수 있습니다.
대안 1: Edit on GitHub 단축키 사용하기
QGIS 문서 웹사이트에 있는 페이지의 우상단에 있는 Edit on GitHub 링크를 클릭하면 각 페이지를 쉽고 빠르게 편집할 수 있습니다.
이때 열리는 파일은
qgis:master분기에 있는 파일로, 페이지 상단에 작성자는 이 저장소에 대한 작성 권한이 없으며 작성자가 변경한 내용은 작성자의 저장소에 새로운 분기로 저장될 것이라는 메시지가 뜰 것입니다.변경 사항을 작성하십시오. reStructureText 문법을 사용해서 문서를 작성하기 때문에, 당신이 작성하는 변경 사항에 따라 문서 작성 지침 을 따라야 할 경우도 있습니다.
수정 작업이 끝나면, 작성자가 변경한 내용에 대해 간단히 설명하는 코멘트를 작성한 다음 Propose changes 를 클릭하십시오. 작성자의 저장소에 새 분기 (
patch-xxx)를 생성할 것입니다.Propose changes 를 클릭하면 GitHub가 Comparing changes 페이지로 이동할 것입니다.
변경 사항 작성을 완료했다면, 아래에 있는 끌어오기 요청을 통해 변경 사항 공유 부분 아래 있는 변경 사항 비교 로 건너뛰십시오.
작성자가 QGIS에 변경 사항을 커밋하기 전에 추가로 변경하고자 하는 사항이 있다면, 다음 단계를 따르십시오:
작성자의 QGIS-Documentation 포크(
https://github.com/<YourName>/QGIS-Documentation)로 가십시오.
버튼을 클릭한 다음 patch-xxx분기를 검색하십시오. 해당 분기를 선택하십시오. 버튼의 텍스트가 Branch: patch-xxx 로 변했을 것입니다.아래 있는 파일 수정하기 로 넘어가십시오.
참고
왼쪽 사이드바 하단에 있는 드롭다운 메뉴에서도 Edit on GitHub 단축키를 사용할 수 있습니다.
대안 2: 작성자의 문서 저장소에 애드혹(ad hoc) 분기 생성하기
QGIS 문서의 작성자 포크(fork)에서 파일을 직접 편집할 수 있습니다.
먼저, 사용자의 master 분기가 qgis:master 분기의 최신 상태와 일치하는지 확인하십시오. 이를 확인하려면:
예를 들어
https://github.com/<YourName>/QGIS-Documentation같은 사용자 저장소의 메인 페이지로 가십시오.master분기가 활성화되어qgis/QGIS-Documentation:master분기의 최신 상태와 일치하는지를 알려줄 것입니다.업스트림 분기보다 앞서 커밋한 경우 사용자의
master브랜치를 정렬할 때까지 이전 :ref:`대안 단축키 버튼 <edit_on_github>``을 사용하는 편이 좋습니다.뒤쳐진 커밋만 있는 경우:
오른쪽에 있는 Fetch Upstream 드롭다운 메뉴를 펼치십시오. 다음 작업을 할 수 있습니다:
Compare: 분기들을 비교해서 메인 저장소의 새로운 변경 사항들을 볼 수 있습니다.
Fetch and merge: 업스트림 분기로부터 사용자 분기로 변경 사항들을 가져올 수 있습니다.
Fetch and merge 를 클릭해봅시다. 처리 과정이 끝나면 사용자 분기가
qgis/QGIS-Documentation:master분기의 최신 상태와 일치한다고 표시됩니다.
작성자의 QGIS 문서 저장소의 좌상단에 있는
버튼을 클릭하고 텍스트란에 유일한 이름(unique name)을 입력해서 새 분기(branch) 를 생성하십시오. 새 분기의 이름은 작성자가 해결하고자 하는 문제점과 관련이 있어야 합니다. 이제 버튼이 Branch: branch_name 으로 보일 것입니다.이제 사용자 분기에 새로운 변경 사항을 적용할 준비가 끝났습니다.
주의
절대 master 분기를 변경하지 말고, 애드혹 분기를 변경하십시오.
qgis/QGIS-Documentation 의 master 분기의 수정 사항을 작성자의 QGIS 문서 저장소의 복사본으로 병합하는 경우를 제외하면 master 분기를 변경하지 마십시오. 개별 분기들을 구분하면, 다른 분기들을 건드리지 않고 동시에 여러 문제점을 작업할 수 있습니다. 실수가 발생한 경우 언제나 해당 분기를 삭제하고 마스터 분기에서 새 분기를 생성해서 다시 시작할 수 있습니다.
1.1.3. 파일 수정
QGIS 문서의 작성자 포크의 소스 파일 가운데 수정해야 할 파일을 탐색하십시오.
:ref:` 문서 작성 지침 <QGIS-documentation-guidelines>` 에 따라 수정하십시오.
수정 작업이 끝나면 페이지 하단에 있는 Commit Changes 프레임으로 가서 작성자가 수정한 사항에 대해 간단한 주석을 작성한 다음, Commit Changes 를 클릭해서 작성자 분기에 변경 사항을 직접 커밋하십시오. Commit directly to the branch_name branch. 옵션을 선택했는지 확인하세요.
문제점을 해결하기 위해 업데이트해야 하는 다른 파일에 대해서도 이 단계들을 반복하십시오.
1.1.4. 끌어오기 요청을 통해 변경 사항 공유
공식 문서에 작성자의 변경 사항을 통합시키려면 끌어오기 요청(pull request)을 생성해야 합니다.
참고
Edit on GitHub 링크를 사용한 경우
작성자가 변경 사항을 커밋하면, 깃허브(GitHub)가 작성자의 patch-xxx 분기에서 변경된 사항을 qgis/QGIS-Documentation 마스터 분기와 비교하는 새 페이지를 자동적으로 열 것입니다.
다음 두 번째 단계 로 넘어가십시오.
새 끌어오기 요청 생성
QGIS-Documentation 저장소의 메인 페이지로 가서 New pull request 를 클릭하십시오.
변경 사항 비교
하나는 base:master 이고 다른 하나는 compare:branch_name 인 2개의 대화 상자가 나타난다면 (id7 참조) 작성자 분기 가운데 하나의 변경 사항을 작성자의 마스터 분기로 병합시킬 뿐입니다. 이를 바꾸려면 compare across forks 링크를 클릭하십시오.
그림 1.1 작성자의 Comparing changes 페이지가 이렇게 보일 경우 compare across forks 링크를 클릭
4개의 드롭다운 메뉴가 나타날 것입니다. 이 메뉴들을 통해 작성자 분기의 변경 사항을, 병합시키고자 하는 마스터 분기와 비교할 수 있습니다. 이 드롭다운 메뉴는 다음과 같습니다:
base fork: 작성자 변경 사항을 병합시키고자 하는 포크
base: 작성자 변경 사항을 병합시키고자 하는 기반 포크(base fork)의 분기
head fork: 작성자가 기반 포크로 통합하려 하는 변경 사항이 있는 포크
compare: 해당 변경 사항을 가진 분기
qgis/QGIS-Documentation 을 base fork 로, master 를 base 로 선택하고, 작성자 저장소 <YourName>/QGIS-Documentation 을 head fork 로, 작성자가 변경한 분기를 compare 로 설정하십시오.
그림 1.2 qgis/QGIS-Documentation 과 작성자 저장소 사이의 변경 사항 비교
녹색 Able to merge 체크 표시는 작성자의 변경 사항을 문제없이 공식 문서로 병합시킬 수 있다는 사실을 나타냅니다.
Create pull request 버튼을 클릭하십시오.
경고
표시가 나타난 경우
충돌(conflict) 이 일어났다는 뜻입니다. 다른 누군가가 작성자의 변경 사항과 충돌을 일으키는 내용을 커밋했기 때문에 작성자가 수정한 파일이 병합시키고자 하는 분기와 버전이 맞지 않는 것이죠. 그래도 끌어오기 요청을 생성할 수는 있지만 병합을 완료하려면 모든 충돌 을 해소해줘야 할 것입니다.
팁
번역 중에도, QGIS 문서의 최신 버전 은 계속 유지보수되며 기존 문제점들을 해결하고 있습니다. 다른 배포판의 문제점을 해결하는 중이라면, 앞의 단계들에서 base 를 master 에서 적절한 release_... 분기로 바꾸십시오.
작성자의 끌어오기 요청을 설명
텍스트란이 나타날 것입니다. 작성자가 제기하는 문제점과 관련된 주석을 작성하십시오.
혹시 특정한 기존 문제점 과 관련된 내용일 경우, 주석에 문제점 번호를 넣어주세요. #과 함께 문제점 번호를 (예: #1234) 입력하면 됩니다. fix 또는 close 같은 용어를 앞에 넣어주면, 끌어오기 요청이 병합되는 대로 해당 문제점은 종결될 것입니다.
작성자가 변경하는 모든 문서 페이지를 가리키는 링크들도 추가해주세요.
Create pull request 를 클릭하십시오.
끌어오기 요청 검토 및 논평
앞에서 설명한 대로, 누구나 끌어오기 요청을 통해 문서에 수정 사항을 제출할 수 있습니다. 마찬가지로 누구나 끌어오기 요청에 대해 검토하고 질문을 하거나 논평 할 수 있습니다. 문서 작성 스타일이 프로젝트의 지침과 맞지 않을 수도 있고, 변경 사항에 일부 중요한 세부 내용이나 스크린샷이 누락됐을 수도 있고, 또는 모든 것이 제대로 되어 있을 수도 있습니다. 검토 및 논평은 형식과 내용 모든 관점에서 기고 내용의 질을 향상시키는 데 도움이 됩니다.
끌어오기 요청을 검토하려면:
끌어오기 요청 페이지 로 가서 작성자가 논평하고 싶은 PR(pull request)을 클릭하십시오.
페이지 하단에 작성자가 끌어오기 요청에 대해 일반적인 논평을 남길 수 있는 텍스트란이 있을 것입니다.
특정 행에 대한 논평을 남기고 싶다면,
버튼을 클릭하고 논평하고자 하는 파일을 찾으십시오. 변경 사항을 보려면 Display the source diff 를 클릭해야 할 수도 있습니다.작성자가 논평을 남기고 싶은 행으로 스크롤한 다음
아이콘을 클릭하십시오. 작성자가 논평을 남길 수 있는 텍스트란이 열릴 것입니다.
특정 행에 대한 논평은 다음 두 가지 방법으로 제출할 수 있습니다:
단일 논평이라면 Add single comment 버튼을 사용하십시오. 그대로 공개될 것입니다. 짧은 논평이거나, 다른 논평에 대한 댓글일 경우에만 이 버튼을 사용하세요.
검토의 일부라면, Start a review 버튼을 클릭하십시오. 작성자의 논평이 확인(validation) 과정을 거친 후 자동으로 공개되지 않기 때문에, 버튼을 클릭한 다음에도 논평을 편집하거나 취소하거나 주요 검토 내용 또는 끌어오기 요청에 대한 전반적인 지침의 개요를 추가하거나 작성자가 해당 끌어오기 요청의 내용을 찬성하는지 반대하는지 밝힐 수도 있습니다. 작성자가 자신의 검토 내용을 더 잘 구성할 수 있고, 논평을 편집할 수 있고, 스스로 준비됐을 때 공개할 수 있으며 저장소 팔로워들에게 각 논평마다 알림을 보내는 것이 아니라 단일 알림을 보낼 수 있기 때문에 더 유연하고 편리한 방법입니다. 더 자세한 내용 을 참조하세요.
그림 1.3 특정 라인에 변경 사항을 제안하는 논평
행 논평에는 끌어오기 요청 작성자가 끌어오기 요청에 적용할 수도 있는 제안을 내장시킬 수 있습니다. 제안을 추가하려면, 논평 텍스트란 위에 있는 
Insert a suggestion 버튼을 클릭하고 제안 블록 안에서 텍스트를 수정하십시오.
팁
작성자의 끌어오기 요청에 제안을 배치(batch) 프로세스로 커밋하는 것을 선호
끌어오기 요청 작성자로서, 작성자의 끌어오기 요청에 검토자의 피드백을 직접 통합시킬 때 고려해야 할 제안들이 많아 배치 프로세스로 추가하는 편이 좋은 경우, 논평 텍스트란 하단에 있는 Commit suggestion 버튼을 사용하지 말고:
- 탭으로 전환하십시오.
작성자가 포함시키고 싶은 각 변경사항마다 Add suggestion to batch 를 클릭하십시오. 추가할 때마다 숫자가 올라가는 것을 볼 수 있습니다.
작성자의 끌어오기 요청에 제안들을 적용할 준비가 끝나면 Commit suggestions 버튼을 누른 다음, 변경 사항에 대한 설명을 입력하십시오.
이렇게 하면 작성자 분기에 모든 수정 사항을 커밋 한번으로 추가할 것입니다. 변경 사항 이력도 더 알아보기 쉽고, 저장소 팔로워들에게 가는 알림도 줄어듭니다. 의도하지는 않았지만, 작성자가 클릭해야 하는 횟수도 줄어들 겁니다.
수정 작업
새 끌어오기 요청은 자동적으로 끌어오기 요청(pull request) 목록 에 추가될 것입니다. 다른 편집자들과 운영자들이 작성자의 PR을 검토해서 제안을 커밋하거나 수정을 요구할 수도 있습니다.
끌어오기 요청은 자동화된 빌드 점검도 (예: rst(reStructuredText) 서식 작업의 경우 파이썬 코드 문법을 점검) 촉발할 것입니다. 점검 보고서는 페이지 하단에 표시됩니다. 오류를 발견했을 경우, 작성자의 커밋(commit) 옆에 빨간 가위표가 나타날 것입니다. 이 빨간 가위표 또는 끌어오기 요청 페이지 하단의 요약 부분에 있는 Details 를 클릭하면 오류의 세부 정보를 볼 수 있습니다. 보고된 모든 오류 또는 경고를 해결해야 qgis/QGIS-Documentation 저장소에 작성자의 변경 사항을 커밋할 수 있습니다.
작성자의 끌어오기 요청이 메인 저장소와 병합되기 전까지, 작성자의 끌어오기 요청을 향상시키거나 요구받은 수정 사항을 적용하거나 빌드 오류를 해결하기 위해 끌어오기 요청을 수정할 수 있습니다.
끌어오기 요청을 변경하려면 작성자의 끌어오기 요청 페이지의 탭을 클릭한 다음 수정하고자 하는 파일명 옆에 있는 
연필 버튼을 클릭하십시오.
작성자의 끌어오기 요청에서 커밋한 것과 동일한 분기를 변경하는 경우, 추가한 변경 사항이 끌어오기 요청에 자동적으로 추가될 것입니다. 따라서, 작성자가 해당 끌어오기 요청으로 해결하려는 문제에 관련되었을 경우에만 변경 사항을 추가해야 합니다.
또다른 문제점을 해결하고 싶다면, 해당 변경 사항을 위한 새 분기를 생성한 다음 앞의 단계를 반복하십시오.
모든 빌드 오류가 수정되고 작성자와 운영자가 작성자의 변경 사항에 대해 만족한 다음에야 운영자가 작성자의 기고 내용을 병합할 것입니다.
1.1.5. 작성자의 병합된 분기 삭제
작성자의 변경 사항이 병합됐다면, 해당 분기를 삭제해도 됩니다. 목적을 다 한 분기를 삭제하면 사용자 저장소에 사용되지 않거나 이전 버전인 분기를 유지하지 않아도 됩니다.
QGIS 문서 저장소의 사용자 포크(
https://github.com/<YourName>/QGIS-Documentation)로 가십시오.Branches 탭을 클릭하십시오. Your branches 아래 사용자 분기 목록이 있을 겁니다.
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
팁
권한 거부 (퍼블릭키) 오류?
앞의 명령어로 권한 거부 (퍼블릭키) 오류가 반환됐다면 작성자의 SSH 키에 문제가 있을 수 있습니다. 자세한 내용은 깃허브 도움말 을 참조하십시오.
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
여기서 작업을 시작해도 괜찮지만, 길게 봤을 때 작성자의 작업 내용을 밀어낼 경우 (깃허브 처리 과정에서는 끌어오기 요청이라고 합니다) 작성자의 로컬/원격 저장소에서 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를 입력하십시오. 작성자의 커밋이 해당 티켓을 폐지할 것입니다.
작성자의 로컬 분기에 변경 사항을 저장하고 커밋했으니, 이제 끌어오기 요청을 생성하기 위해 변경 사항을 작성자의 원격 저장소에 전달해야 합니다:
$ git push origin myNewBranch
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 응용 프로그램 도 있습니다.
끌어오기 요청의 변경 사항이 최근 대상 분기에 밀어낸 변경 사항과 충돌을 일으키는 경우, 병합할 수 있으려면 먼저 충돌을 해소해야 합니다:
서로 경쟁 관계에 있는 몇몇 행에 관련된 충돌인 경우, 깃허브 끌어오기 요청(pull request) 페이지에 있는 Resolve conflicts 버튼을 사용할 수 있습니다. 이 버튼을 클릭하면 깃허브에서 병합 충돌 해결 에서 설명하는 대로 문제점을 해결합니다.
파일 재명명 또는 제거에 관련된 충돌인 경우, git 명령 줄을 사용해서 충돌을 해소해야 합니다. 일반적으로, 먼저
git rebase targetBranch호출을 이용해서 대상 분기를 사용자 분기 기반으로 새로 설정하고 보고된 충돌을 해결해야 합니다. 명령줄을 사용하여 병합 충돌 해결 에서 더 자세한 내용을 읽어보십시오.
때때로, 퇴고 과정의 끝자락에서 그럴 필요가 없는 데도 커밋 여러 개로 갈라진 변경 사항을 발견할 수도 있습니다. 이런 커밋들을 더 적은 개수와 더 의미 있는 커밋 메시지로 압축할 수 있는 git 명령 줄 도구가 있습니다. 자세한 내용은 명령줄에서 깃 다시 지정 사용 을 확인하세요.