Lesson 0025：开源项目维护——从个人仓库到社区项目

前两节你学会了 PR 协作流程（0023）和版本发布体系（0024）。这节课讲最后一层：如何把一个仓库变成一个健康的、可持续的开源项目——或者退一步，把你团队的内部工具仓库管理得像开源项目一样规范。

为什么 DevOps 要学这个？你们团队的 Terraform 模块仓库、Ansible playbook 仓库、内部 CLI 工具——本质上都是「有用户、有贡献者、需要文档和规范」的项目。开源社区的治理实践直接复用。

1. Community Health Files —— 社区健康文件

GitHub 把以下文件称为 Community Health Files。它们放在仓库根目录（或 .github/ 目录），GitHub 会自动识别并展示在仓库首页的 sidebar 里：

2. LICENSE —— 选一个许可证

没有 LICENSE 的公开仓库 = 保留所有权利。别人 fork 你的代码在法律上是侵权的。选许可证是开源的第一步。

3. Issue & PR 模板 —— 结构化沟通

模板让贡献者不用猜你希望他们提供什么信息。

Issue 模板（多模板选择器）

.github/
├── ISSUE_TEMPLATE/
│   ├── config.yml              # 模板选择器的配置
│   ├── bug_report.yml          # Bug 报告模板
│   └── feature_request.yml     # 功能请求模板
└── PULL_REQUEST_TEMPLATE.md    # PR 模板

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: true      # 允许不使用模板（开空白 Issue）
contact_links:
  - name: 💬 Discussions
    url: https://github.com/myorg/myrepo/discussions
    about: 使用问题请去 Discussions，不要开 Issue
  - name: 🔒 安全漏洞
    url: https://github.com/myorg/myrepo/security/advisories
    about: 请通过 Security Advisory 私下报告

# .github/PULL_REQUEST_TEMPLATE.md
## Summary


## Related Issues


## Type of Change
- [ ] Bug fix (PATCH)
- [ ] New feature (MINOR)
- [ ] Breaking change (MAJOR)
- [ ] Documentation only
- [ ] CI/CD or infrastructure

## Checklist
- [ ] 本地测试通过
- [ ] 添加/更新了相关测试
- [ ] 更新了文档（如有需要）

4. The .github Repository —— 组织级默认配置

如果你的 GitHub 组织（如 myorg）有一个叫 .github 的仓库，里面的模板文件会作为所有组织仓库的默认值。

myorg/.github/
├── ISSUE_TEMPLATE/              # 所有仓库共享的 Issue 模板
│   └── bug_report.yml
├── PULL_REQUEST_TEMPLATE.md     # 所有仓库共享的 PR 模板
├── CONTRIBUTING.md              # 所有仓库共享的贡献指南
└── CODE_OF_CONDUCT.md           # 所有仓库共享的行为准则

效果：组织下任何仓库如果没有自己的模板，就自动用 .github 仓库的。这避免了每个仓库都复制粘贴一遍模板。

5. GitHub Discussions & Pages —— 社区基础设施

Discussions（社区论坛）

Settings → General → Features → 勾选 Discussions。它会出现在仓库顶部 tab 栏。

Discussion ≠ Issue。Issue 是「待办任务」，Discussion 是「开放式对话」：

• Q&A：用户问怎么用 → 答案标记为 Accepted Answer
• Ideas：功能建议的早期讨论（成熟后转成 Issue）
• Announcements：发布公告（只有 maintainer 能发）
• General：其他讨论

GitHub Pages（文档站点）

把一个分支（通常 gh-pages）或目录（通常 docs/）发布为静态网站：

# Settings → Pages → Source: Deploy from a branch → gh-pages → / (root)
# 你的网站就在 https://myorg.github.io/myrepo 了

# 或者用 GitHub Actions 自动部署（推荐——支持任意静态站点生成器）
# Settings → Pages → Source: GitHub Actions → 选一个模板（Jekyll/Static HTML）

