附录 A：贡献文档_Hbase 中文文档

Apache HBase 项目欢迎对项目的所有方面做出贡献，包括文档。

在 HBase 中，文档包括以下几个方面，可能还包括其他方面：

HBase 参考指南（本书）
HBase 网站
API 文档
命令行实用程序输出和帮助文本
Web UI 字符串，显式帮助文本，上下文相关字符串等
记录消息
源文件，配置文件和其他内容中的注释
将上述任何一种语言本地化为英语以外的目标语言

无论您想要帮助哪个区域，第一步几乎总是下载（通常通过克隆 Git 存储库）并熟悉 HBase 源代码。有关下载和构建源的信息，请参阅开发人员。

A.1。有助于文档或其他字符串

如果您在 UI，实用程序，脚本，日志消息或其他地方的字符串中发现错误，或者您认为某些内容可以更清晰，或者您认为文本需要添加到当前不存在的位置，那么第一个步骤是提交 JIRA。除了任何其他相关组件外，务必将组件设置为Documentation。大多数组件都有一个或多个默认所有者，他们监视进入这些队列的新问题。无论您是否能够修复该错误，您仍应该在看到错误的地方提交错误。

如果您想尝试修复新提交的错误，请将其分配给自己。您需要将 HBase Git 存储库克隆到本地系统并在那里解决问题。当您开发出潜在的修复程序时，请将其提交以供审核。如果它解决了这个问题并被视为一种改进，那么其中一个 HBase 提交者将根据需要将其提交给一个或多个分支。

过程：提交补丁的建议工作流程

这个程序比 Git 专业人员需要的更详细，但是包含在本附录中，以便不熟悉 Git 的人在学习时能够对 HBase 有信心。

如果您还没有这样做，请在本地克隆 Git 存储库。你只需要这样做一次。
通常，在检出跟踪分支时，使用git pull命令将远程更改拉入本地存储库。
对于您处理的每个问题，请创建一个新分支。一个适用于命名分支的约定是将给定分支命名为与其相关的 JIRA：
```
$ git checkout -b HBASE-123456 
```
在您的分支上进行建议的更改，经常将更改提交到本地存储库。如果您需要切换到处理其他问题，请记得检查相应的分支。
当您准备好提交补丁时，首先要确保 HBase 构建干净，并在修改的分支中按预期运行。
如果您更改了文档，请确保通过运行mvn clean site来构建文档和网站。
如果您需要几天或几周的时间来实施修复，或者您知道您正在使用的代码区域最近有很多更改，请确保将分支重新绑定到远程主服务器并处理任何冲突在提交补丁之前。
```
$ git checkout HBASE-123456
$ git rebase origin/master 
```
针对远程主服务器生成补丁。从 git 存储库的顶层运行以下命令（通常称为hbase）：
```
$ git format-patch --stdout origin/master &gt; HBASE-123456.patch 
```
补丁的名称应包含 JIRA ID。
查看补丁文件，确保您没有意外更改任何其他文件，并且没有其他意外。
如果您满意，请将补丁附加到 JIRA 并单击 Patch Available 按钮。审核人员将审核您的补丁。
如果您需要提交新版本的补丁，请将旧版本保留在 JIRA 上，并在新补丁的名称中添加版本号。
提交更改后，无需保留本地分支。

A2。编辑 HBase 网站

HBase 网站的源代码位于 HBase 源代码的 src / site / 目录中。在此目录中，各个页面的源位于 xdocs / 目录中，这些页面中引用的图像位于 resources / https://hbase.apache.org/images 中/ 目录。此目录还存储 HBase 参考指南中使用的图像。

该网站的页面是用类似 HTML 的 XML 方言编写的，名为 xdoc，在 https://maven.apache.org/archives/maven-1.x/plugins/xdoc/reference/xdocs 上有参考指南。 html 。您可以在纯文本编辑器，IDE 或 XML 编辑器（如 XML Mind XML Editor（XXE）或 Oxygen XML Author）中编辑这些文件。

要预览更改，请使用mvn clean site -DskipTests命令构建网站。 HTML 输出位于 _ 目标/站点/_ 目录中。如果对更改感到满意，请按照提交文档修补程序中的步骤提交补丁。

A.3。发布 HBase 网站和文档

