贡献指南

约 1353 字大约 5 分钟

2025-12-20

SecRandom 欢迎任何人向我们的仓库提交代码。您可以帮助我们做很多工作，包括但不限于：

提交补丁来修复bug
添加新功能
优化现有的功能
优化代码的性能
完善文档与翻译
更多......

通过阅读本指南，您将会了解为 SecRandom 贡献代码的各个流程。您还会了解使用 commit 信息进行二进制构建的方式。现在就开始吧！

🚀 快速开始1

在向 SecRandom 项目贡献代码之前，请确保您已完成以下准备工作：

注

除了使用命令行，您还可以使用 GitHub Desktop 或您 IDE 中的内置功能/插件进行操作。

Fork 项目
- 访问 SecRandom GitHub 仓库
- 点击右上角的 "Fork" 按钮创建您自己的仓库副本
克隆仓库

注意

确保在这一步之前，您已经将终端的工作目录切换到您想保存/修改 SecRandom 源代码的地方。

```bash
git clone https://github.com/您的用户名/SecRandom.git
cd SecRandom
```

添加上游仓库

git remote add upstream https://github.com/SECTL/SecRandom.git

安装虚拟环境 (可选)

提示

若您不需要运行代码以测试效果，您可以跳过这个部分。

SecRandom 使用 `uv` 管理虚拟环境。您需要先获取它再执行以下命令。您可以在 [uv官方文档](https://docs.astral.sh/uv/getting-started/) 中获取关于 `uv` 的信息。

```bash
uv venv
uv sync
```

随后您可以这样运行代码（在虚拟环境中）：

```bash
uv run ./main.py
```

📤 提交您的贡献

创建分支
```
git checkout -b feature/功能名称
```
进行修改
- 编写您的代码
- 添加必要的注释（请使用中文）
- 确保遵循项目代码规范

提交更改

git add .
git commit -m "描述您的更改内容"

同步上游更改

git fetch upstream
git rebase upstream/master

推送并创建拉取请求 (Pull request, PR)
```
git push origin feature/您的功能名称
```
- 访问您的 GitHub Fork 仓库
- 点击 "Compare & pull request" (比较/拉取请求) 按钮
- 填写 PR 描述并提交

📋 贡献指南

代码规范

使用中文编写代码注释，别忘记撰写 Docstring
遵循 PEP8 倡导的风格指南，若有意异议可以查看现有的代码
确保导入所有您已使用的类/函数/变量，不要使用 from module import *
验证第三方 UI 组件与其他库中的类/函数/变量是否存在

提示

您可以使用 PyRight， Ruff 等工具检查代码是否有缺陷/代码是否符合规范。

提交 (commit) 信息规范

使用清晰、简洁的提交信息
以 fix, feat 等约定俗成的单词开头
避免过于简单的描述（如："修复bug"）

提示

我们推荐使用约定式提交撰写提交信息。

PR 要求

PR 标题应简洁明了地描述更改内容（若只有一个提交，也可以直接使用这个提交的标题）
提供详细的更改说明，包括：
- 新增/修改/删除的功能
- 新增/修改版本/删除的依赖库和更改 Python 版本
- 其他破坏性更改也请一并告知
确保所有测试通过
确保您修改的代码至少在您的计算机上运行正常
关联相关的 Issue（如有）

最后一步......

当 SecRandom 的维护者审查了您的 PR，确保没有任何问题之后，就会将您的所贡献的代码合并到主分支。

现在我们 恭喜您成为 SecRandom 贡献者的一员！

如果您的 PR 没有通过，也没有关系。请仔细阅读我们的维护者给出的建议并且继续努力，早有一日，您会成为 SecRandom 贡献者的一员。加油😃👍！

📖 Actions 构建工作流

若您需要测试自动构建的二进制程序，您可以阅读以下文字来获取更多信息。

🚀 GitHub Actions 统一构建工作流使用指南

SecRandom 项目使用统一的 GitHub Actions 工作流进行构建和发布，配置文件位于 .github/workflows/build-unified.yml。该工作流支持多种触发方式和配置选项。

通过提交消息触发特定构建

您可以通过在 git commit 消息中包含特定关键词来触发不同的构建行为：

触发打包构建
- 在 commit 消息中包含 打包 关键词
- 例如：git commit -m "新增功能打包"
指定构建平台
- win - Windows 平台
- linux - Linux 平台
- all - 所有平台
- 例如：git commit -m "修复bug 打包 linux"
触发所有平台构建
- 创建符合版本号规范的 tag（格式：v数字.数字.数字.数字）
- 例如：git tag v1.2.3.4 && git push origin v1.2.3.4

构建参数关键词说明

提交消息中可以包含以下关键词来控制构建行为：

关键词	含义	示例
`打包`	通用打包触发	`git commit -m "新增功能打包"`
`win`	Windows 平台	`git commit -m "修复UI 打包 win"`
`linux`	Linux 平台	`git commit -m "优化性能打包 linux"`
`all`	所有平台	`git commit -m "大更新打包 all"`