注解
虽然QGIS文档用于演示该过程,但下面显示的所有命令和步骤也适用于QGIS网站。
现在您知道了如何使用 reStructuredText and Sphinx ,让我们深入研究生成文档并与社区共享您的更改的过程。
GitHub Web界面允许您执行以下操作:
读《圣经》 Hello-world 计划学习下面将使用的一些基本词汇和操作。
假设你已经有了 GitHub account 首先需要分叉文档的源文件。
导航到 QGIS-Documentation repository 页面并单击 按钮位于右上角。
在您的Github帐户中,您将找到一个QGIS文档存储库。( https://github.com/<YourName>/QGIS-Documentation
)此存储库是正式的QGIS文档存储库的副本,您可以在其中完全写入权限,并且可以在不影响正式文档的情况下进行更改。
有不同的方法来帮助QGIS文档。我们在下面分别展示它们,但是您可以从一个过程切换到另一个过程而不会造成任何伤害。
Fix Me
捷径¶可以通过单击 Fix Me
链接到每一页的页脚。
qgis:master
分支,在页面顶部显示一条消息,告诉您您没有对此repo的写访问权,您所做的更改将应用于存储库的新分支。patch-xxx
)在您的存储库中。https://github.com/<YourName>/QGIS-Documentation
)patch-xxx
分支机构。选择此补丁分支。这个 您可以直接从QGIS文档的分支编辑文件。
点击 在分叉的qgis-文档存储库的左上角,在文本字段中输入唯一的名称以创建新的 branch . 新分支的名称应该与您要修复的问题相关。这个
按钮现在应该说 Branch: branch_name
小技巧
Do your changes in an ad hoc branch, never in the master
branch
按照惯例,避免在 master
分支,除非合并来自 master
分支 qgis/QGIS-Documentation
到您的QGIS文档库副本中。单独的分支允许您同时处理多个问题,而不干扰其他分支。如果你犯了错误,你可以删除一个分支,然后从主分支创建一个新的分支来重新开始。
GitHub Web界面是用您的贡献更新QGIS文档报告的简单方法,但它不提供以下工具:
你需要 install git 在硬盘上,以便访问更高级和功能更强大的工具,并拥有存储库的本地副本。您可能经常需要的一些基础知识将在下面介绍。即使您选择Web界面,您也会发现需要关注的规则。
在下面的代码示例中,行以 $
显示应键入的命令 #
是评论。
现在,您已经准备好获取的本地克隆 your QGIS文档库:
$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git
前一个命令行只是一个例子。您应该同时调整路径和存储库URL,替换 <YourName>
使用您的用户名。
检查一下:
$ git remote -v
origin git@github.com:<YourName>/QGIS-Documentation.git (fetch)
origin git@github.com:<YourName>/QGIS-Documentation.git (push)
$ git branch
* master
您可以在这里开始工作,但在长期的过程中,当您将推动您的贡献(在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)
现在您可以在两个远程存储库之间进行选择:
注解
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命令的几句话:
.
. 言简意赅。您的描述可以更长,以 .
你可以提供更多的细节。#
用数字表示问题。前缀与 Fix
如果您修复了票据:您的提交将关闭票据。现在您的更改已保存并提交到本地分支中,您需要将它们发送到远程存储库,以便创建请求:
$ git push origin myNewBranch
将您的PR合并到正式的QGIS文档后,可以删除您的分支。如果你用这种方式工作很多,几周后你会得到很多无用的分支。因此,请以这种方式保持存储库干净:
# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch
别忘了更新 master
在本地存储库中进行分支!
git rebase targetBranch
调用并修复报告的冲突。阅读https://help.github.com/articles/resoluting-a-merge-conflict-using-the-command-line了解更多信息/