# .github/workflows/pages.yml
name: Deploy Docs to GitHub Pages

on:
  push:
    branches: [main]
    paths: ['docs/**']            # 只有 docs/ 变更时才触发

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v4
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/
      - uses: actions/deploy-pages@v4
        id: deployment

6. 治理模型 —— 谁说了算？

小型项目一个人定方向（BDFL）。项目长大后需要明确的治理规则：

无论哪种模型，都建议在 GOVERNANCE.md 里写清楚：谁有合并权限、如何成为 maintainer、重大决策的流程、冲突如何解决。

动手练习

目标：给你的一个仓库加上全套社区健康文件，把 Community Profile 刷到 100%。

# 进入你的仓库
cd ~/code/podcast   # 或其他你想完善的仓库

# 1. 添加 LICENSE（如果还没有）
# 去 GitHub Web UI → Add file → Create new file → 输入 LICENSE
# GitHub 会弹出「Choose a license template」→ 选 MIT → Review and submit

# 2. 创建 CONTRIBUTING.md
cat > CONTRIBUTING.md << 'EOF'
# Contributing

## Development Setup
```bash
git clone https://github.com/YOU/podcast.git
cd podcast
npm install
npm run dev
```

## Commit Convention
We use Conventional Commits: `feat:`, `fix:`, `docs:`, etc.

## Pull Request Process
1. Create a feature branch from `main`
2. Make your changes
3. Run `npm test` to ensure nothing breaks
4. Open a PR — CI must pass
5. At least one reviewer must approve

## Code Style
Run `npm run lint` before committing. CI will fail if linting fails.
EOF

# 3. 创建 CODE_OF_CONDUCT.md（用 Contributor Covenant 模板）
curl -o CODE_OF_CONDUCT.md \
  https://raw.githubusercontent.com/EthicalSource/contributor_covenant/main/release/2-1/CODE_OF_CONDUCT.md

# 4. 创建 SECURITY.md
cat > SECURITY.md << 'EOF'
# Security Policy

## Reporting a Vulnerability
**Please do not report security vulnerabilities through public GitHub issues.**

Instead, use GitHub's [Security Advisory](https://github.com/YOU/podcast/security/advisories/new)
or email security@example.com.

We will respond within 48 hours.
EOF

# 5. 创建 .github/ 下的模板
mkdir -p .github/ISSUE_TEMPLATE

cat > .github/PULL_REQUEST_TEMPLATE.md << 'EOF'
## Summary

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation
EOF

# 6. Push + 去 Insights → Community 看评分
git add . && git commit -m "docs: add community health files"
git push

# → 打开你的仓库 → Insights → Community
# → 应该看到大部分项都打勾了 ✅

小测验

推荐资源

• Open Source Guides（opensource.guide） — GitHub 官方出品，涵盖创建、维护、社区建设、法律等全部主题。这节课的很多内容来自这里
• choosealicense.com — GitHub 官方的许可证选择器，用决策树帮你选。也有许可证条款的对比
• Contributor Covenant — 最广泛采用的行为准则模板，复制即用
• The Open Source Way 2.0（中文版） — Red Hat 社区架构师编写的开源社区治理指南。有中文翻译
• GitHub Docs: Building Communities — 官方社区功能文档
• Linux Foundation: Recommended Practices for Hosting OSS on GitHub — 机构视角的 GitHub 项目最佳实践报告

下一步

至此，GitHub 三连课全部完成。你从 Git 操作（0003）→ CI/CD 流水线（0006）→ GitHub 协作（0023）→ 版本发布（0024）→ 开源维护（0025），形成了一条完整的「代码 → 审查 → 合并 → 发布 → 社区」链路。

回到 课程目录，查看你还需要补哪些课。如果你有实际项目需要配 GitHub 工作流，把具体情况发给我——我会给具体建议。