Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
198 lines (128 loc) · 9.09 KB

DEVELOPMENT.md

File metadata and controls

198 lines (128 loc) · 9.09 KB

开发者指南

Tip

本项目采用 GitHub Projects 进行任务管理。 你可以每次选择其中的一个小的 TODO 进行开发；来帮助项目一点一点前进。

本地开发

一般开发需求分为三种：

  • 修改 templates/ 中某个模板

    例：改进ref.bib中的示例，在 main.tex 中补充注释。

  • 修改 bithesis*.dtx 文件

    例：添加新命令，更改 \BITSetup 选项。

  • 修改其他文件。

Tip

运行 justfile（及 Makefile）需要安装 just 和 fd，通常下载可执行文件即可。此外 Windows 开发者若遇到问题，请参考后文。

修改 templates/ 中某个模板

如果改动仅仅涉及某个模板，那么相对简单一些：

  1. 初次开发前，运行 just copy，这会生成 *.cls 等并更新到 templates/ 下。
  2. 编辑模板。
  3. 测试，确保你的改动能够正确编译；并且不会影响到其他效果。

修改 bithesis*.dtx 文件

  1. 编辑 src/bithesis*.dtx。
  2. 运行 just copy，这会生成新的 *.cls 并更新到 templates/ 下。
  3. 更新文档（src/bithesis-doc.tex 以及 src/bithesis*.dtx 中的注释），然后运行 just doc 编译出手册src/bithesis.pdf。
  4. 测试，确保你的改动不会影响到其他功能。

Tip

如果要添加新命令，可以先在 templates/ 中具体实现，再拷贝到 bithesis*.dtx。

Note

文档有两部分。

  • bithesis-doc.tex面向最终使用者，对应手册bithesis.pdf大部分内容。

  • bithesis*.dtx中的注释面向开发者。

    注释中为何有 LaTeX 代码？

    bithesis*.dtx最顶层的注释包含 LaTeX 代码，可输出为手册结尾「实现细节」一节；不过默认不输出，一般也无需单独检查输出结果。

    如需输出，请如下编辑src/bithesis.dtx（\jobname的值是bithesis，\filename的值是bithesis.dtx），然后照常编译手册。

     \begin{document}
-  \DocInput{\jobname-doc.tex}
+  \DocInput{\jobname-doc.tex,\filename,bithesis-thesis.dtx,bithesis-thesis-exports.dtx,bithesis-report.dtx,bithesis-beamer.dtx,bithesis-doc-style.dtx,bithesis-finale.dtx}

    相关功能的文档位于 DocStrip 和 l3doc。

TeX Live 版本

  • 模板：需要保证自 2021 起的 TeX Live 都能使用

  • 文档：只需保证最新版 TeX Live（当前为 2025/2026）能编译

建议开发时使用最新版 TeX Live，通过 pull request 的 CI 保证支持旧版。

建议开发使用最新版 TeX Live 的原因

  • 目前遇到的兼容性问题主要是不兼容新版，而非不兼容旧版。

    最近 LaTeX 团队为了改进 PDF 可访问性，修改很多宏的定义，导致不兼容。

  • 目前文档只能使用最新版 TeX Live 编译。

参考资料

justfile 的进一步介绍

运行just --list可查看所有命令。

$ just --list
Available recipes:
    list                  # List available recipes
    …

    [build]
    copy                  # Copy necessary files to templates/*/ and relevant directories
    doc                   # Build bithesis.pdf
    …

    [dev]
    regression-test *ARGS # Run regression tests (run with `--help` for help)
    …

    [release]
    pkg                   # Build bithesis.zip for submission to CTAN (mainly for CI)
    …

Windows

justfile 主要针对 Linux 和 macOS 开发者；Windows 开发者要确保至少有：

当然，也欢迎你贡献更通用的开发脚本。

辅助命令

我们常常需要实时预览代码编译的效果，而 LaTeX 本身没有提供实时编译的功能，导致我们要来回运行 just copy、latexmk。

其实可以使用类似 rg --files | entr just copy 以及 rg --files | entr latexmk 来达到「代码修改后立即重新编译」的效果。

（这些命令未必适用于 Windows，可能要手动用 watchexec 等替代。）

单元测试和回归测试

运行 just test 将对所有的模板进行编译测试（同样被用于 GitHub Actions）。

运行 just regression-test 进行回归测试，该命令将比较目前已发布的最新版本和本地版本生成的 PDF 的差异。更多使用方式见 just regression-test --help。

使用前请确保已经安装下面这些依赖。

打包

  • just pkg 可以生成上传 CTAN 所需要的 zip 文件。若已有手册而不想重新编译，可 just pkg-only。（同样被用于 GitHub Actions）
  • just grad X.X.X 可以生成用作研究生院官网附件的 zip 文件。

Release 工作流

在一定量改进和新功能添加以后，需要开始着手发布新的版本。

版本号：参考 Semantic Versioning 2.0.0 | Semantic Versioning 。

正常流程

如果一切正常，那么发布已基本自动，只需手动触发。具体流程如下，注意正式版（如 v3.8.9）和测试版（如 v3.8.9-beta.2）略有不同。

  1. （仅限正式版）选择 issue 模板，创建 Release Tracker。

  2. （仅限正式版）提升src/bithesis.dtx版本号到最新。

    该文件有两处不同格式的版本号和日期，可先运行just update-version确定修改位置、格式、日期，再提升版本号。

  3. 前往 New release · BITNP/BIThesis 发布新 release。

    • tag 选择 create new tag，注意必须前缀v。
    • 正式版的 release title 必须形如“v3.8.9 (Public Release)”，因为会用于校内镜像站的文件夹名；测试版的 release title 可自由发挥，但务必注明是测试版。
    • release notes 暂时留空。此时即使填写内容，稍后也会被覆盖。
    • （仅限测试版）勾选 set as a pre-release。
    • （仅限正式版）保持勾选 set as the latest release。Overleaf/TeXPage 按钮会按“latest”创建项目，必须勾选才会更新。

  4. 前往 Release · Workflow runs · BITNP/BIThesis，观察运行过程。

    若是正式版，此步应该会发起 pull request 更新 CHANGELOG 文件并自动合并，还会利用 CTAN API 提交更新。

    无论什么版本，此步应该都会向刚才的 release 上传附件并填写 release notes。

  5. （可选）待上一步运行完毕，可再编辑 release note，在开头简要补充。

    若补充的内容比较重要，应备份到更新说明 | BIThesis。

  6. （仅限正式版）CTAN 团队通常会在一天内向 BITNP 发送确认邮件，有时还需进一步沟通。

尽量在 UTC+8 同一天的9时至23时完成第2至4步，不然日期容易跨天，给未来调试增加困难。

备用流程

如果发布过程出错，那么可能需要手动完成某些步骤，参考下图完整工作流。

Release Workflow

  • Overleaf 链接已利用 overleaf.com/docs API 自动指向最新发布版，不再需要手动更新。