开源维护者治理：项目健康不只靠代码

# .github/labeler.yml — 根据文件变动自动打标签
bug:
  - changed-files:
      - any-glob-to-any-file: ['src/**']
 
documentation:
  - changed-files:
      - any-glob-to-any-file: ['docs/**', '**/*.md']
 
good first issue:
  - changed-files:
      - any-glob-to-any-file: ['examples/**']

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
description: 报告一个缺陷
labels: ["bug", "needs-triage"]
body:
  - type: input
    id: version
    attributes:
      label: 版本
      description: 出问题的版本号
      placeholder: "v2.1.3"
    validations:
      required: true
  - type: textarea
    id: reproduction
    attributes:
      label: 最小复现
      description: 提供一个可运行的最小复现示例，或使用 codesandbox/replit 链接
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: 预期行为
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: 实际行为
    validations:
      required: true
  - type: input
    id: env
    attributes:
      label: 环境信息
      description: Node.js 版本、操作系统、包管理器版本

# .github/workflows/issue-triage.yml
name: Issue Triage
on:
  issues:
    types: [opened]
 
jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      # 根据 issue 内容关键词自动打优先级标签
      - name: Label by priority
        uses: github/issue-labeler@v3
        with:
          configuration-path: .github/issue-labeler.yml
          enable-versioned-regex: 0
 
      # 欢迎首次贡献者
      - name: Welcome first-time contributors
        uses: actions/first-interaction@v1
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          issue-message: >
            感谢你的反馈！维护者会在 3 个工作日内进行初步分类。
            如果你能提供最小复现示例，会大大加速处理速度。
 
      # 自动关闭缺少模板信息的 issue
      - name: Close incomplete issues
        uses: actions/stale@v8
        with:
          only-labels: "needs-info"
          days-before-stale: 7
          days-before-close: 3
          stale-issue-message: "这个 issue 缺少必要信息且 7 天未更新，将自动关闭。请补充信息后重新打开。"

<!-- CONTRIBUTING.md 核心结构 -->
 
## 开始贡献前
 
1. 先找已有的 issue，或在提 PR 前先开 issue 讨论
2. 标记为 `good first issue` 的问题适合首次贡献
3. 标记为 `help wanted` 的问题需要外部帮助
 
## 开发流程
 
1. Fork 并克隆仓库
2. 创建特性分支：`git checkout -b feat/你的功能名`
3. 写代码，确保测试通过：`pnpm test`
4. 提交 PR，填写模板中的所有必填项
 
## PR 审查标准
 
- 所有自动化检查必须通过（lint、test、typecheck）
- 新功能必须附带测试
- commit message 遵循 Conventional Commits
- 维护者会在 5 个工作日内给出首次反馈
 
## 审查时间预期
 
- 文档修改：1-2 个工作日
- 小 bug 修复：3-5 个工作日
- 新功能：可能需要多轮讨论，首次反馈不超过 5 个工作日

# .github/PULL_REQUEST_TEMPLATE.md
## 变更说明
<!-- 简要说明这个 PR 做了什么 -->
 
## 关联 Issue
<!-- 关联的 issue 编号，如 Closes #123 -->
 
## 检查清单
- [ ] 代码通过了所有自动化检查
- [ ] 新功能/修复附带了测试
- [ ] 更新了相关文档
- [ ] commit message 遵循 Conventional Commits
 
## 截图（如果是 UI 变更）

# .github/workflows/pr-check.yml
name: PR Quality Gate
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck
      - run: pnpm lint
      - run: pnpm test --coverage
 
  # 首次贡献者自动打标签并通知维护者
  label-first-time:
    if: github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v5
      - name: Notify maintainers
        run: |
          echo "首次贡献者 PR，需要维护者优先审查"

<!-- SECURITY.md -->
 
## 报告安全漏洞
 
**不要在公开 issue 中报告安全漏洞。**
 
请通过以下方式之一私下报告：
 
1. 使用 GitHub 的 [Private Vulnerability Reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-security-vulnerabilities)
2. 发送邮件到 [email protected]
 
## 响应时间承诺
 
| 严重程度 | CVSS 评分 | 首次响应 | 修复目标 |
|---------|-----------|---------|---------|
| 严重    | 9.0-10.0  | 24 小时 | 7 天    |
| 高危    | 7.0-8.9   | 48 小时 | 14 天   |
| 中危    | 4.0-6.9   | 5 天    | 30 天   |
| 低危    | 0.1-3.9   | 10 天   | 下个大版本 |
 
## 披露政策
 