HBase 使用 ASF 的gitpubsub机制。 Jenkins 作业运行dev-support/jenkins-scripts/generate-hbase-website.sh脚本，该脚本针对hbase存储库的master分支运行mvn clean site site:stage，并将构建的工件提交到hbase-site存储库的asf-site分支。按下提交后，将自动重新部署网站。如果脚本遇到错误，则会向开发人员邮件列表发送一封电子邮件。您可以手动运行脚本或检查脚本以查看所涉及的步骤。

A.4。检查 HBase 网站的断开链接

Jenkins 作业定期运行，使用dev-support/jenkins-scripts/check-website-links.sh脚本检查 HBase 网站是否有损坏的链接。此脚本使用名为linklint的工具检查错误链接并创建报告。如果找到损坏的链接，则会向开发人员邮件列表发送一封电子邮件。您可以手动运行脚本或检查脚本以查看所涉及的步骤。

A.5。 HBase 参考指南样式指南和备忘单

HBase 参考指南用 Asciidoc 编写，使用 AsciiDoctor 构建。以下备忘单供您参考。更多细微而全面的文档可在 http://asciidoctor.org/docs/user-manual/ 上找到。

元素类型	期望的渲染	怎么做
一个段落	一个段落

只需键入一些顶部和底部带有空行的文本。

| |在段落中添加换行符而不添加空行|手动换行|

这将在加号处打破+。或者在整个段落前面加上包含'[％hardbreaks]'的行

text

| |内联文字内容（完全按照所示输入的内容）|大胆的单声道|

typethis

| |内联可替换内容（用您自己的值替换的东西）|粗斜体单声道|

__ 类型的东西 __

| |突出显示的代码块|等宽，突出，保留空间|

[source,java]
----
  myAwesomeCode() {
}
----

| |代码块包含在单独的文件中包括就好像它是主文件的一部分|

[source,ruby]
----
include\::path/to/app.rb[]
----

| |仅包含单独文件的一部分|与 Javadoc 相似|

见 http://asciidoctor.org/docs/user-manual/#by-tagged-regions

| |文件名，目录名，新术语|斜体|

hbase-default.xml

| |外部裸 URL |链接 URL 作为链接文本|

link:http://www.google.com

| |带文字的外部网址|带有任意链接文本的链接|

link:http://www.google.com[Google]

| |创建内部锚点以交叉引用|没有呈现|

[[anchor_name]]

| |使用其默认标题|交叉引用现有锚点使用元素标题的内部超链接（如果可用），否则使用锚名称|

<<anchor_name>>

| |使用自定义文本交叉引用现有锚点使用任意文本的内部超链接

<<anchor_name,Anchor Text>>

| |块图像|替代文字的图像|

image::sunset.jpg[Alt Text]

（将图像放在 src / site / resources / images 目录中）

| |内嵌图像|带有 alt 文本的图像，作为文本流程的一部分

image:sunset.jpg [Alt Text]

（只有一个冒号）

| |链接到远程图像|显示在别处托管的图像|

image::http://inkscape.org/doc/examples/tux.svg[Tux,250,350]

（或image:）

| |向图像添加尺寸或 URL |取决于|

在 alt 文本后的括号内，指定 width，height 和/或 link =“ http://my_link.com ”

| |脚注|下标链接带你到脚注|

Some text.footnote:[The footnote text.]

| |没有标题的注释或警告|告诫图像后面跟着警告|

NOTE:My note here

WARNING:My warning here

| |复杂的笔记|该笔记有一个标题和/或多个段落和/或代码块或列表等

.The Title
[NOTE]
====
Here is the note text. Everything until the second set of four equals signs is part of the note.
----
some source code
----
====

| |子弹列表|子弹列表|

* list item 1

（见 http://asciidoctor.org/docs/user-manual/#unordered-lists ）

| |编号列表|编号列表|

. list item 2

（见 http://asciidoctor.org/docs/user-manual/#ordered-lists ）

| |清单|选中或未选中的复选框|

经过：

- [*]

未选中：

- [ ]

| |多级列表|项目符号或编号或组合|

. Numbered (1), at top level
* Bullet (2), nested under 1
* Bullet (3), nested under 1
. Numbered (4), at top level
* Bullet (5), nested under 4
** Bullet (6), nested under 5
- [x] Checked (7), at top level

| |标记列表/变量列表|列表项标题或摘要后跟内容|

Title:: content

Title::
  content

| |侧栏，引号或其他文本块|一个文本块，格式与默认值不同

使用不同的分隔符分隔，请参阅 http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary 。上面的一些例子使用分隔符，如....，----，====。

[example]
====
This is an example block.
====

[source]
----
This is a source block.
----

