一步一步的贡献¶

注解

虽然QGIS文档用于演示该过程,但下面显示的所有命令和步骤也适用于QGIS网站。

现在您知道了如何使用 reStructuredText and Sphinx ,让我们深入研究生成文档并与社区共享您的更改的过程。

使用Github Web界面

GitHub Web界面允许您执行以下操作:

读《圣经》 Hello-world 计划学习下面将使用的一些基本词汇和操作。

注解

如果您正在修复报告的问题

如果要更改以修复 issue ,在问题报告中添加注释以将其分配给您自己。这将阻止多个人处理同一问题。

1。Fork QGIS文档

假设你已经有了 GitHub account 首先需要分叉文档的源文件。

导航到 QGIS-Documentation repository 页面并单击 githubFork 按钮位于右上角。

在您的Github帐户中,您将找到一个QGIS文档存储库。( https://github.com/<YourName>/QGIS-Documentation )此存储库是正式的QGIS文档存储库的副本,您可以在其中完全写入权限,并且可以在不影响正式文档的情况下进行更改。

2。作出改变

有不同的方法来帮助QGIS文档。我们在下面分别展示它们,但是您可以从一个过程切换到另一个过程而不会造成任何伤害。

备选方案1:使用 Fix Me 捷径

可以通过单击 Fix Me 链接到每一页的页脚。

  1. 这将在 qgis:master 分支,在页面顶部显示一条消息,告诉您您没有对此repo的写访问权,您所做的更改将应用于存储库的新分支。
  2. 按照以下步骤进行更改 writing guidelines .
  3. 完成后,对更改进行简短评论,然后单击 Propose file change . 这将生成一个新的 branchpatch-xxx )在您的存储库中。
  4. 点击后 Propose file change Github将导航到 Comparing changes 页。
    • 如果已完成更改,请跳至 Compare changesShare your changes via Pull Request 下面部分。
    • 如果在将它们提交给QGIS之前您还想进行其他更改,请执行以下步骤:
      1. 导航到您的QGIS文档分支( https://github.com/<YourName>/QGIS-Documentation
      2. 点击 githubBranch 然后搜索 patch-xxx 分支机构。选择此补丁分支。这个 githubBranch 按钮现在将显示 Branch: patch-xxx
      3. 跳下 Modify files 下面。

备选方案2:在文档存储库中创建临时分支

您可以直接从QGIS文档的分支编辑文件。

点击 githubBranch 在分叉的qgis-文档存储库的左上角,在文本字段中输入唯一的名称以创建新的 branch . 新分支的名称应该与您要修复的问题相关。这个 githubBranch 按钮现在应该说 Branch: branch_name

小技巧

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

按照惯例,避免在 master 分支,除非合并来自 master 分支 qgis/QGIS-Documentation 到您的QGIS文档库副本中。单独的分支允许您同时处理多个问题,而不干扰其他分支。如果你犯了错误,你可以删除一个分支,然后从主分支创建一个新的分支来重新开始。

三。修改文件

  1. 浏览qgis文件叉的源文件到需要修改的文件
  2. 按照以下步骤进行修改 writing guidelines
  3. 完成后,导航到 Commit Changes 在页面底部添加框架,对所做更改进行简短评论,然后单击 Commit Changes 将更改直接提交到您的分支。确保 Commit directly to the branch_name branch. 被选中。
  4. 对需要更新以解决问题的任何其他文件重复前面的步骤。

4。通过“拉”请求共享更改

您需要发出请求,将您的更改集成到正式文档中。

注解

If you used a Fix Me link

提交更改后,Github将自动打开一个新页面,比较您在 patch-xxx 分支到 qgis/QGIS-Documentation 主分支。

跳过 Step 2 下面。

1。启动新的请求

导航到的主页 QGIS-Documentation repository and click on New pull request.

2。比较变化

如果您看到两个对话框,其中一个显示 base:master 而另一个 compare:branch_name (参见图),这将只合并您从一个分支到主分支的更改。要修复此问题,请单击 compare across forks 链接。

../../_images/githubCompareAcrossForks.png

如果你 Comparing changes 页面如下,单击 compare across forks 链接。

您应该看到四个下拉菜单。这些将允许您将在分支中所做的更改与要合并到的主分支进行比较。他们是:

  • base fork: the fork that you want to merge your changes into
  • base: the branch of the base fork that you want to merge your changes into
  • head fork: the fork that has changes that you want to incorporate into the base fork
  • compare: the branch with those changes

选择 qgis/QGIS-Documentation 作为基础叉 master 作为基础,将head fork设置为存储库 <YourName>/QGIS-Documentation ,并设置“与修改的分支进行比较”。

../../_images/githubCreatePullRequestComparison.png

比较两者之间的变化 qgis/QGIS-Documentation 以及你的存储库

一张绿色的支票 Able to merge 显示您的更改可以合并到正式文档中而不会发生冲突。

单击 Create pull request 按钮。

警告

If you see githubCantMerge

这意味着 conflicts . 您要修改的文件与目标分支不是最新的,因为其他人已提交与您的更改冲突。您仍然可以创建拉请求,但需要修复 conflicts 完成合并。

小技巧

尽管已发布并正在翻译,但qgis的文档 2.18 仍保持不变,现有问题已解决。如果您正在修复不同版本的问题,请更改 basemaster 适当的 release_... 在上述步骤中进行分支。

三。描述您的请求

将打开一个文本框:填写您正在解决的问题的任何相关注释。

如果这与 issue ,在您的评论中添加问题编号。这是通过输入和发行号(** #1234 )如果前面有类似的词 fixclose ,相关问题将在请求合并后立即关闭。

添加指向正在更改的任何文档页的链接。

点击 Create pull request

4。进行更正

新的请求将自动添加到 Pull requests list . 其他编辑和管理员将审查您的请求,他们可能会提出建议或要求更正。

拉请求还将触发 Travis CI build 它会自动检查您的贡献是否有构建错误。如果Travis CI发现错误,则在提交旁边会出现一个红十字会。单击红十字会或 Details 在“拉”请求页底部的摘要部分查看错误的详细信息。在将更改提交到 qgis/QGIS-Documentation 储存库。

您可以对拉请求进行修改,直到它与主存储库合并,以改进您的请求、解决请求的修改或修复生成错误。

要进行更改,请单击 githubFilesChanged 在“拉取请求”页面中的选项卡,单击铅笔按钮 githubEditPencil 在要修改的文件名旁边。

如果对拉请求中提交的同一分支进行了这些更改,则任何其他更改都将自动添加到拉请求中。因此,只有当这些更改与您打算用该请求修复的问题相关时,才应进行其他更改。

如果要修复另一个问题,请为这些更改创建一个新分支,然后重复上述步骤。

在更正任何生成错误之后,以及在您和管理员对您的更改满意之后,管理员将合并您的贡献。

5。审查和评论请求

你可以做 comments 请求中的更改。导航到 pull request page 然后点击你想要评论的请求。

在页面底部,您将找到一个文本框,您可以在其中留下有关拉请求的常规注释。

要添加有关特定行的注释,请单击 githubFilesChanged 找到你想要评论的文件。你可能要点击 Load diff 看看变化。滚动到要评论的行,然后单击 githubBluePlus . 这将打开一个文本框,允许您留言。

5。删除合并的分支

合并更改后,可以删除分支。删除旧分支可以避免在存储库中存在未使用和过时的分支。

导航到您的QGIS文档库分支( https://github.com/<YourName>/QGIS-Documentation )点击 Branches 标签。下面 Your branches 你会看到你的分支列表。点击 deleteSelected Delete this branch 用于删除任何不需要的分支的图标。

使用git命令行工具

GitHub Web界面是用您的贡献更新QGIS文档报告的简单方法,但它不提供以下工具:

你需要 install git 在硬盘上,以便访问更高级和功能更强大的工具,并拥有存储库的本地副本。您可能经常需要的一些基础知识将在下面介绍。即使您选择Web界面,您也会发现需要关注的规则。

在下面的代码示例中,行以 $ 显示应键入的命令 # 是评论。

本地存储库

现在,您已经准备好获取的本地克隆 your QGIS文档库:

$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git

前一个命令行只是一个例子。您应该同时调整路径和存储库URL,替换 <YourName> 使用您的用户名。

小技巧

权限被拒绝(PublicKey)错误?

如果您收到一个拒绝权限(publickey)错误,那么您的ssh密钥可能有问题。见 GitHub help 有关详细信息。

检查一下:

$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master
  • origin is the name of the remote repository of your QGIS-Documentation repository.
  • master is the default main branch. You should never use it to contribute! Never!

您可以在这里开始工作,但在长期的过程中,当您将推动您的贡献(在Github过程中称为拉请求)时,您将遇到许多问题,因为QGIS文档存储库的主分支将与您的本地/远程存储库不同。

添加另一个远程存储库

为了能够遵循主项目中的工作,请在本地存储库中添加一个新的远程存储库。这个新的远程存储库是来自qgis项目的qgis文档存储库:

$ git remote add upstream git@github.com:qgis/QGIS-Documentation.git
$ git remote -v
origin  git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin  git@github.com:<YourName>/QGIS-Documentation.git (push)
upstream        git@github.com:qgis/QGIS-Documentation.git (fetch)
upstream        git@github.com:qgis/QGIS-Documentation.git (push)

现在您可以在两个远程存储库之间进行选择:

  • origin to push your local branch in your remote repository
  • upstream to merge (if you have right to do so) your contribution to the official one OR to update your master branch of local repository from the master branch of the official repository.

注解

upstream is just a label, a kind of standard name but you can call it as you want.

更新您的基本分支

用于测试文档( 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

现在您有一个本地和远程存储库,它们都有 master 使用来自QGIS组织的QGIS文件进行最新分支。你可以开始为自己的贡献工作。

对于已发布的文档( release_ 分支机构)

在测试文档中,我们继续解决QGIS中的问题。 2.18 博士,意思是你也可以为它做出贡献。按照前面的部分示例代码,您可以通过选择相应的分支轻松地完成这项工作。

克隆存储库时(请参见 本地存储库 ,您的克隆具有上游存储库的所有分支。如上所述,您需要确保您的分支机构与上游的:

# change branch e.g. for 2.18 LTR
$ git checkout release_2.18
# get "information" from the release_2.18 branch in upstream repository
$ git fetch upstream release_2.18
# merge update from upstream/release_2.18 to the current local branch
$ git merge upstream/release_2.18
# update **your** remote repository
$ git push origin release_2.18

这样,您的本地和远程分支 2.18 版本是最新的,其中一个官方的上游存储库。

为生产部门做出贡献

现在您的基本分支已经更新,您需要创建一个专门的分支,在其中添加您的贡献。总是在基础分支以外的分支上工作!永远!

$ 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
release_2.18
* 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个字符,而不是以 . . 言简意赅。您的描述可以更长,以 . 你可以提供更多的细节。
  • 使用A # 用数字表示问题。前缀与 Fix 如果您修复了票据:您的提交将关闭票据。

现在您的更改已保存并提交到本地分支中,您需要将它们发送到远程存储库,以便创建请求:

$ git push origin myNewBranch

共享您的更改

现在,您可以转到您的Github存储库并 create a Pull Request 如前一节所述。确保在正式的QGIS文档存储库中创建从分支到目标远程分支的公关。

清理本地和远程存储库

将您的PR合并到正式的QGIS文档后,可以删除您的分支。如果你用这种方式工作很多,几周后你会得到很多无用的分支。因此,请以这种方式保持存储库干净:

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

别忘了更新 master 在本地存储库中进行分支!

进一步阅读