oss-ready

OSS Ready

将项目转变为专业的开源仓库，添加标准社区文件和 GitHub 模板。

全文使用以下两个术语：

• 增量编辑：对于已存在的文件，只添加缺失的章节或行。绝不替换、改写、翻译或删除用户的内容。
• 占位符：在新建文件中，或在运行时添加到现有文件的行中，匹配 PH='\[(YEAR|COPYRIGHT HOLDER|INSERT [A-Z ]+)\]|TODO|TBD|FIXME' 的内容。

编辑前同步仓库（必需）

前提条件：仓库必须位于命名分支上，并且有一个 origin 远程。请在 Step 0 之前运行 references/repo-sync.md 中的代码块，且只运行一次。遇到第一个失败时停止：

1. 如果 git rev-parse --git-dir 失败（不是 Git 仓库），则停止。
2. 如果 git symbolic-ref --quiet --short HEAD 失败（处于分离 HEAD 状态），则在任何暂存或同步操作前停止。
3. 如果 git remote get-url origin 失败，则停止并询问用户。
4. 如果 git status --porcelain 输出了任意行，则使用 git stash push -u 暂存更改。
5. 运行 git fetch origin && git pull --rebase origin "$branch"。
6. 使用 git stash pop --index 恢复暂存的更改。

如果退出码非零，打印包含 BLOCKED 的最终报告，以及代码块打印的恢复命令。绝不丢弃更改。如果唯一失败是缺少 origin，且用户批准继续，则转到 Step 0，并在 Uncertainty: 下列出 Repo Sync skipped (no origin)。

工作流

在 Step 0 之前，检查 references/edge-cases.md。如果仓库符合其中某种情况，请先按文档中的说明处理。

Step 0：创建功能分支

1. 读取当前分支：git branch --show-current。
2. 读取默认分支：git symbolic-ref --short refs/remotes/origin/HEAD，去掉 origin/ 前缀。如果失败，则使用 main；如果只存在 master，则使用 master。
3. 如果当前分支不是默认分支，且名称中包含 oss，则保留当前分支并转到 Step 1。
4. 如果 git branch -a --format='%(refname:short)' 列出的 feature/ 分支多于 feat/ 分支，则选择前缀 feature/；否则选择 feat/。
5. 如果 <prefix>oss-ready 已存在，则询问用户是要复用该分支，还是提供其他名称。绝不重置现有分支。
6. 运行 git switch -c <prefix>oss-ready，或运行 git switch <name> 以复用分支。如果失败，则停止并标记为 BLOCKED。

Step 1：分析项目

按照 references/file-specs.md → Analysis values 中的说明，记录技术栈、用途、现有文件、许可证、仓库 URL、README 语言、可见性和填充值。用一个问题询问安全与行为规范联系人的信息。如果无法检测到技术栈，则询问应采用哪种技术栈。

Step 2：创建/更新核心文件

根据 Step 1 的值编写 README.md 和 CONTRIBUTING.md。除非已存在许可证，或用户指定其他许可证，否则从 assets/LICENSE-MIT 复制 LICENSE。从 assets/ 复制 CODE_OF_CONDUCT.md（Contributor Covenant 2.0）和 SECURITY.md。将每个占位符替换为 Step 1 中对应的值。章节列表和各文件规则见 references/file-specs.md → Analysis values。

所有用法示例都必须取自仓库代码、脚本或 --help 输出。绝不编造命令或联系人。对于代码中没有来源的章节，应将其省略，并列在 Manual review 下。

Step 3：创建 GitHub 模板

从 assets/.github/ 复制每个缺失的文件：ISSUE_TEMPLATE/bug_report.md、ISSUE_TEMPLATE/feature_request.md、PULL_REQUEST_TEMPLATE.md。保留 .github/ 下所有现有文件和工作流，不作更改。

Step 4：创建文档结构

创建每个缺失的文件。跳过规则和内容见 references/file-specs.md → docs/。

docs/
├── ARCHITECTURE.md    # System design, components
├── DEVELOPMENT.md     # Dev setup, debugging
├── DEPLOYMENT.md      # Production deployment
└── CHANGELOG.md       # Version history (skip when a root CHANGELOG.md exists)

Step 5：更新项目元数据

向根清单文件添加缺失的 license、description 和 repository 字段。绝不覆盖已有值的字段。编辑后解析该文件。各技术栈对应的字段和解析命令见 references/file-specs.md → Project metadata。

步骤 6：确保 .gitignore

将 references/file-specs.md → .gitignore 中适用于该技术栈且缺失的每个模式追加到文件中。使用 grep -qxF '<pattern>' .gitignore 检查其中一个模式。切勿删除任何行。

步骤 7：验证并报告

1. 运行每项验收标准检查。记录 pass、fail 或 not applicable，并说明原因。
2. 按上文 占位符 中的定义设置 PH。对每个创建的文件运行占位符 grep：grep -nE "$PH" <file>。
3. 对每个更新文件中新增的行运行该命令：git diff -U0 -- <file> | grep -E '^\+' | grep -E "$PH"。
4. 运行 git status --porcelain。确认没有任何行以 D 或 D 开头。
5. 打印最终报告。

不要提交或推送。用户会审核并提交该分支。

步骤完成报告

完成步骤 1–7 中的每一步后，按此格式打印报告（示例：references/final-report.md）：

