5. 贡献文档

文档位于自己的源代码树中。我们将从 fork 和克隆 CouchDB 文档 GitHub 镜像开始。这将使我们能够通过拉取请求将贡献发送到 CouchDB。

如果您还没有 GitHub 帐户，现在是获取一个的好时机，它们是免费的。如果您不想使用 GitHub，还有其他方法可以贡献回来，我们将在下次介绍。

转到 https://github.com/apache/couchdb 并点击右上角的“fork”按钮。这将在您的 GitHub 帐户中创建一个 CouchDB 的 fork。如果您的帐户是 username，您的 fork 位于 https://github.com/username/couchdb。在标题中，它会告诉我我的“GitHub 克隆 URL”。我们需要复制它并启动一个终端

$ git clone https://github.com/username/couchdb.git
$ cd couchdb/src/docs
$ subl .

我在我最喜欢的编辑器中打开整个 CouchDB 文档源代码树。它给了我通常的目录列表

ebin/
ext/
.git/
.gitignore
images/
LICENSE
make.bat
Makefile
NOTICE
rebar.config
src/
static/
templates/
themes/
.travis.yml

文档源代码位于 src/docs/src 中，您可以安全地忽略所有其他文件和目录。

首先，我们应该确定我们想在文档中记录这个内容的位置。我们可以查看 https://couchdb-docs.apache.org/en/latest/ 以获得灵感。 JSON 结构参考 看起来是一个写这个内容的好地方。

当前状态主要包括描述 JSON 结构的表格（毕竟，这是本章的标题），但关于数字表示的一些散文并不会有害。为了将来参考，由于线程中的主题包括视图和视图中的不同编码（与存储引擎相反），我们应该记住在视图文档中也做一个注释，但我们将在以后进行。

让我们尝试找到构建文件 https://couchdb-docs.apache.org/en/latest/json-structure.html 的源文件 - 我们很幸运，在 share/doc/src 下我们找到了文件 json-structure.rst。这看起来很有希望。 .rst 代表 ReStructured Text（参见 http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html 获取标记参考），它是一种用于编写文档的 ASCII 格式，在本例中是文档。让我们看看并打开它。

我们看到带有额外格式的 ASCII 表格，所有这些看起来都像最终的 HTML。到目前为止，一切都非常简单。现在，让我们只添加到这个文件的底部。我们可以稍后担心更好地组织它。

我们从添加一个新的标题开始

Number Handling
===============

现在我们将线程的主要电子邮件的其余部分粘贴进去。它主要是文本，但它包含一些代码列表。让我们标记它们。我们将

ejson:encode(ejson:decode(<<"1.1">>)).
<<"1.1000000000000000888">>

变成

.. code-block:: erlang

    ejson:encode(ejson:decode(<<"1.1">>)).
    <<"1.1000000000000000888">>

我们继续处理其他代码示例。我们将

Spidermonkey

$ js -h 2>&1 | head -n 1
JavaScript-C 1.8.5 2011-03-31
$ js
js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
"1.0123456789012346"
js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
js> JSON.stringify(JSON.parse(f))
"1.0123456789012346"

变成

Spidermonkey::

    $ js -h 2>&1 | head -n 1
    JavaScript-C 1.8.5 2011-03-31
    $ js
    js> JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
    "1.0123456789012346"
    js> var f = JSON.stringify(JSON.parse("1.01234567890123456789012345678901234567890"))
    js> JSON.stringify(JSON.parse(f))
    "1.0123456789012346"

然后继续处理所有其他代码示例。

我稍微清理了一下文本，使其听起来更像一个文档条目，而不是邮件列表上的帖子。

下一步将是验证我们是否正确地获得了所有标记。我将在以后进行。现在，我们将把我们的更改贡献回 CouchDB。

首先，我们提交我们的更改

$ > git commit -am 'document number encoding'
[main a84b2cf] document number encoding
1 file changed, 199 insertions(+)

然后我们将提交推送到我们的 CouchDB fork

$ git push origin main

接下来，我们回到我们的 GitHub 页面 https://github.com/username/couchdb 并点击“Pull Request”按钮。用一些有用的内容填写描述，然后点击“Send Pull Request”按钮。

我们完成了！

5.1. 文档风格指南

当您更改文档时，您应该确保遵循风格。浏览一些文件，您会发现风格非常简单。如果您不确定您的格式是否符合风格，请问问自己以下问题

Is it needed for correct syntax?

如果答案是 No.，那么它可能不符合风格。

这些指南力求简单，没有矛盾和例外。最好的风格是遵循的风格，因为它似乎是自然的方式。

5.1.1. 指南

指南按优先级降序排列。

  1. 语法

    • 正确的语法始终比风格更重要。这包括配置文件、HTML 响应等。

  2. 编码

    • 所有文件都是 UTF-8。

  3. 行尾

    • 所有行都以 \n 结尾。

    • 没有尾随空格。

  4. 行长

    • 最大行长为 90 个字符。

  5. 链接

    • 所有内部链接都是相对的。

  6. 缩进

    • 4 个空格。

  7. 标题

    • 文件中最高级别的标题用 = 覆盖和下划线。

    • 较低级别的标题用以下字符下划线，按降序排列

      = - ^ *  + # ` : . " ~ _

    • 覆盖和下划线与标题长度匹配。

  8. 空行

    • 文件末尾没有空行。

    • 列表可以每项用一个空行隔开。