2019年4月16日

使用 l3build 上传到 CTAN

最近发布了 l3build 的新版本，它可以使用 curl 自动上传软件包到 CTAN。

这个功能在我们 Wunschliste 上已经有一段时间了，早期的想法是“逆向工程” CTAN 上传页面，就像 Martin Scharrer 的（现在已失效的）ctanupload 工具一样。幸运的是，CTAN 团队添加了一个 API，允许开发人员以文档完善且稳定的方式与 CTAN 上传过程交互。

Gerd Neugebauer 的 ctan-o-mat 工具已经使用此 API 一段时间了，它提供了通过命令行向 CTAN 发送软件包更新的功能，软件包的元数据可以通过配置文件加载。虽然手动通过 CTAN 上传软件包并不是一个繁琐的过程，但能够自动化这个过程还是很不错的。

对于像 l3build 这样的工具，我们更倾向于不依赖标准 TeX 发行版之外的额外工具，并且由于 Windows 现在提供了 curl 实用程序，这使得我们能够直接在 l3build 中构建 CTAN 上传工具。这个工具的机制是由 David Carlisle 编写的；谢谢！

它的使用相对简单。在软件包的 build.lua 文件中，添加如下形式的表格

uploadconfig = {
  pkg          = "vertbars",
  version      = "v1.0c",
  author       = "Peter R Wilson; Will Robertson",
  uploader     = "Will Robertson"
  license      = "lppl1.3c",
  summary      = "Mark vertical rules in margin of text",
  ctanPath     = "/macros/latex/contrib/vertbars",
  repository   = "https://github.com/wspr/herries-press/",
  note         = [[Uploaded automatically by l3build...]]
}

除了上面列出的字段外，还可以有其他字段；此示例并非旨在详尽无遗。完整的可能性列表可以通过 CTAN API 文档 或 l3build 文档获得。

运行 l3build upload

在 build.lua 配置文件到位的情况下，要向 CTAN 提交软件包的新版本，您首先需要运行 l3build ctan 来生成软件包 zip 存档，然后执行类似如下的操作

l3build upload --message "Minor update to fix some erroneous spaces from missing % signs"

对于更长的消息，您可以使用 --file releasenotes-v1.0c.txt，其中列出的文件名包含此更新的发行说明。但是请注意，此处可以包含的内容有相当小的字符限制；您可能希望在单独的 CHANGELOG 文件中维护更长、更详细的更改列表。

在上传过程之前，l3build 将检查是否遗漏了任何必需字段，并在交互式终端中提示它们。特别是，将要求用户提供他们的电子邮件地址以进行验证；一般来说，如果 build.lua 文件要公开存储，则不应将此信息硬编码到该文件中。

除了交互式查询之外，电子邮件字段也可以设置为命令行选项，如下所示

l3build upload --email "my.email@mail.com" ...

或者，您可以在您的个人 texmf/scripts 目录中创建一个包含以下内容的 build-private.lua 文件

uploadconfig = uploadconfig or {}
uploadconfig.uploader = "My Name"
uploadconfig.email    = "my.name@gmail.com"

并使用 require('build-private.lua') 将其读取到您的 build.lua 文件中。

进一步的自动化和未来计划

当前的支持不尝试自动化发布过程的任何方面。例如

  • 您可能希望添加额外的逻辑来检查您的版本控制系统的状态，然后再继续进行标记或上传。
  • 您可能希望让 l3build tag 自动更新软件包版本。
  • 您可能希望从关联的 CHANGELOG 文件自动填充 uploadconfig 中的 announcement 字段。

等等。还值得注意的是，此工具不会自动运行 l3build ctan，因为如果需要重新运行测试套件，该过程可能会非常缓慢。运行适当的 tag，然后 ctan，然后 upload 步骤是一个手动过程。

随着我们对我们和其他人如何使用该工具获得更多经验，我们将研究提供更多关于自动化和/或便利性的功能，特别是与版本控制的集成。

与此同时，我期待着能够更轻松地对软件包进行快速更改并将其发送到 CTAN。