◆ [Step Name] ([step N of 7] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

每项检查应以该步骤所验证的内容命名。步骤 0 不需要报告。如果步骤 0 或 1 失败，请以 BLOCKED 停止。如果步骤 2–6 中任何一步报告 FAIL 或 PARTIAL，请继续；整个运行最终状态为 PARTIAL。步骤 2 启动后，无论如何都要运行步骤 7。

最终报告

最后一份步骤报告之后，在聊天中打印一份最终报告；只有在用户要求时才写入文件。报告按顺序分为四部分：

1. Result: 状态词、仓库和分支，以及 PARTIAL 或 BLOCKED 的原因。
2. Evidence: 创建和更新的文件，以及已运行的每项步骤 7 检查的结果。
3. Uncertainty: 尚存的占位符、未运行的检查及其原因，以及未经测试的行为。
4. Decision: 所需的审批，或 No approval needed.，然后列出用户仍需执行的操作。

按以下优先顺序采用首个匹配的状态规则：

1. BLOCKED：运行在步骤 7 之前停止，且目标仓库中没有创建或更改任何文件。
2. PARTIAL：适用的检查失败或未运行，存在占位符，某一步报告 FAIL 或 PARTIAL，或步骤 7 未能完成。
3. COMPLETE：所有适用的检查均已通过，未发现占位符，且步骤 1–7 均报告 PASS。

只有在 references/final-report.md 列出的原因之一成立，并且符合其中的结果表、示例和读者检查时，才允许标记为 not applicable。任何其他跳过的检查均视为未运行。

验收标准

步骤 7 使用 test -f、grep、git 或目视检查来运行每项检查。

• 存在 LICENSE。新建的 MIT 文件通过 grep -c "MIT License" LICENSE 检查（或检查指定许可证的标题）。现有文件保持不变：git diff --quiet -- LICENSE。
• README.md 至少有 40 行，并包含安装、用法和许可证章节。英文文件中，grep -ciE "^#+ .*(install|usage|license)" README.md 返回值 >= 3；其他语言的标题需目视检查。
• CONTRIBUTING.md 提及问题跟踪器以及分支/PR 工作流：grep -iE "issue|pull request|branch" CONTRIBUTING.md。
• CODE_OF_CONDUCT.md 提及 Contributor Covenant：grep -i "contributor covenant" CODE_OF_CONDUCT.md。
• SECURITY.md 列出漏洞报告联系方式：grep -E "@|https?://" SECURITY.md。
• .github/ISSUE_TEMPLATE/bug_report.md 和 feature_request.md 存在，并包含 YAML 前置内容（name:、about:）。
• .github/PULL_REQUEST_TEMPLATE.md 包含检查清单（- [ ]）。
• 本次运行创建的每个 docs/ 文件都以 # 标题开头：head -1 <file>。
• .gitignore 包含步骤 6 中适用于该技术栈的每个模式。
• 清单文件（package.json、pyproject.toml、Cargo.toml）声明 license、description 和 repository，且仍可解析。
• 占位符 grep 未找到匹配项。
• 没有删除任何先前已提交的文件（步骤 7 第 4 项）。
• 最终报告以 Result: 和一个状态词开头，包含其余三个部分，并通过 references/final-report.md 中的读者检查。

预期输出

对一个部分完成的 TypeScript CLI 执行完整流程后，结果应如下：

Result: COMPLETE — acme/tsgrep on feat/oss-ready
Evidence:
  Created: LICENSE (MIT, 2026 Jane Doe), CONTRIBUTING.md,
           CODE_OF_CONDUCT.md ([email protected]), SECURITY.md ([email protected]),
           .github/ISSUE_TEMPLATE/bug_report.md, feature_request.md,
           .github/PULL_REQUEST_TEMPLATE.md, docs/ (4 files)
  Updated: README.md (+ Quick Start, Usage, License badge),
           package.json (+ license, repository), .gitignore (+ dist/, .env)
  Acceptance criteria: 13/13 pass. Placeholder grep: no matches. No deleted files.
Uncertainty: README commands copied from package.json scripts, not executed.
Decision: No approval needed.
  Remaining action: confirm both contact addresses are monitored.
  Remaining action: review and commit feat/oss-ready.

打印前，请确认列出的每个文件都存在（test -f）。

边缘情况

包含检测和状态影响的完整表格：references/edge-cases.md。简而言之：

• 绝不覆盖现有的非 MIT LICENSE、.github/ 文件，或 CODE_OF_CONDUCT.md、SECURITY.md 中的用户内容。
• 当仓库是私有或内部仓库、没有 origin，或无法检测出技术栈时，先询问。
• 在 monorepo 中仅更新根清单，除非用户指定了某个子包。
• 在 detached HEAD、不处于 git 仓库中，或 stash、sync 或 restore 失败时，停止。绝不丢弃更改。
• 保留 README 的语言和根目录下的 CHANGELOG.md。

资源和参考资料

• assets/：LICENSE-MIT、CODE_OF_CONDUCT.md（Contributor Covenant 2.0）、SECURITY.md，以及 .github/ 问题和 PR 模板
• references/repo-sync.md：Repo Sync 块
• references/file-specs.md：分析值、各文件内容、填充值、元数据、.gitignore
• references/final-report.md：状态规则、结果表格、示例、读者检查项
• references/edge-cases.md：各边缘情况的检测、处理方式和状态