1. 一步一步的贡献

e.g.

1. 一步一步的贡献

使用GitHub Web界面

Fork QGIS-文档
做出改变

备选方案1：使用  Edit on GitHub 捷径
备选方案2：在您的文档存储库中创建一个临时分支

修改文件
通过拉取请求共享您的更改

启动新的拉取请求
比较更改
描述您的拉取请求
审核并评论拉取请求
改正

删除合并后的分支机构

使用Git命令行工具

本地存储库
添加另一个远程存储库
更新您的基本分支
为您的生产部门做出贡献
共享您的更改
清理本地和远程存储库

进一步阅读

备注
虽然使用qgis文档来演示该过程，但下面显示的所有命令和步骤也适用于qgis-WebSite。

如果您正在阅读这些行，肯定是因为您愿意为编写QGIS文档做出贡献，并且正在寻找操作指南。你来对地方了！目前的文档将指导您通过不同的方法来实现这一目标，向您展示要遵循的主要步骤，您可以使用的技巧和您应该知道的陷阱。
如需任何帮助，请毫不犹豫地要求对您试图修复的问题报告发表评论，或写信给  QGIS-community-team list 。更多详细信息请访问  Get involved in documentation 。
现在让我们深入了解这一过程。
文档源使用Git版本控制系统存储，并可在GitHub上获得，网址为https://github.com/qgis/QGIS-Documentation.要修复的问题和要解释的功能的列表可在https://github.com/qgis/QGIS-Documentation/issues.上找到

小技巧
如果您是第一次投稿，并且不知道从哪里开始，您可能会有兴趣处理我们的  welcoming issue reports 。

修改文件有两种不相互排斥的主要方法：

Using the GitHub web interface
Using Git command line tools 。

1.1. 使用GitHub Web界面
GitHub Web界面允许您执行以下操作：

编辑文件
预览并提交您的更改
发出拉入请求，将您的更改插入到主存储库中
创建、更新或删除分支

如果您还不熟悉Git和GitHub词汇，您可能需要阅读GitHub  Hello-world 学习下面将用到的一些基本词汇和动作的项目。

备注
If you are fixing a reported issue
如果您正在进行更改以修复  issue ，将备注添加到问题报告以将其分配给您自己。这将防止不止一个人在同一问题上工作。

