중요
번역은 여러분이 참여할 수 있는 커뮤니티 활동입니다. 이 페이지는 현재 100.00% 번역되었습니다.
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.5. 작성자의 병합된 분기 삭제
작성자의 변경 사항이 병합됐다면, 해당 분기를 삭제해도 됩니다. 목적을 다 한 분기를 삭제하면 사용자 저장소에 사용되지 않거나 이전 버전인 분기를 유지하지 않아도 됩니다.
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 명령 줄 도구가 있습니다. 자세한 내용은 명령줄에서 깃 다시 지정 사용 을 확인하세요.