# 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，接收者核实后再使用。**