1.1.1. Fork QGIS-文档
假设您已经有一个  GitHub account ，您首先需要分叉文档的源文件。
导航到  QGIS-Documentation repository 页面，并单击  按钮在右上角。
在您的GitHub帐户中，您将找到QGIS文档资料档案库 (https://github.com/<YourName>/QGIS-Documentation )。此存储库是官方QGIS文档存储库的副本，您可以在其中进行完全写入访问，并且可以在不影响官方文档的情况下进行更改。

1.1.2. 做出改变
有几种不同的方式可以为QGIS文档提供帮助。我们在下面单独显示它们，但您可以从一个进程切换到另一个进程，而不会造成任何损害。

备选方案1：使用  Edit on GitHub 捷径
QGIS文档网站上的页面可以通过单击  Edit on GitHub 链接位于每页的右上角。

这将在中打开文件  qgis:master 分支，并在页面顶部显示一条消息，告诉您对此repo没有写访问权限，并且您的更改将应用于存储库的新分支。
做您的更改。由于该文档是使用reStrutireText语法编写的，因此根据您的更改，您可能需要依赖  writing guidelines 。
When you finish, make a short comment about your changes and click on
Propose changes. This will generate a new branch
(patch-xxx) in your repository.
在您点击之后  Propose changes ，GitHub将导航到  Comparing changes 佩奇。

如果您已完成更改，请跳至  Compare changes 在  Share your changes via Pull Request 下面的部分。
如果在将更改提交到QGIS之前需要进行其他更改，请执行以下步骤：

导航到您的QGIS-Documentation分支 (https://github.com/<YourName>/QGIS-Documentation )
点击  并搜索  patch-xxx 布兰奇。选择此补丁程序分支。这个  按钮现在会说  Branch: patch-xxx
跳到  Modify files 下面。

备注
这个  Edit on GitHub 快捷方式也可以在左边栏底部的下拉菜单中找到。

备选方案2：在您的文档存储库中创建一个临时分支
您可以直接从QGIS文档的分支编辑文件。
首先，确保您的  master 分支机构是最新的  qgis:master 布兰奇。要执行此操作，请执行以下操作：

转到存储库的主页，即  https://github.com/<YourName>/QGIS-Documentation 。这个  master 分支机构应处于活动状态，并说明其是否为最新版本  qgis/QGIS-Documentation:master 或者不去。
如果它在上游分支之前提交，您最好使用上一个  shortcut button alternative 直到您将您的  master 布兰奇。
如果它后面只有承诺：

扩展  Fetch Upstream 右侧的下拉菜单。你可以的

Compare 分支，并查看主存储库中的新更改
Fetch and merge ：将更改从上游分支转移到您的分支。

让我们点击  Fetch and merge ：在此过程之后，您的分支机构被提及为最新的  qgis/QGIS-Documentation:master 。

点击  在分叉的QGIS-Documentation存储库的左上角，并在文本字段中输入唯一名称以创建新的  branch 。新分支的名称应该与您要修复的问题相关。这个  按钮现在应该说  Branch: branch_name
你已经准备好在上面开始新的改变了。

注意
Do your changes in an ad hoc branch, never in the master branch
按照惯例，避免在您的  master 分支中的修改合并时除外  master 分支机构  qgis/QGIS-Documentation 到您的QGIS文档库的副本中。单独的分支允许您同时处理多个问题，而不会干扰其他分支。如果您犯了错误，您总是可以删除一个分支，然后通过从主分支创建一个新分支来重新开始。

1.1.3. 修改文件

浏览QGIS-Documentation分支的源文件，找到需要修改的文件
按照以下说明进行修改  writing guidelines
完成后，导航到 Commit Changes 框在页面底部，对您的更改做简短的评论，然后点击  Commit Changes 将更改直接提交到您的分支。确保  Commit directly to the branch_name branch. 处于选中状态。
对需要更新以解决该问题的任何其他文件重复上述步骤

1.1.4. 通过拉取请求共享您的更改
您需要提交请求以将您的更改整合到官方文档中。

备注
If you used an Edit on GitHub link
提交更改后，GitHub将自动打开一个新页面，比较您在  patch-xxx 分支到  qgis/QGIS-Documentation 师傅分部。
跳至  Step 2 下面。

启动新的拉取请求
导航到的主页  QGIS-Documentation 存储库，然后单击  New pull request 。

比较更改
如果您看到两个对话框，其中一个显示  base:master 另一个是  compare:branch_name (见图)，这只会将您的更改从一个分支合并到您的主分支。要解决此问题，请单击  compare across forks 链接。

图 1.1 如果你的  Comparing changes 页面如下所示，请单击  compare across forks 链接。

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

base fork ：要将更改合并到的分支
base ：要将更改合并到的基本分支的分支
head fork ：具有要合并到基本派生中的更改的派生
compare ：具有这些更改的分支机构

选择  qgis/QGIS-Documentation 作为基础叉子与  master 作为基点，将头叉设置为存储库  <YourName>/QGIS-Documentation ，并将比较设置为修改后的分支。

图 1.2 比较以下各项的变化  qgis/QGIS-Documentation 和您的存储库

一张绿色的支票，上面写着 Able to merge 表明您的更改可以合并到官方文档中，而不会发生冲突。
单击  Create pull request 纽扣。

警告
If you see 
这意味着有  conflicts 。您正在修改的文件与您的目标分支不是最新的，因为其他人提交了与您的更改冲突的内容。您仍然可以创建拉入请求，但需要修复任何  conflicts 来完成合并。

小技巧
虽然被翻译了，但  latest version QGIS文档的版本仍得到维护，现有问题已得到修复。如果您要修复不同版本的问题，请更改 base 从…  master to the appropriate release_...  上述步骤中的分支。

描述您的拉取请求
将打开一个文本框：为您要解决的问题填写任何相关备注。
如果这与特定的  issue ，在您的评论中添加问题编号。这可以通过输入#和发行编号( e.g.   #1234 )。如果前面有这样的术语  fix 或  close ，有关问题将在拉式请求合并后立即结束。
添加指向您要更改的任何文档页面的链接。
点击  Create pull request 。

审核并评论拉取请求
如上所述，任何人都可以通过拉请求提交对文档的修改。同样，任何人都可以审查有问题的拉入请求，并  comments 。也许写作风格与项目指导方针不符，更改缺少一些主要细节或屏幕截图，也可能一切看起来都很棒，一切都井然有序。审查有助于提高投稿的质量，无论是形式上还是实质上。
要复查拉式请求，请执行以下操作：

导航到  pull requests page 然后点击您想要评论的Pull请求。
在页面底部，您会发现一个文本框，您可以在其中留下有关Pull请求的一般注释。
要添加有关特定行的注释，请执行以下操作

点击  并找到您要评论的文件。您可能需要点击  Display the source diff 才能看到变化。
滚动到要评论的行，然后单击  。这将打开一个文本框，允许您留下评论。

可以发布特定的行注释：

作为单个注释，使用  Add single comment 纽扣。它们是随你而动出版的。仅当您几乎没有要添加的评论或回复其他评论时才使用此选项。
或者作为审查的一部分，按下  Start a review 纽扣。您的意见不会在验证后自动发送，允许您在以后编辑或取消它们，以添加有关拉式请求的审核要点或全局说明的摘要，以及您是否批准它。这是一种更方便的方式，因为它更灵活，允许你组织你的评论，编辑评论，在你准备好的时候发布，并向存储库的追随者发送一条通知，而不是每条评论都有一条通知。到达  more details 。

图 1.3 用更改建议注释一行

行注释可以嵌入拉式请求编写器可以应用于拉式请求的建议。要添加建议，请单击    ^{Insert a suggestion} 按钮，并修改建议块中的文本。

小技巧
Prefer committing suggestions to your pull request as a batch
作为拉取请求的作者，当直接将审阅者的反馈合并到您的拉取请求中时，应避免使用  Commit suggestion 当您有许多建议要处理并希望将它们作为批提交添加时，请单击注释底部的按钮，即：

切换到  选项卡
新闻发布会  Add suggestion to batch 对于您想要包含的每一次重新措辞。你会看到一个计数器随着你的前进而增加。
按下任何一个  Commit suggestions 当您准备好将建议应用到Pull请求时，请按下按钮，然后输入描述更改的消息。

这将把所有修改作为一次提交添加到您的分支中，从而使更改的历史记录更清晰，并减少对存储库追随者的通知。顺便说一句，这样做还可以节省您的点击次数。

改正
一个新的拉取请求将自动添加到  Pull requests list 。其他编辑和管理员将审查您的拉取请求，他们可能会提出建议或要求更正。
Pull请求还将触发自动构建检查(例如，针对rst格式、python代码语法)，并且报告显示在页面底部。如果发现错误，则会在您的提交旁边显示一个红叉。点击红十字会或点击  Details 在拉入请求页面底部的摘要部分中，查看错误的详细信息。在将更改提交到  qgis/QGIS-Documentation 存储库。
您可以对Pull请求进行修改，直到它与主存储库合并，以改进您的请求、解决请求的修改或修复构建错误。
要进行更改，请单击  选项卡，然后单击铅笔按钮  在您要修改的文件名旁边。
如果您对拉式请求中提交的同一分支机构进行更改，则任何附加更改都将自动添加到您的拉式请求中。因此，仅当这些更改与您打算使用该拉入请求修复的问题相关时，才应进行其他更改。
如果要修复另一个问题，请为这些更改创建一个新分支，然后重复上述步骤。
在更正任何构建错误并在您和管理员对您的更改满意之后，管理员将合并您的贡献包。

1.1.5. 删除合并后的分支机构
您可以在合并更改后删除分支。删除旧分支可以避免存储库中有未使用和过时的分支。

导航到QGIS-Documentation存储库的分支 (https://github.com/<YourName>/QGIS-Documentation )。
按下  Branches 标签。以下  Your branches 您将看到您的分支机构的列表。
按下    ^{Delete this branch} 图标删除任何不需要的分支。

1.2. 使用Git命令行工具
GitHub Web界面是使用您的贡献更新QGIS文档存储库的一种简单方法，但它不提供以下工具：

对提交进行分组并清除更改历史记录
修复与主回购可能发生的冲突
构建文档以测试您的更改

你需要  install git 以便访问更先进和功能更强大的工具，并拥有存储库的本地副本。下面是你可能经常需要的一些基本知识。即使您选择Web界面，您也会发现需要注意的规则。
在下面的代码示例中，以  $ 显示您应该在以下时间键入的命令  # 都是评论。

1.2.1. 本地存储库
现在，您已经准备好获取本地克隆 your QGIS-文档库。
您可以使用Web URL克隆您的QGIS存储库，如下所示：
# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone https://github.com/<YourName>/QGIS-Documentation.git

前面的命令行只是一个例子。您应该同时调整路径和存储库URL，替换  <YourName> 使用您的GitHub用户名。
检查以下各项：
# Enter the local repository
$ cd ./QGIS-Documentation
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
$ git branch
* master

origin 是您的QGIS文档存储库的远程存储库的名称。
master 是默认的主分支。你永远不应该用它来做贡献！ Never!

或者，您可以使用SSH协议克隆您的QGIS存储库：
# move to the folder in which you intend to store the local repository
$ cd ~/Documents/Development/QGIS/
$ git clone git@github.com:<YourName>/QGIS-Documentation.git

小技巧
Permission denied (publickey) error?
如果前面的命令出现权限拒绝(公钥)错误，则可能是您的SSH密钥有问题。看见  GitHub help 了解更多细节。

如果您使用SSH协议，请检查以下各项：
# Enter the local repository
$ cd ./QGIS-Documentation
$ 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流程中称为Pull请求)时，您会遇到很多问题，因为QGIS/QGIS-文档库的主分支将与您的本地/远程存储库不同。然后，您需要跟踪主远程存储库并使用分支。

1.2.2. 添加另一个远程存储库
为了能够跟踪主项目中的工作，请在本地存储库中添加一个新的远程存储库。这个新的远程存储库是QGIS项目中的QGIS文档存储库：
$ git remote add upstream https://github.com/qgis/QGIS-Documentation.git
$ git remote -v
origin  https://github.com/<YourName>/QGIS-Documentation.git (fetch)
origin  https://github.com/<YourName>/QGIS-Documentation.git (push)
upstream        https://github.com/qgis/QGIS-Documentation.git (fetch)
upstream        https://github.com/qgis/QGIS-Documentation.git (push)

同样，您可以使用SSH协议在本地存储库中添加远程存储库：
$ 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 要将您当地的分支机构推向 your 远程存储库
upstream 将您的贡献合并(如果您有权这样做)，或从官方存储库的主分支更新本地存储库的主分支。

备注
upstream 只是一个标签，一种标准的名字，但你可以随心所欲地叫它。

1.2.3. 更新您的基本分支
在使用新的贡献包之前，您应该始终更新本地存储库中的主分支。假设您愿意推动对测试文档的更改，请运行以下命令行：
# switch to master branch (it is easy to forget this step!)
$ git checkout master
# get "information" from the master branch in the 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 (aka <YourName>/QGIS-Documentation)
$ git push origin master

现在，您的本地和远程存储库都有自己的  master 分支机构与官方最新消息  master QGIS的分支--文档。你可以开始做你的贡献了。

备注
如果您希望对已发布的文档做出贡献，请切换分支
与测试文档一起，我们将继续修复  latest release ，这意味着你也可以为它做贡献。遵循上一节的样例代码，替换  master 与相应分部的最新文件。

1.2.4. 为您的生产部门做出贡献
现在您的基本分支已经更新，您需要创建一个专用分支，在其中添加您的贡献。始终在基本分支之外的分支上工作！一直都是！
# Create a new branch
$ git checkout -b myNewBranch
# checkout means go to the branch
# and -b flag creates a new branch if needed, based on current branch
# Let's check the list of existing branches (* indicates the current branch)
$ git branch
master
release_2.18
...
* myNewBranch
# You can now add your contribution, by editing the concerned file(s)
# with any application (in this case, vim is used)
$ vim myFile
# once done
$ git add myFile
$ git commit

以下是关于提交/推送命令的几句话：

尝试只做出一项贡献(原子变化)，即只解决一个问题
尝试仔细解释您在提交的标题和描述中所做的更改。第一行是标题，应以大写字母开头，长度为80个字符，不能以  .. Be concise. Your description can be longer, end with a .  你可以给出更多的细节。
使用  # 用一个数字来表示一个问题。前缀为  Fix 如果你修复了罚单：你的承诺将关闭罚单。

现在您的更改已保存并提交到您的本地分支，您需要将它们发送到您的远程存储库以创建拉入请求：
$ git push origin myNewBranch

1.2.5. 共享您的更改
现在，您可以转到GitHub存储库并  create a Pull Request 正如上一节所揭示的那样。确保您在官方QGIS文档存储库中创建了从您的分支机构到远程分支机构的PR。

1.2.6. 清理本地和远程存储库
在您的公关被合并到QGIS官方文档后，您可以删除您的分支。如果你以这种方式大量工作，几周内你就会得到很多无用的分支。因此，通过以下方式保持您的存储库清洁：
# delete local branch
$ git branch -d myNewBranch
# Remove your remote myNewBranch by pushing nothing to it
$ git push origin :myNewBranch

并且不要忘记更新  master 分支机构在您的本地存储库中！

1.3. 进一步阅读

除了上面介绍的Github Web界面和Git命令行工具之外，还有  GUI applications 您可以使用创建和管理您对文档的贡献。

当拉入请求中的更改与推送到目标分支的最新更改冲突时，需要先解决冲突，然后才能进行合并：

如果冲突与较少的竞争线路有关，则  Resolve conflicts 按钮在GitHub拉取请求页面中可用。按按钮并按照中的说明解决问题  Resolving a merge conflict on GitHub
如果冲突涉及文件重命名或删除，则需要使用git命令行来解决冲突。通常，您必须首先使用以下命令将分支重新定位到目标分支上  git rebase targetBranch 呼叫并修复报告的冲突。有关更多信息，请访问  Resolving a merge conflict using the command line

有时，在校对过程结束时，您可能会将更改分成多个提交，这不一定值得。Git命令行可帮助您将这些提交压缩为数量更少、更有意义的提交消息。有关详细信息，请访问  Using git rebase on the command line

1. 一步一步的贡献

1.1. 使用GitHub Web界面 

1.1.1. Fork QGIS-文档 

1.1.2. 做出改变 

备选方案1：使用 `Edit on GitHub` 捷径 

备选方案2：在您的文档存储库中创建一个临时分支 

1.1.3. 修改文件 

1.1.5. 删除合并后的分支机构 

1.2. 使用Git命令行工具 

1.2.1. 本地存储库 

1.2.2. 添加另一个远程存储库 

1.2.3. 更新您的基本分支 

1.2.4. 为您的生产部门做出贡献 

1.2.6. 清理本地和远程存储库 

1.3. 进一步阅读 