切换到语义化版本控制

作者 Dan Allen -

经过多年的讨论，我们终于准备好在 Asciidoctor 中切换到语义化版本控制。这次切换将作为每个参与项目下一次重大发布的一部分。

关于语义化版本控制

语义化版本控制（或简称 SemVer）是一个基于简单的 MAJOR.MINOR.PATCH 顺序选择版本号的逻辑系统。

  • MAJOR 版本用于引入不兼容的更改（无论大小）。

  • MINOR 版本用于添加向后兼容的功能。

  • PATCH 版本用于修复 Bug（当然是向后兼容的）。

还可以通过构建元数据为预发布版本留出空间。您可以在 https://semver.org 上了解更多信息。

在我们当前的系统中，补丁发布与主版本和次版本发布无法区分，并且只有一个发布线。经验告诉我们（以艰难的方式），这种情况既不清晰也不可持续。对我们而言，SemVer 旨在实现更好的沟通和发展空间。它是一个基于共享期望和信任的系统。虽然它可能不完美，但 SemVer 应该有助于理解版本号的含义以及何时进行升级。我们不能期望它能防止破坏，但至少您会知道何时可能发生。

独立版本化项目

切换到 SemVer 也意味着 Asciidoctor 项目，即 Asciidoctor、AsciidoctorJ 和 Asciidoctor.js，将独立进行版本控制。生态系统中的其他项目也可能会开始独立版本化（事实上，有些已经开始了）。

AsciidoctorJ 和 Asciidoctor.js 都已经发展到远远超出重新分发 Asciidoctor RubyGem 的阶段。它们拥有自己的 API、扩展模型、自定义功能和平台集成。这值得拥有自己的版本线。独立的版本线还将使用户能够更好地理解每个版本将带来什么。

在与 Robert (AsciidoctorJ 负责人) 和 Guillaume (Asciidoctor.js 负责人) 交流后，这是我们商定的系统：

  • 核心处理器（Asciidoctor、AsciidoctorJ 和 Asciidoctor.js）将从 2.0.0 版本开始迁移到 SemVer。我们计划这三个项目同时进行这次主版本迁移，以最大限度地减少混淆。

  • 如果 Asciidoctor.js 或 AsciidoctorJ 需要对 Asciidoctor 进行更改，它们可以强制 Asciidoctor 发布。这意味着 Asciidoctor 必须随时“准备发布”。补丁或次要版本发布不需要太多讨论，但主版本发布自然需要。

  • 2.0.0 之后，我们不会尝试在三个项目之间统一版本号。Guillaume 提出了一个有力的论点，认为尝试统一版本号会违背 SemVer 的原则，从而导致版本号失去意义。这确实会增加记录 Asciidoctor.js 或 AsciidoctorJ 所提供底层 Asciidoctor 版本的复杂性。然而，AsciidoctorJ 和 Asciidoctor.js 都提供了访问底层 Asciidoctor 版本号的 API。发布号也可以通过 asciidoctor-version 文档属性访问。

我们考虑过在坚持 SemVer 的同时，如何将 Asciidoctor、AsciidoctorJ 和 Asciidoctor.js 锁定到同一版本。然而，我们得出的结论是，这样做只会延续我们看到的版本发布积压的状况。最好让这些项目拥有在适当时机自由发布的自由。有了三个版本号段 (MAJOR.MINOR.PATCH)，我们终于有了足够的空间来实现这些发布！

后续步骤

我们将首先将 Asciidoctor 1.5.8 版本重新打包为 2.0.0，并进行一些小的调整以放弃不再支持的 Ruby 版本。然后 AsciidoctorJ 和 Asciidoctor.js 将会跟进发布它们的 2.0.0 版本。届时，我们将严格按照上述 SemVer 规则进行版本控制。

Asciidoctor.js 1.5.0 发布到 Bower 和 npm！

作者 Guillaume Grossetie 和 Anthonny Quérouil -

