1. 공헌단계¶
참고
이번 과정을 설명하는 데 QGIS 문서를 예로 들긴 했지만, 다음 단락부터 보여줄 모든 명령어 및 단계는 QGIS 웹사이트에도 적용할 수 있습니다.
이 라인을 읽고 있다는것은 QGIS 문서와 방법을 고려하고 있다는것입니다. 정확하게 오셨습니다! 현재문서는 다양한 방식으로 목적을 달성하기위해 도와드리며 고려할 사항을 알려드립니다.
도움이 필요하시면 문제리포트에 코맨트를 남기거나 〈QGIS-커뮤니티팀 목록 <https://lists.osgeo.org/mailman/listinfo/qgis-community-team>〉_에 쓰십시오. 자세한 내용은 <https://qgis.org/en/site/getinvolved/document.html>를 참조하십시오.
과정으로 이동하겠습니다.
문서의 원본은 https://github.com/qgis/QGIS-Documentation에 GitHub에 git 버전으로 저장되어 있습니다. 파일을 수정하는 방식은 다음 두가지입니다:
GitHub 웹인터페이스 1 사용
Git 커맨드라인툴 1 사용.
1.1. GitHub 웹인터페이스 사용¶
GitHub 웹인터페이스에서 실행할 수 있는 작업:
파일편집
변경사항 미리보기와 코맨트
메인 저장소에 삽입할 변경사항을 요청
브랜치 생성, 업데이트 삭제
git와 GitHub 어휘에 익숙하지 않다면 GitHub 〈Hello-world <https://guides.github.com/activities/hello-world/>〉_프로젝트에서 아래에서 사용할 기본적인 어휘와 액션을 학습하십시오.
참고
보고된 이슈을 수정하려면
〈문제점 <https://github.com/qgis/QGIS- Documentation/issue>〉_를 수정하려면 코맨트를 자신의 이슈리포트에 적용하십시오. 동일한 문제를 여러사람이 해결하려는것을 방지할 수 있습니다.
1.1.1. 1. Fork QGIS-Documentation¶
Assuming you already have a GitHub account, you first need to fork the source files of the documentation.
Navigate to the QGIS-Documentation repository page and click on the
button in the upper right corner.
In your GitHub account you will find a QGIS-Documentation repository
(https://github.com/<YourName>/QGIS-Documentation
).
This repository is a copy of the official QGIS-Documentation repository where
you have full write access and you can make changes without affecting the
official documentation.
1.1.2. 2. Make changes¶
There are different ways to contribute to QGIS documentation. We show them separately below, but you can switch from one process to the other without any harm.
1.1.2.1. Alternative 1: Use the Edit on GitHub
shortcut¶
Pages on the QGIS documentation website can be edited quickly and easily by clicking on the
Edit on GitHub
link at the top right of each page.
This will open the file in the
qgis:master
branch with a message at the top of the page telling you that you don’t have write access to this repo and your changes will be applied to a new branch of your repository.Do your changes. Since the documentation is written using the reStructureText syntax, depending on your changes, you may need to rely on the writing guidelines.
When you finish, make a short comment about your changes and click on Propose changes. This will generate a new branch (
patch-xxx
) in your repository.After you click on Propose changes, github will navigate to the Comparing changes page.
If you’re done making changes, skip to Compare changes in the Share your changes via Pull Request section below.
If there are additional changes that you want to make before submitting them to QGIS, follow these steps:
Navigate to your fork of QGIS-Documentation (
https://github.com/<YourName>/QGIS-Documentation
)Click on
and search for the
patch-xxx
branch. Select this patch branch. Thebutton will now say Branch: patch-xxx
Jump down to Modify files below.
참고
The Edit on GitHub
shortcut is also available in the drop-down
menu at the bottom of the left sidebar.
1.1.2.2. Alternative 2: Create an ad hoc branch in your documentation repository¶
You can edit files directly from your fork of the QGIS Documentation.
Click on in the upper left corner of your forked QGIS-
Documentation repository and enter a unique name in the text field to create a
new branch .
The name of the new branch should relate to the problem you intend to fix. The
button should now say Branch: branch_name
팁
Do your changes in an ad hoc branch, never in the master
branch
By convention, avoid making changes in your master
branch except when
you merge the modifications from the master
branch of qgis/QGIS-Documentation
into your copy of the QGIS-Documentation repository.
Separate branches allow you to work on multiple problems at the same time
without interfering with other branches. If you make a mistake you can
always delete a branch and start over by creating a new one from the master
branch.
1.1.3. 3. Modify files¶
Browse the source files of your fork of QGIS-Documentation to the file that needs to be modified
Make your modifications following the writing guidelines
When you finish, navigate to the Commit Changes frame at the bottom of the page, make a short comment about your changes, and click on Commit Changes to commit the changes directly to your branch. Make sure Commit directly to the branch_name branch. is selected.
Repeat the previous steps for any other file that needs to be updated to fix the issue
1.1.5. 5. Delete your merged branch¶
You can delete the branch after your changes have been merged. Deleting old branches saves you from having unused and outdated branches in your repository.
1.2. Git 명령 프롬프트 도구 이용¶
The GitHub web interface is an easy way to update the QGIS-documentation repo with your contributions, but it doesn’t offer tools to:
group your commits and clean your change history
fix possible conflicts with the main repo
작성자의 변경 사항을 테스트하기 위한 문서를 빌드
You need to install git on your hard drive in order to get access to more advanced and powerful tools and have a local copy of the repository. Some basics you may often need are exposed below. You’ll also find rules to care about even if you opt for the web interface.
다음에 나오는 코드 예시에서, #
로 시작하는 줄은 주석을 의미하지만 $
로 시작하는 줄은 작성자가 입력해야 하는 명령어를 나타냅니다.
1.2.1. 로컬 저장소¶
Now you are ready to get a local clone of your QGIS-Documentation repository.
You can clone your QGIS repository using the web URL as follows:
# 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 둘 다 작성자의 로컬 환경에 맞춰야 합니다.
Check the following:
# 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 는 기본 주 분기입니다. 기고하는 데 절대로 이 분기를 이용해서는 안 됩니다! 절대로요!!
Alternatively you can clone your QGIS repository using the SSH protocol:
# 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
팁
권한 거부 (퍼블릭키) 오류?
If you get a Permission denied (publickey) error with the former command, there may be a problem with your SSH key. See GitHub help for details.
Check the following if you used the SSH protocol:
# 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
You can start to work here but in the long term process you will get a lot of issues when you will push your contribution (called Pull Request in github process) as the master branch of the qgis/QGIS-Documentation repository will diverge from your local/remote repository. You then need to keep track of the main remote repository and work with branches.
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)
Similarly, you can use the SSH protocol to add a remote repository in your local repository:
$ 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. 작성자의 기반 분기 업데이트¶
Before working on a new contribution, you should always update your master branch in your local repository. Assuming you are willing to push changes to the testing documentation, run the following command lines:
# 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
Now you have your local and remote repositories which both have their master
branch up to date with the official master
branch of QGIS-Documentation.
You can start to work on your contribution.
참고
Switch the branch if you wish to contribute to released doc
Along with the testing documentation, we continue to fix issues in the
latest release, meaning
that you can also contribute to it. Follow the previous section sample code,
replacing master
with the corresponding branch of the latest documentation.
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
를 입력하십시오. 작성자의 커밋이 해당 티켓을 폐지할 것입니다.
Now that your changes are saved and committed in your local branch, you need to send them to your remote repository in order to create pull request:
$ git push origin myNewBranch
1.2.6. 작성자의 로컬 및 원격 저장소 청소¶
작성자의 풀 요청이 공식 QGIS 문서에 통합된 다음, 작성자의 분기를 삭제할 수 있습니다. 이런 방식으로 많은 작업을 하는 경우, 몇 주만 지나도 쓸데없는 분기들을 많이 보유하게 될 겁니다. 따라서 다음 방법을 통해 작성자의 저장소를 말끔히 유지하십시오.
# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch
그리고 작성자의 로컬 저장소에 있는 master
분기를 업데이트하는 것도 잊지 마십시오!
1.3. 참고문헌¶
Other than the Github web interface and the git command line tools exposed above, there are also GUI applications you can use to create and manage your contributions to the documentation.
When the changes in the pull request are conflicting with recent changes pushed to the target branch, the conflicts need to be resolved before a merge is possible:
if the conflict relates to few competing lines, a Resolve conflicts button is available in the Github pull request page. Press the button and resolve the issue as explained at https://help.github.com/articles/resolving-a-merge-conflict-on-github/
if the conflict involves files renaming or removal, then you’d need to resolve the conflict using git command lines. Typically, you have to first rebase your branch over the target branch using
git rebase targetBranch
call and fix the conflicts that are reported. Read more at https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
Sometimes, at the end of the proofreading process, you may end up with changes split into multiple commits that are not necessarily worth it. Git command lines help you squash these commits to a smaller number and more meaningful commit messages. Some details at https://help.github.com/articles/using-git-rebase-on-the-command-line/