欢迎来到 AsciiDoc 语言项目！我们很高兴你对帮助提升 AsciiDoc 成为最佳轻量级标记语言表现出兴趣。我们欢迎各种形式的贡献，不仅仅是代码。这包括用户场景和需求、测试、文档、基础设施自动化等等。继续阅读以了解我们的工作方式以及如何参与进来。

沟通

我们使用公共邮件列表和问题跟踪器进行通信。

开发者邮件列表

这个邮件列表是您可以提出问题、表达关注、进行一般讨论以及对AsciiDoc语言的开发、其规范、语法和TCK（技术兼容性工具包）提出想法的地方。关于该项目状态和其他社区活动的公告也会发布到这个邮件列表。

Project issue tracker

项目的问题追踪器与Eclipse的GitLab实例上的代码仓库并列存在。使用问题追踪器来提交bug报告、规范增补与澄清请求，以及用户文档问题。问题追踪器也是项目团队管理里程碑和发布开发工作的地方。

AsciiDoc WG 邮件列表

这个规范项目隶属于 https://projects.eclipse.org/working-group/asciidoc [AsciiDoc 工作组]。这个列表是发布和讨论Eclipse的AsciiDoc项目以及整个生态系统的愿景、范围、治理和宣传更新的地方。

行为准则

AsciiDoc 语言项目及其项目空间受到[Eclipse社区行为守则](https://www.eclipse.org/org/documents/Community_Code_of_Conduct.php)的约束。通过参与，您应当遵守这一准则。有关我们的价值观和社区行为，请查看项目的治理过程以获得更多信息。让我们共同努力，使这成为一个欢迎、专业、包容且安全的环境，供大家共同参与。

在提交你的第一个合并请求（MR）之前，请完成以下步骤：

  1. 注册一个[Eclipse Foundation账户]。如果你已经在开发者或工作组邮件列表中发过帖子，那么你已经设置了一个账户。

    1. 确保使用您打算在提交项目仓库时使用的同一个电子邮件地址进行注册。

    2. 您的 Eclipse Foundation 账户登录也将登录到[Eclipse GitLab 实例] https://gitlab.eclipse.org。

  2. 电子签署[Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php)。

    1. 要检查你是否已经签署了ECA，[登录你的Eclipse账户](https://accounts.eclipse.org/user/login)并前往你的个人资料页面。在你个人资料页面的右上角寻找*状态*侧边栏。如果你看到*Eclipse Contributor Agreement*旁有一个绿色的勾选标记，那么你就已经准备就绪了。

关于Eclipse基金会账户和ECA的更多信息，请见Eclipse手册中的[贡献到Eclipse项目](https://www.eclipse.org/projects/handbook/#contributing)部分。

为规范和TCK做出贡献

这个项目维护AsciiDoc语言规范、技术兼容性套件（TCK）及其相关材料。规范和TCK是为开发实现、扩展以及处理AsciiDoc的其他工具的开发者所准备的。这个项目遵循[Eclipse Foundation Specification Process]（EFSP）并且受[Eclipse IP Policy]的约束。

规格范围和发布计划

在为这个项目做出贡献之前，请确保你已经熟悉了项目的[已批准的范围]和[当前发布计划]。问题和合并请求必须符合项目的范围，并有助于实现当前发布计划的目标和里程碑。如果你不确定某个想法是否符合项目范围或与发布计划一致，请联系项目团队的https://accounts.eclipse.org/mailing-list/asciidoc-lang-dev[开发邮件列表]。

规格问题

行动性问题报告应该具体且全面。如果您需要收集输入和反馈以帮助准备提交问题报告，我们鼓励您首先在https://accounts.eclipse.org/mailing-list/asciidoc-lang-dev[开发邮件列表]上发帖。不过，请记住，邮件列表并不是做最终决策的地方。相反，这是问题跟踪器的角色。一旦提交了问题，关于该主题的讨论应该保留在[issue tracker] https://gitlab.eclipse.org/eclipse/asciidoc/asciidoc-lang/-/issues 中。

下面列出了一些广泛的问题类别及其应提供的信息。

问题报告（种类|错误）

Bug报告应描述看起来不正确的语法、功能或行为，描述您得到的结果以及您期望的结果。您提供的细节越多，团队就能越快尝试复现这个bug。

规格更新（种类|特征）

规范更新，例如新功能请求、改进、澄清以及可能对兼容实现、扩展、用户或整个AsciiDoc生态系统产生重大影响的移除，应描述存在问题或期望的场景，解决或实现场景的可能途径，以及变更对兼容实现、用户和AsciiDoc生态系统的正负面影响。这样的问题在接受提出的解决方案之前，需要由负责相关规范领域的团体进行评估。

规格形式化（种类|形式化）

规范形式化问题指的是需要在规范文件中定义和描述的现有特性。与那些有模棱两可或问题参数或行为的重大特性添加或更新不同，这些特性相对无争议且理解清晰。

术语和命名（区域/命名与术语）

涉及定义、澄清或更改规范术语、术语定义、名称和命名模式的问题应提供术语或名称的当前状态、建议的更改以及更改的原因。术语和命名必须考虑许多因素，如用户和开发者的心智模型、包容性语言、用例的共性、保留字冲突以及可用性（例如，键盘布局、本地化、可访问性）。这样的问题可能需要由维护相关规范区域的小组进行评估。

问题处理流程

项目团队会在问题分类过程中向问题添加标签。问题的处理时间取决于bug的严重性、当前发布计划和里程碑，以及维护相关规范领域的项目团队成员的可用性。没有标记为*triage|accepted*的问题尚未被项目接受。根据项目的决策进程，项目对问题进行评估和接受。

规范合并请求指南

  • 一个合并请求（MR）应当仅针对问题跟踪器中记录的一个具体问题。

    • 例外情况是对于打字错误、小的语法和句子结构变动，以及格式修正的修订请求（Merge Requests）。

  • 标记为 triage|accepted 的问题已准备好进行合并请求（MR）。

  • 将自己分配到合并请求（MR）将要解决的问题上。除非你已经跟他们或项目团队讨论过，否则不要将自己分配到已经分配给其他人的问题上。

  • 对核心规范概念、特性或行为进行重大更改的MR（合并请求），以及对AsciiDoc生态系统有重大影响的MR，需要至少两名团队提交者的审查和批准。

  • 所有其他的合并请求（MRs）必须由至少一名团队提交者审核并批准。何时对一个合并请求进行审查取决于具备适当专业知识的团队成员的可用性以及当前发布周期的阶段。

直到所做的更改是完整的、正确无误的、并且格式良好（意味着它通过了所有自动测试和手动测试、代码审查、团队审阅等），一个合并请求（MR）才会被批准。我们不能期望未来有人来修复一个MR已知的缺陷，因为"未来"往往意味着"永不"。如果MR中有争议的部分阻碍了合并，可以把那部分内容提取出来形成一个新的MR，这样剩余部分就可以继续前进，通过审查/合并流程。

我们鼓励您在实现复杂功能或进行影响规范多个领域的修改时尽早开启一个合并请求（MR）。可以在MR标题前加上WIP:（工作进行中）或Draft:（草案），手动或使用MR界面。这允许团队在您最终确定MR之前开始提供反馈，并有助于创造出更好的最终产品。

有关逐步的MR指令，请参见本地仓库设置和MR工作流程章节。

命名空间和本地仓库设置

您必须在准备您的第一个合并请求之前完成以下步骤。如果您不熟悉git，可以查阅https://gitlab.eclipse.org/help/topics/git/index.md[GitLab的git帮助主题]，以获取学习资源列表。

  1. 确保你已经设置好你的Eclipse账户并且签署了ECA（贡献者协议）。

  2. 转到 AsciiDoc 语言仓库，并将其复刻到你的个人命名空间。该项目不接受不来自复刻中的专用分支的合并请求。

  3. 克隆仓库到你的机器上并配置你的远程路径。

  4. 推荐但非强制。如果您计划经常为项目做出贡献，我们建议将您的GPG密钥与您的本地仓库和GitLab账户关联，以便您可以用它来签署您的提交。

    1. 参阅 https://gitlab.eclipse.org/help/user/project/repository/gpg_signed_commits/index.md [使用GPG签名提交] 以了解如何生成GPG密钥以及如何配置您的本地仓库自动签署您的提交。如果您在设置GPG密钥或将其与您的帐户关联时遇到问题，请在 开发邮件列表 上联系项目团队。

合并请求工作流步骤

每次处理新问题时，请遵循以下步骤。

  1. 你想提交的更改是问题跟踪器中的一个问题的解决方案吗（在几乎所有情况下都应该是这样的）？如果是：

    1. 确保问题处于准备进行合并请求的状态。

    2. 将自己分配到这个问题上。在问题的评论中输入快捷操作`/assign me`然后提交它。

  2. 当你准备好进行更改时，请将问题的状态更新为活跃。

    1. 在问题的评论中输入快速操作命令`/label ~status::active`并提交。任何先前的状态标签将会被自动移除。

  3. 在你的本地仓库中，创建一个新的分支来进行你的更改工作（永远不要从你的主分支提交合并请求）。

    1. 将您的分支命名为它解决的问题编号以及简短的文字提示，例如，issue-2-short-description。这将使您的合并请求更容易审查。

  4. 如果更改很小，比如是一个打字错误或格式修正，并且不需要一个问题单，那么在你的本地仓库中创建一个新分支，在那里进行你的更改工作。

    1. 分支名称应该是一个简短的文字提示，例如`fix-short-description`。

  5. 在你的新分支中做出修改。

    1. 不要重构、重新格式化或清理与合并请求(MR)解决的问题无直接关系的代码或内容。

  6. 提交你的更改。

    1. 提交信息应简洁且具体。信息中应该使用一个[closing pattern](https://gitlab.eclipse.org/help/user/project/issues/managing_issues.md#closing-issues-automatically)来引用它解决的问题，并提供一个简短的描述，例如，fixes #1 简短描述、resolves #1 简短描述`或`closes #1 简短描述。这会让你的合并请求更容易被审查和批准。

    2. 只有当个别显著变更需要在仓库的日志中特别记载时，才会为每个合并请求创建多个提交。

    3. 在多次迭代修改文件时，如果忘记增加了某些更改或者文件等，应该对你的提交进行压缩或修改。

  7. 将分支推送到你的远程分叉仓库。

  8. 将分支作为MR提交，使用在您推送分支后终端中显示的GitLab界面或URL。

    1. 就像提交信息一样，合并请求(MR)标题应该使用 关闭模式 引用其解决的问题，并提供简短的描述，例如，fixes #1 简短描述、resolves #1 简短描述`或`closes #1 简短描述。这将使您的MR更容易被审查。

    2. 如果您仍在完成您的合并请求（MR）并希望在其完成之前获得反馈，请在MR标题前加上WIP:（例如，WIP: resolves #2 add build test）或Draft:。当MR准备好进行最终审查时，从MR标题中移除WIP:或Draft:。

  9. 项目团队的一名成员将会审阅你的合并请求（MR）。在审阅过程中，他们可能会要求对你的合并请求（MR）进行更改。

    1. MR不会被批准，直到更改完成、正确且格式良好（意味着它通过了所有自动化和手动测试、代码静态分析、团队审查等）。

  10. 审核员可能会要求你在批准和合并你的合并请求之前，压缩或修改你的提交。