发布列车正在运行！Asciidoctor.js 的 1.5.0 版本已发布，现已在 Bower 和 npm 上可用。此版本是使 Asciidoctor.js 在 JavaScript 生态系统中得到广泛应用的重要一步。

Bower and npm 
Asciidoctor in JavaScript.
It was a dream.
Then it was a prototype.
Now, it’s the real deal.
什么是 Asciidoctor.js？

Asciidoctor.js 是在 JavaScript 中使用 Asciidoctor 的官方库。它与 Asciidoctor 共享相同的源代码，并通过 Opal 转译为 JavaScript。使用 Asciidoctor.js，您可以从 JavaScript 转换 AsciiDoc 内容或分析已解析的 AsciiDoc 文档的结构。

升级到 Asciidoctor 1.5.0 时，请参阅迁移指南，了解如何迁移内容。

发布亮点

Asciidoctor.js 就是 Asciidoctor

正如在 Asciidoctor 1.5.0 的发布说明 中提到的，我们努力使 Asciidoctor.js (JavaScript) 和 Asciidoctor core (Ruby) 保持一致。这意味着您可以期望 Asciidoctor.js 能够像原始版本一样解析和转换文档。甚至包含文件也能正常工作！

要使某些功能（如包含文件）正常工作，需要特别注意，因为 JavaScript 是一个与 Ruby 不同的环境，并且 JavaScript 环境之间甚至存在关键差异！

例如，在 Ruby 中读取包含文件只是使用常规的 Ruby IO API 的问题。在浏览器环境中，我们必须使用 XMLHttpRequest（即 Ajax）作为 IO API。如果 Asciidoctor.js 在 Node.js 上运行，我们必须使用 Node IO API fs.readSync() 来使其工作。

请放心，我们正在继续努力消除任何差异，将 Asciidoctor core 的所有出色功能带到 JavaScript。

请继续阅读，了解如何获取 Asciidoctor.js！

使用 Asciidoctor.js 比以往任何时候都更简单

如果您是前端或后端 JavaScript 开发人员，您只需一个命令即可获取最新版本的 Asciidoctor.js。

Bower 包

使用 Bower 安装 Asciidoctor.js
$ bower install asciidoctor.js --save
可选的 --save 标志会自动将包添加到您项目的依赖项中。

安装包后，您可以将以下 script 标签添加到您的 HTML 页面中：

<script src="bower_components/asciidoctor.js/dist/asciidoctor-all.min.js"></script>

asciidoctor-all.min.js 是一个 minified 版本，包含 Asciidoctor core、扩展 API 和 Opal。

这是一个简单的示例，使用 doctype: 'inline' 选项和 showtitle 属性将 AsciiDoc 转换为 HTML5：

var asciidoc = "https://asciidoctor.org.cn[*Asciidoctor*] " +
    "running on https://opalrb.com[_Opal_] " +
    "brings AsciiDoc to the browser!";
var options = Opal.hash2(['doctype', 'attributes'], {doctype: 'inline', attributes: ['showtitle']});
var html = Opal.Asciidoctor.$convert(asciidoc, options);
console.log(html);

请参阅 前端开发指南，了解更多关于 Bower 包的信息。

npm 包

使用 npm 安装 Asciidoctor.js
$ npm install asciidoctor.js --save
可选的 --save 标志会自动将包添加到您项目的依赖项中。

安装包后，首先要做的就是使用 require 加载 asciidoctor.js 模块，然后您就可以开始使用 API 了：

sample.js
var asciidoctor = require('asciidoctor.js')(); (1)
var opal = asciidoctor.Opal; (2)

var processor = null;
var useExtensions = true;

if (useExtensions) {
  processor = asciidoctor.Asciidoctor(true); (3)
}
else {
  processor = asciidoctor.Asciidoctor(); (4)
}

var content = "https://asciidoctor.org.cn[*Asciidoctor*] " +
    "running on https://opalrb.com[_Opal_] " +
    "brings AsciiDoc to Node.js!";
var options = opal.hash2(
    ['doctype', 'attributes'],
    {doctype: 'inline', attributes: ['showtitle']});