[note]
====
This is a note block.
====

[quote]
____
This is a quote block.
____

如果要插入一直保持被解释的文字 Asciidoc 内容，如果有疑问，请在顶部和底部使用八个点作为分隔符。

| |嵌套部分|章节，节，小节等|

= Book (or chapter if the chapter can be built alone, see the leveloffset info below)

== Chapter (or section if the chapter is standalone)

=== Section (or subsection, etc)

==== Subsection

等等多达 6 个级别（仔细考虑深入 4 级以上，也许你可以选择标题段落或列表）。请注意，您可以通过在 include 之前直接添加:leveloffset:+1宏指令将一本书包含在另一本书中，然后将其重置为 0。有关示例，请参阅 book.adoc 源代码，因为这是本指南处理章节的方式。 不要为前言，术语表，附录或其他特殊类型的章节做这些。

| |包含另一个文件|内容包含在内，就像它是内联的一样

include::[/path/to/file.adoc]

有很多例子。见 book.adoc 。

| |一张桌子|一张桌子|

见 http://asciidoctor.org/docs/user-manual/#tables 。通常，行由换行符和换行符按管道分隔

| |注释掉一行|渲染时跳过一行|

// This line won’t show up

| |注释掉一个块|在渲染过程中会跳过文件的一部分

////
Nothing between the slashes will show up.
////

| |突出显示要审阅的文本|文本显示黄色背景|

Test between #hash marks# is highlighted yellow.

A.6。自动生成的内容

HBase 参考指南的某些部分，特别是 config.files ，是自动生成的，因此文档的这个区域与代码保持同步。这是通过 XSLT 转换完成的，您可以在 _src / main / xslt / configuration_to_asciidoc chapter.xsl 的源代码中查看。这会将 hbase-common / src / main / resources / hbase-default.xml 文件转换为 Asciidoc 输出，该输出可以包含在参考指南中。

有时，需要添加配置参数或修改其描述。对源文件进行修改，重建后它们将包含在“参考指南”中。

将来可能并且将从 HBase 源文件自动生成其他类型的内容。

A.7。 HBase 参考指南中的图像

您可以在 HBase 参考指南中包含图像。如果可能，重要的是包括图像标题，并始终包括替代文本。这允许屏幕阅读器导航到图像并且还为图像提供替代文本。以下是带有标题和替代文本的图像示例。注意双冒号。

.My Image Title
image::sunset.jpg[Alt Text]

以下是带有替换文本的内嵌图像的示例。注意单个冒号。内嵌图像不能有标题。它们通常是像 GUI 按钮这样的小图像。

image:sunset.jpg[Alt Text]

进行本地构建时，将图像保存到 src / site / resources / https://hbase.apache.org/images/ 目录。链接到图像时，请不要包含路径的目录部分。在构建输出期间，图像将被复制到适当的目标位置。

当您提交包含将图像添加到 HBase 参考指南的修补程序时，请将图像附加到 JIRA。如果提交者询问应该提交映像的位置，它应该进入上面的目录。

A.8。在 HBase 参考指南中添加新章节

如果要在 HBase 参考指南中添加新章节，最简单的方法是复制现有的章节文件，重命名它，并更改 ID（在双括号中）和标题。章节位于 src / main / asciidoc / _ 章节/ 目录中。

删除现有内容并创建新内容。然后打开 src / main / asciidoc / book.adoc 文件，该文件是 HBase 参考指南的主文件，并复制现有的include元素以将新章节包含在适当的位置。在创建补丁之前，请务必将新文件添加到 Git 存储库。

如有疑问，请检查其他文件是如何包含的。

A.9。常见文档问题

经常出现以下文档问题。其中一些是偏好，但其他人可能会产生神秘的构建错误或其他问题。

_ 隔离更改以便进行简易差异检查。_

小心漂亮打印或重新格式化整个 XML 文件，即使格式随着时间的推移而降级。如果您需要重新格式化文件，请在不更改任何内容的单独 JIRA 中执行此操作。请注意，因为某些 XML 编辑器在您打开新文件时会进行批量重新格式化，尤其是在编辑器中使用 GUI 模式时。
_ 语法突出显示 _

HBase 参考指南使用coderay进行语法高亮显示。要为给定代码清单启用语法突出显示，请使用以下类型的语法：
```
[source,xml]
----
&lt;name&gt;My Name&lt;/name&gt;
---- 
```
支持几种语法类型。 HBase 参考指南中最有趣的是java，xml，sql和bash。