Monte Library 私人知识库 资料库 EN

原始笔记

4.2 Preparing Software For Reuse And Release

4.2 Preparing Software For Reuse And Release

正文

1. 软件复用的五个层级

从低到高依次为：

  1. 可重新运行（Re-runnable）：代码能够再次执行，但不保证结果一致。
  2. 可重复（Repeatable）：多次运行可以得到相同结果。
  3. 可复现（Reproducible）：使用相同软件版本和输入数据，可以重新生成论文中的研究结果。
  4. 可复用（Reusable）：软件容易使用、理解和修改。
  5. 可复制实现（Replicable）：其他人能根据论文描述重新实现算法，并用原始实现消除描述中的歧义。

研究软件至少应达到可复用层级；可复现只是科学可信性的基础，而可复用还要求别人能理解和修改代码。

2. README结构

# 项目名称

一句话描述项目解决什么问题。

## Main Features
- 主要功能 1
- 主要功能 2

## Prerequisites
- 运行时依赖
- 测试依赖

## Installation
安装步骤

## Usage
最基本的使用示例

## Contributing
如何提交 Issue、代码和 Pull Request

## Getting Help
联系方式或问题反馈渠道

## Credits
贡献者和致谢

## Citation
学术引用方式

## License
许可证说明

这部分讲的是：把 GitHub Actions 的测试状态以徽章（badge）形式显示在 README 顶部。

CI徽章

![Continuous Integration build in GitHub Actions](https://github.com/<your_github_username>/python-intermediate-inflammation/actions/workflows/main.yml/badge.svg?branch=main)

会在 README 中显示一个小图标，例如：

build passing

或：

build failing

它表示 GitHub Actions 最近一次 CI 工作流是否执行成功。

2. Markdown 语法结构

图片的 Markdown 语法是：

![替代文字](图片地址)

对应到示例：

![Continuous Integration build in GitHub Actions](徽章地址)

其中：

  • Continuous Integration build in GitHub Actions 是图片无法显示时使用的替代文字；

  • 括号中的 URL 是 GitHub 动态生成的 SVG 徽章。

3. 徽章 URL 的含义

https://github.com/<your_github_username>/
python-intermediate-inflammation/
actions/workflows/main.yml/
badge.svg?branch=main

各部分含义如下：

  • <your_github_username>：你的 GitHub 用户名；

  • python-intermediate-inflammation：仓库名称；

  • actions/workflows/main.yml：CI 工作流配置文件；

  • badge.svg：要求 GitHub 返回一个 SVG 徽章；

  • branch=main：显示 main 分支上的工作流状态。

例如用户名是 monte123：

![CI Status](https://github.com/monte123/python-intermediate-inflammation/actions/workflows/main.yml/badge.svg?branch=main)

添加许可证

在本地仓库添加

安装了 GitHub CLI 时，可以获取官方模板：

gh api licenses/mit --jq .body > LICENSE

打开 LICENSE，把：

Copyright (c) [year] [fullname]

改成：

Copyright (c) 2026 Your Name

然后提交：

git add LICENSE
git commit -m "Add MIT license"
git push

GitHub 的许可证 API 会返回 MIT 模板正文，其中包含 [year] 和 [fullname] 占位符。

README 中注明

在 README.md 末尾加：

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

Python 项目的可选配置

使用现代 pyproject.toml 时，可以在 [project] 下添加：

[project]
license = "MIT"
license-files = ["LICENSE"]

其中 MIT 是 SPDX 标识符，license-files 确保构建发布包时包含许可证文件。

Tag

1. Tag 是什么

Git 中的 tag 是指向某个特定 commit 的固定名称。

例如：

v1.0.0 → commit 2df4bf...

相比难记的 commit 哈希，v1.0.0 更适合人阅读和引用。

分支会随着新提交不断移动，而发布后的 tag 通常应保持不变：

main：A → B → C → D
              ↑
           v1.0.0

这里 main 可以继续移动到 D，但 v1.0.0 仍指向 C。

2. 查看当前标签

git tag

它会列出本地仓库中的所有 tag。

3. 创建带注释的标签

教程使用：

git tag -a v1.0.0 -m "Version 1.0.0"

参数含义：

  • -a：创建 annotated tag，即带注释标签；

  • v1.0.0：标签名称；

  • -m：添加标签说明；

  • 默认标记当前所在 commit，即 HEAD。

带注释标签会额外保存：

  • 标签创建者；

  • 创建时间；

  • 标签说明；

  • 指向的 commit。

4. 查看标签内容

git show v1.0.0

输出通常包含两部分。

第一部分是标签信息：

tag v1.0.0
Tagger: Name <email>
Date: ...

Version 1.0.0

第二部分是标签所指向的 commit：

commit 2df4bf...
Author: ...
Date: ...

    Finalising README.

后面出现的 diff 表示该 commit 相比父提交修改了什么：

  • - 开头：删除的内容；

  • + 开头：新增的内容；

  • @@ ... @@：发生修改的位置。

5. 将 tag 推送到 GitHub

普通的：

git push origin main

通常只推送分支，不会自动推送本地 tag。

需要单独执行：

git push origin v1.0.0

如果想一次推送所有本地标签：

git push origin --tags

但实际项目中，单独推送指定 tag 更安全，避免意外把测试标签全部上传。

7. 语义化版本号

教程推荐 Semantic Versioning：

MAJOR.MINOR.PATCH\text{MAJOR.MINOR.PATCH}

例如：

1.4.2

各部分含义：

  • MAJOR：产生不兼容的 API 修改；

  • MINOR：向后兼容地增加功能；

  • PATCH：向后兼容地修复问题。

例如当前版本为 1.2.3：

修改 新版本
修复一个 bug 1.2.4
添加兼容的新功能 1.3.0
修改 API，旧代码无法使用 2.0.0

预发布版本可以写成：

1.0.0-alpha.1
1.0.0-beta.1
1.0.0-rc.1

其中 rc 表示 release candidate，即候选发布版本。

重新移动tag

git tag -f v1.0.0 main
git push origin v1.0.0 --force

Switch to English