var html = processor.$convert(content, options); (5)
console.log(html); (6)
1 加载 Asciidoctor.js 库
2 检索并别名顶级 Opal 命名空间
3 实例化启用扩展的 Asciidoctor
4 实例化不带扩展的 Asciidoctor
5 使用 Asciidoctor.js 将 AsciiDoc 内容转换为 HTML5
6 将 HTML5 输出打印到控制台

将文件另存为 sample.js 并使用 node 命令运行它：

$ node sample.js

您应该会在终端中看到以下输出：

<a href="https://asciidoctor.org.cn"><strong>Asciidoctor</strong></a> running on <a href="https://opalrb.com"><em>Opal</em></a> brings AsciiDoc to Node.js!</p>
要成功使用 Asciidoctor.js，理解如何在 JavaScript 环境中处理 Ruby 对象非常重要。我们建议您浏览 Opal 文档，了解方法名称的映射方式以及它期望的数据类型。

请参阅 后端开发指南，了解更多关于 npm 包的信息。

Asciidoctor.js 在 Node 上如火如荼

Node.js 是 JavaScript 最热门的领域，npm 是管理和分发这种热度的包管理器。我们希望 Asciidoctor.js 成为这个生态系统的一部分。我们也需要它在那里开始构建工具。这就是为什么我们迈出了将 Asciidoctor.js 打包成 npm 包的第一步……实际上是多个！Asciidoctor 现在拥有了一个新的游乐场！

以下是已发布的 npm 包：

asciidoctor.js

Asciidoctor.js 的主要 npm 包

grunt-asciidoctor

一个用于在您的 Grunt 项目中处理 AsciiDoc 源文件的 npm 包

社区已经开始如何使用这些包了：

asciidoc-preview (Atom 编辑器)

Atom 的一个插件，可在您输入时显示文档的预览！

asciidoc-preview (Brackets 编辑器)

Brackets 的一个扩展，可在您输入时显示文档的预览！

grunt-asciidoctor-assemble

由 @tedbergeron 编写的 Grunt 的静态网站生成器。

当然，仍然存在挑战，但我们会解决它们。前往 Asciidoctor.js 项目参与其中。

让我们玩这个新游戏吧！

JVM 上的 Asciidoctor.js

您没看错。浏览器不是唯一能运行 JavaScript 的地方。（我们不是指像 Node.js 这样从浏览器逃出来的 JavaScript 引擎。）我们说的是最支持多语言的运行时，JVM。

Alex Soto 正在努力将 Asciidoctor.js 集成到 AsciidoctorJ 中，这样您就可以在 JVM 上使用它，利用 Nashorn、dynjs 和其他运行在其上的 JavaScript 引擎。 AsciidocFX 项目已经在 Nashorn 上使用 Asciidoctor.js，所以这不仅仅是一个想法！

为了确保 Asciidoctor.js 在 JVM 上顺利运行，仍然需要解决几个挑战，例如让包含文件工作。前往 AsciidoctorJ 项目参与其中，帮助实现这一目标！

致谢

Asciidoctor.js 与 Asciidoctor core 的对齐是一项重大工作。它需要许多人的投入，他们齐心协力应对这一挑战。

我们尤其要感谢 Opal 开发者，特别是 Adam Beynon、meh 和 Elia Schito，他们使得 Asciidoctor.js 得以实现。他们对我们的工作非常积极响应，对 Opal 进行了更改和修复，并提供了宝贵的输入，使我们能够不断前进。

我们还要感谢 Anthonny Quérouil，他构建了一个 Grunt 构建来编译、聚合和压缩 Asciidoctor.js，并帮助将构件发布到 Bower 和 npm。

感谢所有测试 Asciidoctor.js 的人，无论是直接测试还是通过使用工具。您的参与使 Asciidoctor.js 成为真正强大的工具！

如果您有任何问题或反馈，我们鼓励您参与 讨论列表。我们在那里见！

  • 1 / 1