3. Development Process
As common in open source projects, contributions of code and documentation to the project are highly appreciated. The QGIS community is very supportive. This section describes the procedure for developing and merging your contributions in the QGIS project.
3.1. git 기반 프로젝트
The complexity of the QGIS source code has increased considerably during the last years. Therefore it is hard to anticipate the side effects that the addition of a feature will have. In the past, the QGIS project had very long release cycles because it was a lot of work to reestablish the stability of the software system after new features were added. To overcome these problems, QGIS switched to a development model using the git version control system: new features are coded in the contributor branches first and merged to the QGIS master (the main branch) when they are finished and stable.
QGIS 소스 코드가 호스팅 되는 곳은 https://github.com/qgis/QGIS.
There exist various roles on GitHub. When having an account on GitHub you are already allowed to contribute by forking the repository and have the role ‘contributor’. Core developers are ‘collaborators’ and can merge branches into the upstream and official repository.
To get started using and contributing to the QGIS repository, you need to:
have a GitHub account
make your own copy of the QGIS repository (see fork)
have a git client installed on your system
set up your git environment
and have fun!
3.1.3. Installing git
The git project provides recent versions of the software for most platforms. Follow the instructions at https://git-scm.com/downloads to get and install the copy corresponding to your OS and architecture. There, it’s also possible to install a git GUI client to browse and manage your repositories (most of the time, it will install git if not yet available).
3.2. Development in branches
3.2.1. Contributions to development
Once signed up on GitHub and having forked the repository, you can engage as a contributor.
Contributions to QGIS code can be done from your forked repository on the GitHub website. The new code will automatically be built by the test environment. But this workflow can quickly reveal its limits when you want to provide complex changes. Instructions below will assume a local clone.
You can contribute by initiating a pull request. To do that follow these generic steps:
Clone your repository onto your local computer and set up the build environment
Create a new branch and do the edits for development
Commit your changes and push your branch back to the remote fork on GitHub. A pull request is then offered as web link (URL) right after.
Open a pull request (PR) asking to pull the commit(s) from your branch into the master branch into the upstream repository.
A review process is being started informing other contributors and collaborators about your pull request. You should be reactive to their comments and suggestions.
A more detailed Github’s Fork & Pull Workflow is available at https://reflectoring.io/github-fork-and-pull/
Most of the QGIS projects (website, documentation, pyQGIS API, plugins…) are available in the project GitHub page and can get contributions, following the same process.
3.2.2. 저장소에 접근
To be able to interact from your local disk with both your remote fork and the QGIS upstream repositories, you need to:
Make a clone of your copy on your local disk
cd path/to/store/the/repository git clone https://github.com/<yourName>/QGIS.git
Connect the QGIS main repository (we will name it
upstream) to yours
git remote add upstream https://github.com/qgis/QGIS.git
Check connected remote repositories
git remote -v # origin https://github.com/<YourName>/QGIS.git (fetch) # origin https://github.com/<YourName>/QGIS.git (push) # upstream https://github.com/qgis/QGIS.git (fetch) # upstream https://github.com/qgis/QGIS.git (push)
Your online repository is now accessible from your local drive and you can interact with it using the name
origin. Whenever you’d like to fetch changes from the qgis/QGIS repository, use
In QGIS we keep our most stable code in the current release branch.
master branch contains code for the so called ‘unstable’ release series. Periodically
we will branch a release off master, and then continue stabilisation and selective
incorporation of new features into master.
See the INSTALL file in the source tree for specific instructions on building development versions.
- Initial announcement on mailing list or issues repo:
Before starting, make an announcement on the developer mailing list to see if another developer is already working on the same feature. You can also mention your interest as a comment in the issue report if one exists in the repo. If the new feature requires any changes to the QGIS architecture, a QGIS Enhancement Proposal (QEP) is needed.
- Create a branch in your local repository:
Create a new git branch for the development of the new feature, based on latest state of the master branch.
git fetch upstream master git checkout -b newfeature upstream/master
- Now you can start developing:
Code your changes in your local disk with your usual IDE. Remember to write tests suite for your modifications, when appropriate.
- Commit your changes to the git repo:
When making a commit, put a descriptive comment and rather do several small commits if the changes across a number of files are unrelated. Conversely we prefer you to group related changes into a single commit.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
Now, you may want to share your work with QGIS community members. Push your new feature up to your online fork repository by doing:
git push origin newfeature
If the branch already exists, your changes will be pushed into it, otherwise, it is created.
- Submit your changes with a pull-request
With opening the pull-request, the automated test suite is triggered and checks whether your changes follow the coding guidelines of QGIS and do not break any existing feature. You’d need to fix any reported issues before your branch is merged upstream.
We use GitHub actions to manage the tests to be run on the repository. For convenience, you can enable the actions on your repository so that the tests are run when you push the changes. You’d then open the pull request after they all passed, making the review process more efficient.
- Rebase to upstream master regularly:
It is recommended to rebase to incorporate the changes in master to the branch on a regular basis. This makes it easier to merge the branch back to master later. After a rebase you need to
git push -fto your forked repo.
git pull --rebase upstream master git push -f origin newfeature
GIT 마스터가 되려면 아래 사이트를 보세요.
3.2.4. Testing before merging back to master
When you are finished with the new feature and happy with the stability, make an announcement on the developer list. Before merging back, the changes will be tested by developers and users.
3.3. Submitting Pull Requests
There are a few guidelines that will help you to get your patches and pull requests into QGIS easily, and help us deal with the patches that are sent to use easily.
In general it is easier for developers if you submit GitHub pull requests. We do not describe Pull Requests here, but rather refer you to the GitHub pull request documentation.
If you make a pull request we ask that you please merge master to your PR branch regularly so that your PR is always mergeable to the upstream master branch.
If you are a developer and wish to evaluate the pull request queue, there is a very nice tool that lets you do this from the command line
In general when you submit a PR you should take the responsibility to follow it through to completion - respond to queries posted by other developers, seek out a ‘champion’ for your feature and give them a gentle reminder occasionally if you see that your PR is not being acted on. Please bear in mind that the QGIS project is driven by volunteer effort and people may not be able to attend to your PR instantaneously. We do scan the incoming pull requests but sometimes we miss things. Don’t be offended or alarmed. Try to identify a developer to help you and contact them asking them if they can look at your patch. If you feel the PR is not receiving the attention it deserves your options to accelerate it should be (in order of priority):
Help review others pull requests to free the person assigned to yours.
Send a message to the mailing list ‘marketing’ your PR and how wonderful it will be to have it included in the code base.
Send a message to the person your PR has been assigned to in the PR queue.
Send a message to Marco Hugentobler (who manages the PR queue).
Send a message to the project steering committee asking them to help see your PR incorporated into the code base.
3.3.1. Best practice for creating a pull request
Always start a feature branch from current master.
If you are coding a feature branch, don’t “merge” anything into that branch, rather rebase as described in the next point to keep your history clean.
Before you create a pull request do
git fetch upstreamand
git rebase upstream/master(given upstream is the remote for qgis user and not your own remote, check your
git remote -v | grep github.com/qgis).
You may do a git rebase like in the last line repeatedly without doing any damage (as long as the only purpose of your branch is to get merged into master).
Attention: After a rebase you need to
git push -fto your forked repo. CORE DEVS: DO NOT DO THIS ON THE QGIS PUBLIC REPOSITORY!
3.3.2. Special labels to notify documentors
There is a special label (
Needs Documentation) that can be assigned by reviewers
to your pull request to automatically generate issue reports in QGIS-Documentation
repository as soon as your pull request is merged. Remember to mention whether your
feature deserves such a label.
Moreover, you can add special tags to your commit messages to provide more information to documenters. The commit message is then added to the generated issue report:
[needs-docs]to instruct doc writers to please add some extra documentation after a fix or addition to an already existing functionality.
[feature]in case of new functionality. Filling a good description in your PR will be a good start.
Please devs use these labels (case insensitive) so doc writers have issues to work on and have an overview of things to do. BUT please also take time to add some text: either in the commit OR in the docs itself.
3.3.3. Due Diligence
QGIS는 GPL에 따라 라이선스가 부여됩니다. 충돌하는 지적 재산권의 방해를 받지 않는 패치만 제출하도록 모든 노력을 기울여야 합니다. 또한 GPL에 따라 사용할 수 있게 되어 기쁘지 않은 코드를 제출하지 마십시오.
3.4. GIT 접근 권한 얻기
QGIS 소스 트리에 대한 쓰기 액세스는 초대를 통해 이루어집니다. 일반적으로 한 사람이 기본 역량과 C++ 및 QGIS 코딩 규칙에 대한 이해를 보여주는 실질적인 패치를 여러 개(여기에는 정해진 숫자가 없음) 제출할 때 PSC 구성원 중 한 명이나 다른 기존 개발자가 해당 사람을 PSC에 지명하여 쓰기 액세스 권한을 부여할 수 있습니다. 지명자는 그 사람이 쓰기 권한을 얻어야 한다고 생각하는 이유에 대한 기본적인 홍보 단락을 제공해야 합니다. 어떤 경우에는 비 C++ 개발자에게 쓰기 권한을 부여합니다. 번역가와 문서작가를 위한 이러한 경우, 그 사람은 여전히 패치를 제출할 수 있는 능력을 보여주어야 하며 이상적으로는 손상 없이 코드 베이스를 수정하는 것에 대한 이해를 보여주는 몇 가지 실질적인 패치를 제출해야 합니다.
GIT로 옮긴 이후, 우리는 QGIS를 포킹한 다음 pull request 발행하여 github 내에서 코드를 공유하는 것이 사소한 일이기 때문에 새로운 개발자에게 쓰기 액세스 권한을 부여할 가능성은 많지 않습니다.
커밋/풀 요청을 하기 전에 모든 것이 컴파일되는지 항상 확인하십시오. 커밋으로 인해 다른 플랫폼 및 이전/최신 버전의 라이브러리를 사용하여 빌드하는 사람에게 발생할 수 있는 중단 가능성을 인식하도록 노력하십시오.