维护 GitHub 开源项目：Issue 模板与贡献指南

FreeGuideOnline 最新 2026-06-19

name: Bug 报告 about: 创建报告帮助我们改进 title: '[Bug] ' labels: 'bug, needs triage' assignees: ''

描述错误 清晰简洁地描述错误是什么。

复现步骤 按顺序列出复现问题的步骤：

  1. 前往 '...'
  2. 点击 '...'
  3. 滚动至 '...'
  4. 观察到错误

期望行为 清晰简洁地描述你期望发生什么。

截图 如果适用，添加截图以帮助解释问题。

环境信息（请填写以下信息）：

  • 操作系统: [例如 iOS]
  • 浏览器 [例如 chrome, safari]
  • 版本 [例如 22]

附加上下文 在此处添加有关该问题的任何其他上下文。


`---` 包裹的部分是 **YAML 前置元数据**，定义了该模板在新建 Issue 页面里的名称、描述、默认标签和指派人。每个模板文件都必须包含这些元数据，GitHub 才能正确识别。

#### 创建功能请求模板

`.github/ISSUE_TEMPLATE/feature_request.md`：

```markdown
---
name: 功能请求
about: 为这个项目提出一个想法
title: '[Feature] '
labels: 'enhancement'
assignees: ''
---

**您的功能请求是否与某个问题相关？请描述。**
清晰简洁地描述问题所在。例如：当 [...] 时，我总是感到沮丧。

**描述您想要的解决方案**
清晰简洁地描述您想要发生的事情。

**描述您考虑过的替代方案**
清晰简洁地描述您考虑过的任何替代解决方案或功能。

**附加上下文**
在此处添加有关功能请求的任何其他上下文或截图。

高级技巧：链接外部资源与强制选择

如果你的项目已有详细的说明文档、常见问题或社区讨论区，可以通过 config.yml 在 Issue 创建页面添加侧边栏链接，引导用户先查阅这些资源，从而减少无效 Issue。

在 .github/ISSUE_TEMPLATE/config.yml 中配置：

blank_issues_enabled: false
contact_links:
  - name: 项目文档
    url: https://docs.example.com
    about: 请先查阅文档中关于此功能的说明
  - name: 社区讨论
    url: https://github.com/yourname/yourrepo/discussions
    about: 一般性问题请在此讨论

blank_issues_enabled: false 会禁用空白 Issue 的创建，强制贡献者从模板中选择。这对成熟项目非常有效，但对新项目建议先保持为 true，避免门槛过高。

模板设计最佳实践

  • 每个模板只解决一类问题：Bug、Feature、Question、Documentation 等，清晰分离。
  • 使用清单式勾选项：例如“我已搜索过已有 Issue”、“我已阅读贡献指南”，可以过滤掉大量重复问题。
  • 注明环境与版本：对于工具类项目，环境矩阵往往是排错关键。
  • 保持语言友好：用“谢谢你的反馈”、“我们重视你的意见”等词汇开头，降低贡献者的紧张感。

贡献指南：从欢迎到规范

贡献指南文件通常名为 CONTRIBUTING.md，放置在仓库根目录或 .github 文件夹中。当有人新建 Issue 或 Pull Request 时，GitHub 会自动在界面中显示该文件链接，确保贡献者不会错过。

贡献指南的核心结构

一个专业的贡献指南应包含以下模块，可按需调整顺序：

  1. 欢迎词与项目简介：用一句话说明项目目标，表达对所有贡献的感谢。
  2. 行为准则 (Code of Conduct)：链接到 CODE_OF_CONDUCT.md，营造安全包容的环境。
  3. 我能做什么：列出需要帮助的事（写代码、文档、测试、设计、问题分类等）。
  4. 创建 Issue 的规范：引用你的 Issue 模板，说明标签使用方式。
  5. 开发环境搭建：提供本地运行项目所需的步骤、依赖安装、构建命令。
  6. 提交流程与分支策略：说明分支命名约定、commit 信息格式、Pull Request 的步骤。
  7. 代码风格与测试要求：引用项目的 linter 配置、测试运行命令，以及“通过 CI 才能合并”的政策。
  8. 加入社区的渠道：Discord、Slack 或 Discussion 链接。

编写示例：片段参考

# 贡献指南

感谢你考虑为 `project-name` 做出贡献！以下准则希望让参与过程透明、高效。

## 开发者守则
本项目遵循 [贡献者公约](CODE_OF_CONDUCT.md) 行为准则。参与即同意遵守其条款。

## 如何贡献
- **报告错误**：使用 [Bug 报告模板](https://github.com/yourname/yourrepo/issues/new?template=bug_report.md)。
- **建议新功能**：使用 [功能请求模板](https://github.com/yourname/yourrepo/issues/new?template=feature_request.md)。
- **改进文档**：拼写修正、示例补充都非常欢迎，直接 PR 即可。
- **贡献代码**：请遵循下方的开发流程。

## 开发环境设置
1. Fork 仓库并克隆到本地
2. 安装依赖：`npm install`
3. 复制环境变量文件：`cp .env.example .env`
4. 启动开发服务器：`npm run dev`

## Pull Request 流程
1. 确保你从 `main` 分支创建一个功能分支，命名如 `feat/short-description`。
2. 如果更改了 API 或新增功能，请更新相关文档。
3. 确保提交通过所有测试：`npm test`
4. 提交 PR 时使用清晰的标题和描述，关联相关 Issue。
5. 维护者审核后可能会要求修改，请及时响应。

## 代码风格
- 我们使用 Prettier 统一格式，提交前运行 `npm run format`。
- 变量命名采用 `camelCase`，组件使用 `PascalCase`。
- 提交信息遵循 [约定式提交](https://www.conventionalcommits.org/) 规范。

## 社区
有问题？加入我们的 [Discord 服务器](https://discord.gg/example) 或使用 [GitHub Discussions](https://github.com/yourname/yourrepo/discussions)。

让贡献指南更智能的技巧

  • 在指南中嵌入“一键环境”：若项目使用了 Docker 或 Gitpod，可放入 https://gitpod.io/#https://github.com/yourname/yourrepo 链接，让贡献者点击即进入在线开发环境。
  • 贡献者认可：说明你会如何使用 @all-contributors 机器人来识别所有类型的贡献（不仅是代码），提升参与动力。
  • 首次贡献友好标记：在指南中明确说明如何寻找 good first issue 标签，并给出示例链接，降低上手难度。

模块化文件组织参考

一个治理成熟的 .github 目录结构常如下所示：

.github/
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   ├── feature_request.md
│   └── config.yml
├── PULL_REQUEST_TEMPLATE.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
└── workflows/