3. GIT访问¶

本章节描述了如何从头开始使用QGIS的git库。在此之前，你机器上需要先安装git客户端，你才能使用git库。

3.1. 安装 ¶

3.1.1. 在GNU/Linux下安装git ¶

基于Debian版本的用户可以：

sudo apt install git

3.1.2. 在Windows下安装git ¶

Windows users can obtain msys git or use git distributed with cygwin.

3.1.3. 在OSX下安装git ¶

The git project has a downloadable build of git. Make sure to get the package matching your processor (x86_64 most likely, only the first Intel Macs need the i386 package).

下载完后，点击安装包开始安装。

PPC/source note

The git site does not offer PPC builds. If you need a PPC build, or you just want a little more control over the installation, you need to compile it yourself.

Download the source from https://git-scm.com/. Unzip it, and in a Terminal cd to the source folder, then:

make prefix=/usr/local
sudo make prefix=/usr/local install

如果你不需要任何附加库，比如Perl，Python或者TclTk（GUI），你可以用以下参数进行make，从而禁止这些功能：

export NO_PERL=
export NO_TCLTK=
export NO_PYTHON=

3.2. 访问代码库 ¶

克隆QGIS的主版本库：

git clone git://github.com/qgis/QGIS.git

3.3. 导出一个分支库 ¶

为了导出一个分支库，比如2.6.1的版本分支库，需要：

cd QGIS
git fetch
git branch --track origin release-2_6_1
git checkout release-2_6_1

导出主版本库：

cd QGIS
git checkout master

注解

在QGIS里，我们把最稳定的代码放在当前版本的分支库上。主版本库包含了一些不稳定版本的代码。我们会定期的从主版本库拉一个分支版本库出来，持续稳定化，并选择某些新功能加入主版本库。

如果需要编译开发版本，请查看代码库里INSTALL文件里的相关说明。

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 where new features are coded in GIT branches first and merged to master (the main branch) when they are finished and stable. This section describes the procedure for branching and merging in the QGIS project.

3.7.2. 步骤 ¶

先在邮件列表中声明
在开始之前，需要在开发邮件列表里声明一下，看是否有其他开发人员已经在做同样的功能了。同时联系项目控制委员会（project steering committee， PSC）的技术顾问。如果一个新功能需要改动QGIS的架构，还需要提一个记录（request for comment，RFC）。

创建一个分支库：为了开发一个新的功能，需要创建一个新的git分支库。

git checkout -b newfeature

终于，你可以开始功能开发了。如果你计划跟其他开发者共享你的开发分支库，需要把代码上传，你可以通过以下方式把你的代码库上传到QGIS的官方代码库：

git push origin newfeature

注解

如果分支库已经存在，你的改动会更新上去。

定期从主版本库更新代码：强烈建议你定期从主版本库更新代码到你的分支库，以便拿到主版本库里最新的改动。这样可以使你的分支库再合并回主版本库的时候，变得简单一些。更新完代码后，你需要在你的分支库上执行“git push -f”。

注解

注意：千万不要在源库里执行“git push -f”！只能在你的开发分支库里执行。

git rebase master

3.7.3. 合并回主版本库之前的测试 ¶

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.8. Submitting Patches and 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.

3.8.1. Pull Requests ¶

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

Please see the section below on 'getting your patch noticed'. 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. If you feel the PR is not receiving the attention it deserves your options to accelerate it should be (in order of priority):

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.8.1.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 origin and git rebase origin/master (given origin is the remote for upstream and not your own remote, check your .git/config or do 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 -f to your forked repo. CORE DEVS: DO NOT DO THIS ON THE QGIS PUBLIC REPOSITORY!

3.8.1.2. Special labels to notify documentors ¶

Besides common tags you can add to classify your PR, there are special ones you can use to automatically generate issue reports in QGIS-Documentation repository as soon as your pull request is merged:

[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.8.1.3. For merging a pull request ¶

Option A:

click the merge button (Creates a non-fast-forward merge)

Option B:

Checkout the pull request
Test (Also required for option A, obviously)
checkout master, git merge pr/1234
Optional: git pull --rebase: Creates a fast-forward, no "merge commit" is made. Cleaner history, but it is harder to revert the merge.
git push (NEVER EVER use the -f option here)

3.9. Patch file naming ¶

If the patch is a fix for a specific bug, please name the file with the bug number in it e.g. bug777fix.patch, and attach it to the original bug report in GitHub.

If the bug is an enhancement or new feature, it's usually a good idea to create a ticket in GitHub first and then attach your patch.

3.10. Create your patch in the top level QGIS source dir ¶

This makes it easier for us to apply the patches since we don't need to navigate to a specific place in the source tree to apply the patch. Also when I receive patches I usually evaluate them using merge, and having the patch from the top level dir makes this much easier. Below is an example of how you can include multiple changed files into your patch from the top level directory:

cd QGIS
git checkout master
git pull origin master
git checkout newfeature
git format-patch master --stdout > bug777fix.patch

This will make sure your master branch is in sync with the upstream repository, and then generate a patch which contains the delta between your feature branch and what is in the master branch.

3.10.1. Getting your patch noticed ¶

QGIS developers are busy folk. We do scan the incoming patches on bug reports 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 don't get any response, you can escalate your query to one of the Project Steering Committee members (contact details also available in the Technical Resources).

3.10.2. Due Diligence ¶

QGIS is licensed under the GPL. You should make every effort to ensure you only submit patches which are unencumbered by conflicting intellectual property rights. Also do not submit code that you are not happy to have made available under the GPL.

3.11. Obtaining GIT Write Access ¶

Write access to QGIS source tree is by invitation. Typically when a person submits several (there is no fixed number here) substantial patches that demonstrate basic competence and understanding of C++ and QGIS coding conventions, one of the PSC members or other existing developers can nominate that person to the PSC for granting of write access. The nominator should give a basic promotional paragraph of why they think that person should gain write access. In some cases we will grant write access to non C++ developers e.g. for translators and documentors. In these cases, the person should still have demonstrated ability to submit patches and should ideally have submitted several substantial patches that demonstrate their understanding of modifying the code base without breaking things, etc.

注解

Since moving to GIT, we are less likely to grant write access to new developers since it is trivial to share code within github by forking QGIS and then issuing pull requests.

Always check that everything compiles before making any commits / pull requests. Try to be aware of possible breakages your commits may cause for people building on other platforms and with older / newer versions of libraries.

When making a commit, your editor (as defined in $EDITOR environment variable) will appear and you should make a comment at the top of the file (above the area that says 'don't change this'). 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.