如何贡献

本指南提供了有关如何为 Gambas 源代码和翻译做出贡献的分步教程。

它将涵盖代码的组织、一些贡献指南以及如何使用 Git 和 GitLab 来提交您的贡献。

使用 Git 和 GitLab

Gambas 源代码由托管在 GitLab.com 上的 Git 存储库管理。

为了处理新的贡献，我们使用项目分支Project forking workflow工作流程：由于贡献者没有直接写入 Gambas 源代码的权限，因此你必须创建一个包含更改的单独存储库，然后创建一个合并请求，询问 Gambas 开发人员将你的更改合并到主存储库中。

虽然这对于新贡献者来说可能听起来很复杂，但本文档旨在逐步指导完成此过程。

如果您在执行此处提到的步骤时遇到问题，或者您对贡献有任何疑问，您可以在邮件列表 ask on the mailing-list 上提问。

创建 GitLab 帐户

首先，您需要一个GitLab account 帐户才能提交任何更改。

我们还建议您使用 SSH （use SSH to work with Git repositories）,而不是 HTTPS来处理 Git 存储库。不仅不必每次与存储库交互时都输入 GitLab 用户名和密码，而且也更安全，因为你的密码永远不会通过网络发送。

您还可以使用 GPG use GPG to sign your commits 来签署你的提交，但这不是必需的。

分支 Gambas 存储库

现在你的 GitLab 帐户已设置完毕，我们现在可以分支 fork the Gambas repository Gambas 存储库了。这将创建 Gambas 存储库的副本，但它将属于你，因此你可以进行任何你想要的更改。

为此，只需转到 Gambas project page 项目页面，然后单击“Fork”按钮。

然后系统会询问您将分支存储库放在哪里。完成后，新的存储库将出现在你的帐户下。

然后，你可以使用以下命令将存储库克隆到本地计算机（替换 <yourusername> 为你的 GitLab 用户名）：

更改你的存储库

克隆完成后，你可以对本地副本进行更改，然后必须提交并推送该副本。

首先，您可以检查您使用 git status。 在提交之前检查一下总是好的！您还可以使用命令查看完整的差异 git diff。

一切完成后，您必须使用git add 命令选择接下来要提交的文件。

您也可以使用选择特定文件或目录 git add file1.c file2.c main/gbx，也可以使用 选择所有内容 git add -A。

然后你可以使用该命令进行提交 git commit。此命令将打开一个编辑器，让你编写提交消息。

有关如何编写提交消息的一些指南，请参阅编写提交消息部分。

此命令将启动默认编辑器（通常 vi），但你可以通过将 EDITOR 环境变量设置为启动你喜欢的编辑器的命令来更改此设置。

现在提交已完成，您可以使用 git push 命令将其推送到 GitLab 存储库。

创建合并请求

现在你的更改已推送到 GitLab 存储库，最后一步是创建合并请求Merge Request，请 Gambas 开发人员将您的更改合并到主 Gambas 存储库。

由于此过程完全通过 GitLab 完成，因此请使用以下说明来创建合并请求 use the following instructions to create your merge requests.。

你的更改很可能不会立即被接受，Gambas 维护人员会要求您进行一些更改。

在这种情况下，你可以进行更改、提交并推送它们。 GitLab 上的合并请求将自动更新，你无需重新创建它。

使你的存储库保持最新

在你更改 Gambas 源代码版本期间，或者在审核你的请求时，Gambas 存储库可能会收到一些更新。

由于分支存储库基本上是一个克隆，因此官方版本和你的版本完全独立，因此它不会自动接收更新的提交。

但是，你可以将本地存储库设置为连接到这两个存储库，这样你就可以从官方 Gambas 存储库中提取更改，将它们与本地更改合并，然后将它们推送到你的分支存储库。

首先，我们将通过添加本地 Git 存储库的远程跟踪分支作为第二个远程存储库：

我们现在已经添加了一个名为本地存储库的远程跟踪分支 upstream ，指向原始 Gambas 存储库。 （你可以使用该命令列出所有远程跟踪分支 git remote -v 。）

这意味着 Git 现在可以使用以下命令从原始 Gambas 存储库中提取更改：

此命令将从 upstream 远程分支获取 master 分支的更改。

如果你自己版本的存储库进行过提交，它将与新的更改合并，创建一个新的合并提交。

合并完成后，您只需 git push 将所有这些更改推送到你的存储库版本即可。如果你有任何待处理的合并请求，它们将自动更新。

编写提交消息

为了自动生成每个版本的变更日志，Gambas 存储库中的提交必须遵循非常特定的格式。

这是一个例子：

根据 Git 提交消息约定，每个提交的第一行是对其所包含内容的简短描述。该行不会出现在变更日志中，但会出现在 git 日志以及 GitLab 界面中。

然后，提交消息由以下部分组成：

• 一个方括号，更改组件在中间 (e.g. [GB.QT4])

• 一个或多个修改，每个修改都以一个标签为前缀，该标签可以是 * NEW: , * BUG: , or * OPT: , 末尾有一个空格。

方括号内的名称是修改的组件之一（大写）, 或者如果更改不影响组件，则为其中之一：

• [INTERPRETER] 对于解释器 (gbx3)的更改.

• [COMPILER] 对于编译器的更改 (gbc3).

• [ARCHIVER] 对于存档器的更改 (gba3).

• [INFORMER] 对于informer (gbi3)的更改

• [DEVELOPMENT ENVIRONMENT] 对于 IDE (gambas3)的更改.

• [CONFIGURATION] 对于 automake/autoconf 配置处理的更改

• [WIKI CGI SCRIPT] 对于维基 CGI 脚本中的更改

• [WEB SITE MAKER] 对于 Gambas 网站生成器的更改

• [EXAMPLES] 对于任何事例的更改.

标签的名称是以下之一：

• NEW 用于新功能或翻译、更新或其他改进；

• BUG 用于错误修复和其他更正

• OPT 用于优化

对用户没有影响的事情（例如重构或代码清理）不应出现在变更日志中。

所有没有标签的行都不会出现在变更日志中，但如果您希望修改跨越多行，则必须在其前面添加两个空格。