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

단계별 기고 방법

주석

이번 과정을 설명하는 데 QGIS 문서를 예로 들긴 했지만, 다음 단락부터 보여줄 모든 명령어 및 단계는 QGIS 웹사이트에도 적용할 수 있습니다.

Now that you know the rules to follow to write a clean doc for QGIS, let’s dive in the process of production of this documentation and how quickly and safely share your changes with the community.

Assuming you already have a GitHub account, you first need to clone the source files of the documentation in order to have your own copy you can work on: go to the QGIS-Documentation repository page (for convenience, this repository is called below qgis/QGIS-Documentation) and click on the Fork button in the upper right corner.

Few seconds later, in your GitHub account you find a QGIS-Documentation repository (https://github.com/<YourName>/QGIS-Documentation). This repo is a safe copy in which you have full write access and can push all your contributions without a risk to affect the official documentation. At the beginning, this repository contains the same branches as qgis/QGIS-Documentation and is defaulted to master branch. Branches are parallel lines of development containing different snapshots of the doc that may merge or diverge. Preferably create a branch for each issue you want to tackle and you can create as many branches as you want.

참고

Do your changes in an ad’hoc branch, never in master

By convention, avoid making changes in your master branch except merging the modifications from the master branch of qgis/QGIS-Documentation (called qgis:master). And use it as model to create new branches for a clean history and snapshot.

There are different ways to contribute to QGIS documentation. Though we expose them below separately, they are not mutually exclusive, meaning that you can, at any moment, switch from one process to another without any harm because they both follow the scheme below:

  1. Do your modifications in an ad’hoc branch of your repository
  2. Publish your changes and ask for merging in the main doc through a pull request (PR)
  3. Others review, discuss and integrate your work in the main branch when everything seems ok.

Using GitHub web interface

From your cloned repository, you can now propose changes to the main documentation. Indeed, GitHub web interface offers you ways to easily:

  • edit files, preview and commit your changes
  • make a pull request to have your changes inserted in the main repo
  • create, update or delete branches

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

Make changes in your repo

Documentation can be improved by addressing issues reported at https://github.com/qgis/QGIS-Documentation/issues or issues you may have encountered while browsing the doc. They can be of different types: typo error, missing feature, wrong or out of date description...

Alternative 1: Picking an issue in the list

  1. Select an issue you want to fix. To avoid many persons tackling the same issue, you can inform contributors about your choice by adding a comment to the issue report and get it assigned to you.
  2. From your repository, create (and switch to) a branch with a name that helps you remind what it’s about
  3. Browse the source files to the file that has to be changed
  4. Toggle the file into Edit mode using the pencil icon and do your modifications following guidelines
  5. Validate your changes by filling the Commit Changes frame and commit directly to your branch.
  6. Redo the previous steps for any other file that needs to be updated to fix the issue.

Alternative 2: Using the Fix Me shortcut

The QGIS project provides an easy way to reach source file from online documentation. Indeed, instead of browsing the source files in GitHub to find the one that suits the issue, or if you find an issue while reading the manuals, you simply have to click the “Fix Me” link at the bottom of the page to open its source file in Edit mode.

  1. 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 in a new branch of your repository.

    Note that if you have commit rights to QGIS-Documentation repository, then no message will show and you’ll directly modify qgis:master branch itself unless you save your changes in another branch.

  2. Do your changes following guidelines available at http://docs.qgis.org/testing/en/docs/documentation_guidelines/

  3. When you finish, at the bottom of the page, comment a bit what your changes are about and click on Propose File change. This will generate a new branch (patch-xxx) in your repo.

참고

If your master branch is even with qgis:master, you can safely replace in the link qgis by <YourName>. In this case, once your changes are done, you need to check radioButtonOn Create a new branch for this commit and start a pull request and avoid modifying master.

Share your changes via Pull Request

Now, you have a new branch in QGIS with a file that diverge from qgis:master. To integrate your changes in the official documentation, you need to do a pull request.

  1. Actually, after you commit your changes, GitHub opens a new dialog comparing branches:

    • if you used the Fix Me without changing the url, then the comparison is between your patch-xxx branch and qgis:master (the base fork is qgis/QGIS-Documentation and its branch master).
    • if you used a branch you had named yourself then the comparison is done between that branch and your own master branch (the base is simply master). You therefore need to leave that page and follow the next step.

  2. In any case (including pushing branch to GitHub from command lines) you can create a new pull request at any moment from many pages. Simply go to the main page of the repository (yours or qgis), click on New Pull Request and Compare across forks (if needed). Ensure you select qgis/QGIS-Documentation with master as base branch and that the head fork is your repository <YourName>/QGIS-Documentation with your modified branch along.

    참고

    Though released and being translated, the documentation of QGIS 2.18 is still maintained and existing issues are fixed. If you plan to fix the issues in the current released doc, replace master branch by the appropriate manual_en_... branch in any of the steps exposed earlier.

  3. A green check along the compared branches shows that your changes can automatically be merged in the official doc. Click the Create pull request button. If you get a red cross, it means that the files you are modifying were not up to date with the branch you are targetting (a commit has been pushed to it since you create or last update your branch). You then need to use git command line tools to fix it.

  4. Fill the form if needed and click again Create pull request button.

  5. A new PR is added to https://github.com/qgis/QGIS-Documentation/pulls and everybody can look or comment it.

  6. That will trigger a Travis CI build automatically checking if your contribution doesn’t contain a build error. In case of error, a red cross appears along your commit. Simply click on it or on Details in the summary section at the bottom of the page to have details on the error. You’ll need to fix any reported error or warning before your changes are committed in the repository.

  7. Until your PR is merged with the main repo, you can add modifications to your proposal. Actually any new changes done to your branch is appended to your pull request. Do it if the change has to do with the issue you are fixing, otherwise create a new branch for those changes following steps above.

  8. Once everything looks good to you and others, a committer can merge your branch with the main repo. Your contribution is validated.

  9. If you want, you can now delete the branch you used, to avoid having too many (unused and outdated) branches crowding your repository.

Doing this little steps will make you learn the process easier.

경고

Be vigilant to pull request against qgis:master and not your own master branch, otherwise nobody is aware of your changes and you may mistakenly merge your changes into your master branch, polluting its history.

참고

Automatically close issue report from pull request

To ease issue reports management, mention the number of the issue you are addressing in your pull-request. This can be done using #issue_number. If preceded by terms like fix, close... the concerned issue is closed as soon as the pull request is merged.

Git 명령 프롬프트 도구 이용

GitHub web interface helps you update the repo with your contribution in an easier way but it doesn’t offer tools to:

  • group your commits and clean your changes history
  • fix conflicts with the main repo if needed...

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

You then 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.

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

로컬 저장소

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

For released doc (manual_en_ branch)

Along the testing documentation, we continue to fix issues in QGIS 2.18 doc, meaning that you can also contribute to it. Following the previous section sample code, you can easily do that by selecting the corresponding branch.

저장소를 복사할 경우 (로컬 저장소 참조) 작성자의 복사본은 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

In this way your local and remote branches for the 2.14 version are up to date with the one of the official upstream repository.

작성자의 작업 분기로 기고

이제 작성자의 기반 분기가 업데이트됐으니, 작성 내용을 추가할 전용 분기를 생성해야 합니다. 언제나 기반 분기가 아닌 다른 분기에서 작업하십시오! 언제나요!

$ 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 를 입력하십시오. 작성자의 커밋이 해당 티켓을 폐지할 것입니다.

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

작성자의 변경 사항 공유

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

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

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

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

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