3. 发展过程

正如在开放源码项目中常见的那样,代码和文档对项目的贡献受到高度赞赏。QGIS社区非常支持。本节介绍在QGIS项目中开发和合并您的贡献的过程。

3.1. 一个基于Git的项目

在过去的几年里,QGIS源代码的复杂性大大增加了。因此,很难预测添加一项功能将会产生什么副作用。过去,QGIS项目的发布周期非常长,因为在添加新功能后重新建立软件系统的稳定性需要大量工作。为了克服这些问题,QGIS切换到使用 git 版本控制系统:新特性首先在贡献者分支中编码,当它们完成并稳定后合并到QGIS主分支。

Qgis源代码托管在https://github.com/qgis/QGIS.上

3.1.1. 角色

GitHub上存在各种角色。当你在GitHub上有一个帐户时,你已经被允许通过分叉存储库来进行贡献,并拥有‘贡献者’角色。核心开发者是“合作者”,可以将分支合并到上游和官方存储库。

3.1.2. 环境

要开始使用QGIS存储库并对其进行贡献,您需要:

  1. vbl.有一个 GitHub account

  2. 制作您自己的 QGIS repository (见 fork )

  3. vbl.有一个 git client installed 在您的系统上

  4. 设置您的 git environment

  5. 祝你玩得开心!

3.1.3. 安装Git

Git项目为大多数平台提供了该软件的最新版本。按照https://git-scm.com/downloads上的说明获取并安装与您的操作系统和体系结构对应的副本。在那里,还可以安装Git图形用户界面客户端来浏览和管理您的存储库(大多数时候,如果Git还不可用,它将安装Git)。

3.2. 分支机构的发展

3.2.1. 对发展的贡献

一旦在GitHub上注册并创建了存储库,您就可以作为贡献者参与进来。

备注

您可以在GitHub网站上的分支存储库中完成对QGIS代码的贡献。新代码将由测试环境自动构建。但是,当您想要提供复杂的更改时,此工作流可以快速揭示其局限性。下面的说明将假定为本地克隆。

您可以通过发起拉取请求进行贡献。要做到这一点,请遵循以下通用步骤:

  1. Clone your repository 安装到本地计算机上,并设置构建环境

  2. 创建一个新分支并进行开发编辑

  3. 提交您的更改并将您的分支推回到GitHub上的远程分支。然后,Pull请求立即以Web链接(URL)的形式提供。

  4. 打开一个拉取请求(PR),请求将提交(S)从您的分支拉入到主分支到上游存储库。

  5. 正在启动审核流程,通知其他贡献者和协作者您的拉取请求。你应该对他们的意见和建议作出反应。

备注

更详细的吉瑟伯叉拉工作流程请访问https://reflectoring.io/github-fork-and-pull/。

备注

大多数QGIS项目(网站、文档、pyQGIS API、插件...)都可以在 project GitHub page 并可以获得捐款,遵循同样的过程。

3.2.2. 访问存储库

为了能够从本地磁盘与远程分支和QGIS上游存储库进行交互,您需要:

  1. 在本地磁盘上复制您的副本

    cd path/to/store/the/repository
    git clone https://github.com/<yourName>/QGIS.git
    
  2. 连接QGIS主资料档案库(我们将其命名 upstream )致您的

    git remote add upstream https://github.com/qgis/QGIS.git
    
  3. 检查连接的远程存储库

    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)
    

    现在可以从本地驱动器访问您的在线资料档案库,您可以使用名称 origin 。每当您想要从QGIS/QGIS存储库中获取更改时,请使用 upstream

备注

在QGIS中,我们将最稳定的代码放在当前版本分支中。 master BRANCH包含所谓的“不稳定”版本系列的代码。我们会定期将一个版本从主版本中分离出来,然后继续稳定并选择性地将新特性加入到主版本中。

请参阅 INSTALL 文件,以获取有关构建开发版本的特定说明。

3.2.3. 程序

  1. 邮寄名单或发行回购的初步公告:

    在开始之前,在开发人员邮件列表上发布一个声明,看看是否有其他开发人员已经在开发相同的功能。如果回购中存在您的兴趣,您也可以在问题报告中将您的兴趣作为评论提及。如果新功能需要对QGIS体系结构进行任何更改,则 QGIS Enhancement Proposal (QEP) 是必要的。

  2. 在您的本地存储库中创建一个分支:

    根据主分支的最新状态,为新功能的开发创建一个新的GIT分支。

    git fetch upstream master
    git checkout -b newfeature upstream/master
    
  3. 现在,您可以开始开发:

    使用您常用的IDE在本地磁盘中对更改进行编码。记住在适当的时候为您的修改编写测试套件。

  4. 将您的更改提交到git repo:

    在提交时,请添加一个描述性注释,如果多个文件之间的更改不相关,则执行几个小的提交。相反,我们更希望您将相关更改分组到单个提交中。

    git add path/to/your/files
    git commit -m "Add a comment describing your nice feature"
    
  5. 现在,您可能希望与QGIS社区成员分享您的工作。通过执行以下操作将您的新功能推送到您的在线分叉存储库:

    git push origin newfeature
    

    备注

    如果该分支已经存在,则您的更改将被推送到其中,否则将创建该分支。

  6. Submit your changes 使用拉取请求

    打开Pull-Request时,自动测试套件将被触发,并检查您的更改是否遵循QGIS的编码指南,并且没有破坏任何现有功能。您需要修复所有报告的问题,然后才能将分支机构合并到上游。

    小技巧

    我们用 GitHub actions 管理要在存储库上运行的测试。为方便起见,您可以在存储库上启用操作,以便在推送更改时运行测试。然后,您可以在所有请求都通过后打开Pull请求,从而使审查过程更加高效。

  7. 定期改基至上游主站:

    建议重新设置基数,以便定期将MASTER中的更改合并到分支机构。这使得以后将分支合并回主分支变得更容易。在重新部署后,您需要 git push -f 给你的分叉回购。

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