- 修复后会给予报告者致谢（除非报告者要求匿名）
- 修复发布前不会公开讨论细节
- 安全公告会通过 GitHub Advisory 和 Release Notes 发布

# 在 .github 目录配置安全策略
# repository settings > Code security > Private vulnerability reporting: Enabled
 
# 配合自动化，安全 issue 自动进入专门的处理流程
# .github/workflows/security-triage.yml
name: Security Triage
on:
  workflow_dispatch:
  schedule:
    - cron: '0 9 * * 1'  # 每周一检查
 
jobs:
  check-dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          severity: 'CRITICAL,HIGH'
          format: 'sarif'
          output: 'trivy-results.sarif'
 
      - name: Upload results to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: 'trivy-results.sarif'

# 好的做法：使用 semantic-release 自动化发布
# .releaserc.json
{
  "branches": ["main"],
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "preset": "conventionalcommits"
    }],
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    ["@semantic-release/github", {
      "assets": [
        { "path": "dist/*.tgz", "label": "Distribution" }
      ]
    }]
  ]
}

# 坏的做法：手动改版本号，手写 changelog，容易遗漏
# 维护者需要记住在三个地方改版本号：
# package.json, CHANGELOG.md, git tag
# 手动操作 = 迟早出错
 
# 手动修改（不推荐）
npm version patch  # 只改了 package.json
# 然后手动编辑 CHANGELOG.md
# 然后手动打 git tag
# 然后手动 npm publish
# 任何一步忘记或出错，版本信息就不一致

# 好的做法：用 GitHub Actions 做发布门禁
# .github/workflows/release-gate.yml
name: Release Gate
on:
  pull_request:
    branches: [main]
 
jobs:
  release-readiness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm typecheck
      - run: pnpm test
      - run: pnpm build
      # 检查是否有 breaking change 但版本号没更新
      - name: Check version consistency
        run: |
          COMMITS=$(git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:%s)
          if echo "$COMMITS" | grep -q "BREAKING CHANGE"; then
            echo "::warning::检测到 breaking change，请确认版本号已正确更新"
          fi

<!-- docs/adr/0001-adopt-label-based-triage.md -->
 
# ADR-0001: 采用标签体系进行 Issue 自动分流
 
## 状态
 
已接受 (2026-03-15)
 
## 背景
 
项目 issue 积压严重，维护者每天需要花 30 分钟手动分类 issue。
随着用户增长（月均 30 个新 issue），这个时间成本不可持续。
 
## 决策
 
采用「类型 + 优先级 + 状态」三维标签体系，配合 GitHub Actions 实现自动分流。
不使用更复杂的 ML 分流方案，因为当前 issue 量不需要。
 
## 后果
 
- 正面：维护者 triage 时间从 30 分钟降到 10 分钟
- 正面：新贡献者更容易找到适合参与的问题
- 负面：需要维护标签配置，约每月 15 分钟
- 风险：自动标签偶尔误分类，需要人工兜底

# 坏的做法：关键决策只在微信群或 Slack 私聊里讨论
# 新贡献者完全不知道为什么要这样做
# 三个月后维护者自己也忘了当初为什么选了方案 A 而不是方案 B
 
# 在 issue 或 PR 里做决策（也不够好）
# 决策散落在几十个 issue 的评论里，无法集中查找
# issue 关闭后更难找到决策背景

# 好的做法：在 docs/adr/ 目录集中管理决策记录
# 每个 ADR 包含：状态、背景、决策、后果
# 用编号命名，方便引用（ADR-0001, ADR-0002...）
# 定期 review，过时的 ADR 标记为 Superseded 并链接到新的

# 好的做法：在 README 或 GOVERNANCE.md 中公开维护节奏
# README.md 中添加
---
## 维护说明
 
本项目由社区志愿者维护。
 
- 维护者每周投入约 5-8 小时
- issue 首次响应时间：3-5 个工作日
- PR 首次反馈时间：5-7 个工作日
- 固定维护时段：每周六上午（UTC+8）
- 紧急安全问题除外，会通过 SECURITY.md 中的渠道处理
 
如果你需要更快的响应，可以考虑：
1. 在 Discussion 区提问，社区成员可能更快回复
2. 联系商业支持（如有）
3. 成为活跃贡献者，参与代码审查
---

# 坏的做法：README 上写「7x24 小时支持」
# 或者不写任何时间预期，让用户以为随时能得到响应
# 维护者被半夜的通知惊醒，周末也在回 issue
# 这不是可持续的开源，这是无偿的全职工作