107 lines
6.1 KiB
Markdown
107 lines
6.1 KiB
Markdown
# GSRL 全局源码发行规范 v1.0
|
||
|
||
**Global Source Release Lock（GSRL）**
|
||
|
||
状态：正式规范 v1.0
|
||
|
||
适用范围：任何拥有独立 Git 仓库的项目。
|
||
|
||
## 1. 定位
|
||
|
||
GSRL 是**规范，不是工具**。它只统一正式发行和接收的基本证据；不指定语言、开发设备、编译器、打包工具、托管平台或 GPT/Codex/RDC 的具体实现。
|
||
|
||
每个独立 Git 仓库自行负责其发行。一个仓库可以发行多个组件；同一仓库在多台电脑上的 Clone 或 Worktree 不构成不同项目。
|
||
|
||
## 2. 触发条件
|
||
|
||
- **必须执行**：独立成果正式发布、交付给其他项目使用、正式接入外部发行成果，以及交付 APK/IPA 或其他正式构建产物。
|
||
- **建议执行**：重要测试或性能基线开始前，检查实际使用的发行版本及产物。
|
||
- **不强制**：普通编码、实验、临时调试及尚未作为正式成果交付的开发构建。
|
||
|
||
开发工作区允许 Dirty；但**包含未归档源码修改的构建，不得声称已完成可从 Git 恢复的 Source Lock**。
|
||
|
||
## 3. 项目发行入口
|
||
|
||
每个项目维护 `release/README.md`，使不熟悉开发目录的使用者可以独立取得正式成果。该入口至少说明：
|
||
|
||
1. 已发行版本系列、当前推荐版本及版本状态；
|
||
2. 每个版本的正式文件获取位置；
|
||
3. 安装、复制、接入或使用步骤；
|
||
4. 必要的依赖、兼容性或环境要求。
|
||
|
||
建议单产品采用 `release/<版本>/`，多组件采用 `release/<组件>/<版本>/`。已有成熟的发布结构可以保留，但必须从 `release/README.md` 明确链接过去。
|
||
|
||
较大产物可存放 Gitea Release 附件、npm/Maven/SwiftPM 仓库或其他受控存储。不要为统一目录强迫大文件进入 Git。
|
||
|
||
## 4. Source Lock 必备内容
|
||
|
||
正式发行版本须提供 `SOURCE_LOCK.json`，至少包含：
|
||
|
||
- 项目及发行单元名称（如有多个组件）、**明确的发行版本**；
|
||
- Git Remote、**完整源码 Commit SHA**、可持久找到该 Commit 的 Tag 或其他保留引用；
|
||
- 每项正式交付文件的名称、位置及 SHA-256；
|
||
- 使用所需的依赖版本/发行身份与说明文档位置（无依赖时明确写空）；
|
||
- 发行状态；未核实的候选版本不得标为正式通过。
|
||
|
||
Source Lock 可以与压缩包同目录放置，也可放在包外作为伴随清单。**不要求包内文件包含自己的哈希**，以免形成循环引用。
|
||
|
||
当 Source Lock 写入同一个源码 Git 仓库时，允许先提交被发行的源码、记录其 Commit，然后在后续提交中加入发行记录；不得以随后发生的 Git HEAD 替代最初被发行的源码 Commit。
|
||
|
||
## 5. 交付方核验
|
||
|
||
正式发行前应逐项确认：
|
||
|
||
1. 本次发行实际使用的代码与 `gitCommit` 相符；相关未提交修改已处理，不能静默带入；
|
||
2. 源码 Commit 已 Push，且能从记录的 Git Remote/保留引用取得；
|
||
3. 交付文件实际存在，SHA-256 为重新计算的结果；
|
||
4. 交付包包含全部必需文件，所需依赖与使用方式已说明；
|
||
5. `release/README.md` 已登记此次版本及获取位置；
|
||
6. 同一发行版本尚未存在另一套已正式发布的文件或源码。
|
||
|
||
检查全部通过才能标记 **PASS / RELEASED**。失败时明确原因，不能用版本号相同代替检查通过。
|
||
|
||
**正式发布不可静默覆盖。** 已发布内容要修正时，使用新版本；允许保留旧版并标注弃用。
|
||
|
||
## 6. 使用方验收
|
||
|
||
其他项目使用一个正式版本时：
|
||
|
||
1. 从该项目 `release/README.md` 找到正式版本和下载入口；
|
||
2. 取得对应交付文件及 `SOURCE_LOCK.json`；
|
||
3. 检查项目、版本、Git 来源、文件清单、兼容性与依赖信息齐全；
|
||
4. **重新计算收到文件的 SHA-256**，确认与 Source Lock 相符；
|
||
5. 校验通过后才能标记为正式接收并接入；不通过则要求交付方补齐或重新发行。
|
||
|
||
使用方不必重做交付方的全部开发测试，但不得凭文件名或人工口头版本说明认定内容正确。必要时保留本次使用的发行版本与 Source Lock 副本或引用，以便以后复查。
|
||
|
||
## 7. 工具及管理职责
|
||
|
||
- **GPT**：识别正式发行/接收任务，组织核验，并依据实际证据判断是否完成；
|
||
- **Codex、RDC 和其他工具**：执行具体 Git、文件、构建、发布、接入操作，报告结果；
|
||
- **Git**：提供源码历史与可恢复身份；
|
||
- **项目维护者**：决定版本、发行方式以及发布授权。
|
||
|
||
可以使用已有的 Git、SHA-256、Gitea Release、包管理器或脚本。不要求安装 GSRL 专用软件，也不建立中央数据库。
|
||
|
||
任何工具均不得为通过 GSRL 而擅自清理未提交文件、强制 Push、覆盖已发布产物，或未经授权提交无关改动。RDC 多步操作继续按已有严格串行规则执行。
|
||
|
||
## 8. 跨设备、跨语言与私有项目
|
||
|
||
同一个 Git 仓库在 Win11、Linux、Mac 或未来设备上使用同一发行规范；路径和本地分支不是永久发行身份。多个 Worktree 要检查**真正用于发布的那个 Worktree**。
|
||
|
||
GSRL 规范仓库可以公开；业务 Git、二进制制品与依赖不要求公开。对私有发行，只需确保**有访问权限的使用者**能够获得源码或对应已归档制品并验证。
|
||
|
||
对于生成型成果（PBF、天气数据、Docker 等），如恢复需要原始数据、配置或外部二进制，发行方必须明确提供其版本、哈希和获取条件。**只有 Git Commit 而缺少必要输入时，不得声称整个生成结果可恢复。**
|
||
|
||
## 9. 完成判定
|
||
|
||
- **PASS**：源码可从指定 Git 来源取得、发行文件可取得且哈希一致、使用说明与必要依赖完整。
|
||
- **INCOMPLETE**：缺少 Git 可恢复依据、文件、哈希、说明或依赖信息，不能作为正式发行。
|
||
- **MISMATCH**：源码、版本或产物校验不一致，禁止将其当作对应的正式发行版本。
|
||
|
||
本规范只负责**源码与交付内容的确定对应**；不默认承诺在任意设备上重新编译出逐字节一致的二进制。
|
||
|
||
---
|
||
|
||
**核心原则：每个独立 Git 项目独立开发、独立发行、独立负责；正式交付有 Source Lock，接收者核实后再使用。**
|