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. A git based project

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 source code is hosted at https://github.com/qgis/QGIS.

3.1.1. Roles

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.

3.1.2. Environment

To get started using and contributing to the QGIS repository, you need to:

  1. have a GitHub account

  2. make your own copy of the QGIS repository (see fork)

  3. have a git client installed on your system

  4. set up your git environment

  5. 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. ブランチでの開発

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:

  1. Clone your repository onto your local computer and set up the build environment

  2. Create a new branch and do the edits for development

  3. 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.

  4. Open a pull request (PR) asking to pull the commit(s) from your branch into the master branch into the upstream repository.

  5. 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:

  1. Make a clone of your copy on your local disk

    cd path/to/store/the/repository
git clone https://github.com/<yourName>/QGIS.git

  2. Connect the QGIS main repository (we will name it upstream) to yours

    git remote add upstream https://github.com/qgis/QGIS.git

  3. 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 upstream.

注釈

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.

3.2.3. 手順

  1. 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.

  2. 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
  3. 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.

  4. 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"

  5. 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.

  6. 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.

  7. 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 -f to your forked repo.

    git pull --rebase upstream master
git push -f origin newfeature

注釈

GITのマスターになることについては、以下のサイトを参照してください。

3.2.4. マスターに戻してマージする前にテスト

新しい機能性と安定性に満足して終了したら、開発者リストで発表を行います。戻してマージする前に、変更は開発者とユーザーによってテストされるでしょう。

3.3. Submitting Pull Requests

パッチを取得し簡単にQGISに要求をプルするのに役立つ、そして簡単に使用するために送信されるそのパッチを扱うのに役立つ、いくつかのガイドラインがあります。

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.

  • あなたのPRおよびそれがコードベースに含まれるとどれほど素晴らしいかを「売り込む」メッセージをメーリングリストに送信します。

  • PRキュー内であなたのPRが割り当てられている人にメッセージを送信します。

  • （PRキューを管理している）マルコ・ヒュージェントブラーにメッセージを送信します。

  • プロジェクトの運営委員会にメッセージを送信し、あなたのPRがコードベースに組み込まれるのを見るのを助けるよう求めます。

3.3.1. プル要求を作成するためのベストプラクティス

  • 常に現在のマスターから機能ブランチを開始します。

  • 機能ブランチをコーディングしている場合は、そのブランチに何かを「マージ」しないでください。むしろ、あなたの履歴をきれいなままに保持するために、次のポイントで説明されるように、リベースしてください。

  • Before you create a pull request do git fetch upstream and git rebase upstream/master (given upstream is the remote for qgis user and not your own remote, check your .git/config or do git remote -v | grep github.com/qgis).

  • 何らかのダメージを与えることなく繰り返し、最後の行のようにgitリベースを行うことができます（あなたのブランチの唯一の目的がマスターにマージされることである限り、）。

  • 注意：リベースした後、あなたのフォークレポに git push -f する必要があります。 CORE DEVS：QGIS公開リポジトリ上でこれ​​をしないでください！

3.3.2. 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] 既存の機能に修正や追加した後、いくつかの余分なドキュメントを追加してくださいとお願いするドキュメントライターを指示します。

  • [feature] in case of new functionality. Filling a good description in your PR will be a good start.

開発者はこれらのラベル（大小文字を区別しない）を使用してください、ドキュメントの作成者が作業する問題を持ち、するべきことの概要を持つように。しかし、また、いくつかのテキストを追加する時間をかけてください：コミットまたはドキュメント自体のいずれかで。

3.3.3. 適当な注意

QGISはGPLの下でライセンスされています。あなたは、矛盾する知的財産権によって妨げられないパッチを提出するよう、あらゆる努力をする必要があります。また、GPLの下で利用可能になって嬉しくないコードを提出しないでください。

3.4. GIT書き込みアクセス権の取得

QGISソースツリーへの書き込みアクセス権は招待によります。人はC ++とQGISコーディング規約の基本的な能力と理解を示し、いくつかの（ここには一定の数が存在しない）かなりのパッチを提出する場合、通常、PSCのメンバーや他の既存の開発者の一人は、書き込みアクセスを許可するためのPSCにその人を指名できます。推薦は、彼らがその人が書き込みアクセス権を取得すべきだと思う理由の基本的なプロモーション段落を与える必要があります。いくつかのケースでは、我々は、翻訳者とdocumentors用など非C ++開発者への書き込みアクセスを許可します。これらのケースでは、人はまだパッチを提出する能力を実証している必要があり、理想的に物事を壊すことなく、コードベースを変更することの理解を示し、いくつかのかなりのパッチなどを提出している必要があります

注釈

GITに移動するので、QGISをforkしてプル要求を発行することによってgithubの内のコードを共有することは簡単なので、新しい開発者に書き込みアクセスを許可する可能性は低いです。

常にすべてがコミット/プル要求を作成する前にコンパイルされることを確認してください。あなたのコミットは、人々が他のプラットフォーム上で構築するためのライブラリとの古い/新しいバージョンの原因となる可能性のある破損を認識するようにしてください。