备注

有关如何成为GIT大师的信息,请访问以下站点。

3.2.4. 合并回MASTER之前的测试

当您使用完新功能并对其稳定性感到满意时,在开发人员列表上发布一条消息。在合并回之前,这些更改将由开发人员和用户进行测试。

3.3. 提交拉式请求

这里有一些指导原则,可以帮助您轻松获取补丁并将请求拉入QGIS,并帮助我们处理容易发送使用的补丁。

一般来说,如果提交GitHub拉流请求,开发人员会更容易。我们在这里不描述拉取请求,而是让您参考 GitHub pull request documentation

如果您提出拉式请求,我们要求您定期将MASTER合并到您的PR分支,以便您的PR始终可以合并到上游MASTER分支。

如果您是一名开发人员,并希望评估拉取请求队列,有一个非常好的 tool that lets you do this from the command line

一般来说,当你提交公关时,你应该负起责任一直跟进到完成--回复其他开发人员发布的问题,为你的功能寻找一位“拥护者”,如果你发现你的公关没有得到行动,偶尔会给他们一个温和的提醒。请记住,QGIS项目是由志愿者推动的,人们可能无法即时关注您的公关。我们确实会扫描传入的拉取请求,但有时我们会遗漏一些东西。不要被冒犯或惊慌。试着找一个开发人员来帮助你,并联系他们,询问他们是否可以查看你的补丁。如果您觉得公关没有得到应有的关注,您可以选择加速公关(按优先顺序):

  • 帮助审阅其他请求以释放分配给您的人员。

  • 发送一条消息给邮件列表‘推销’你的公关,并把它包含在代码库中是多么美好。

  • 向PR队列中分配了您的PR的人发送消息。

  • 向项目指导委员会发送消息,请求他们帮助将您的公关纳入代码库。

3.3.1. 创建拉入请求的最佳实践

  • 始终从当前主控形状开始创建特征分支。

  • 如果您正在编写一个功能分支,请不要将任何内容“合并”到该分支中,而是按照下一点中所述重新设置基址,以保持历史记录的清晰度。

  • 在创建拉入请求之前,请执行以下操作 git fetch upstreamgit rebase upstream/master (如果上游是QGIS用户的遥控器,而不是您自己的遥控器,请检查您的 .git/config 或做 git remote -v | grep github.com/qgis )。

  • 你可以像最后一行一样重复进行一次git重垒,而不会造成任何伤害(只要你的分支的唯一目的是合并到主控中)。

  • 注意:更改基地后,您需要 git push -f 给你的分叉回购。 CORE DEVS: DO NOT DO THIS ON THE QGIS PUBLIC REPOSITORY!

3.3.2. 用于通知纪录员的特殊标签

有一个特别的标签 (Needs Documentation ),审阅者可以将其分配给您的Pull请求,以便在您的Pull请求合并后立即在QGIS-Documentation存储库中自动生成问题报告。记住要指出您的功能是否值得这样的标签。

此外,您还可以在提交消息中添加特殊标记,以便为文档编制人员提供更多信息。然后将提交消息添加到生成的问题报告中:

  • [needs-docs] 指示文档编写者在修复或添加现有功能后添加一些额外的文档。

  • [feature] 在有新功能的情况下。在你的公关中填写一份好的描述将是一个很好的开始。

请开发人员使用这些标签(不区分大小写),以便文档编写者有要处理的问题并有要做的事情的概述。但也请花时间添加一些文本:在提交中或在文档本身中。

3.3.3. 尽职调查

QGIS是在GPL下获得许可的。您应该尽一切努力确保您只提交不受知识产权冲突影响的补丁。此外,不要提交您不愿意在GPL下提供的代码。

3.4. 获取Git写入访问权限

对QGIS源树的写访问权限是邀请的。通常,当一个人提交几个(这里没有固定数量)重要的补丁程序,这些补丁程序证明了C++和QGIS编码约定的基本能力和理解,PSC成员之一或其他现有开发人员可以提名此人到PSC授予写入访问权限。提名者应该给出一个基本的宣传段落,说明为什么他们认为此人应该获得写入权限。在某些情况下,我们会将写访问权限授予非C++开发人员,例如翻译人员和文档人员。在这些情况下,该人员应该已经证明有能力提交补丁程序,并且理想情况下应该已经提交了几个实质性的补丁程序,以证明他们理解在不破坏东西的情况下修改代码库等。

备注

自从迁移到Git后,我们不太可能向新的开发人员授予写访问权限,因为在GitHub内通过派生QGIS然后发出Pull请求来共享代码是微不足道的。

在发出任何提交/拉入请求之前,请始终检查所有内容是否都已编译。尽量意识到您的提交可能会对在其他平台上构建和使用旧/新版本的库的人造成破坏。