BuildKit项目GitHub Issue模板迁移指南

GitHub近期对issue模板系统进行了更新，导致许多开源项目原有的issue模板失效。本文将以BuildKit项目为例，详细介绍如何将传统markdown格式的issue模板迁移到GitHub新支持的YAML格式模板。

模板格式演变

GitHub早期支持在项目根目录下放置.github/issue_template.md文件作为issue模板。但随着平台功能迭代，现在更推荐使用.github/ISSUE_TEMPLATE目录下的YAML格式模板文件。这种新格式提供了更丰富的结构化配置选项。

新旧模板对比

传统markdown模板是简单的文本文件，包含固定的提示内容。而YAML模板则支持：

• 定义多个模板类型（如bug报告、功能请求等）
• 结构化表单字段
• 输入验证规则
• 自动标签分配
• 更友好的用户界面

迁移实践

对于BuildKit项目，可以采用两种迁移方案：

方案一：Markdown兼容格式

在.github/ISSUE_TEMPLATE目录下创建issue.md文件，添加YAML frontmatter：

---
name: 问题报告
about: 报告Bug或建议功能
---

感谢您通过提交issue为BuildKit做贡献！
如果您是首次参与本项目，建议先阅读我们的问题报告指南...

方案二：YAML表单格式

创建issue.yml文件，使用GitHub的表单schema：

name: 问题报告
description: 报告Bug或建议功能
body:
  - type: markdown
    attributes:
      value: |
        感谢您为BuildKit做贡献！
        - 首次参与请先阅读问题报告指南
        - 一般性问题可加入社区Slack频道讨论
        
  - type: textarea
    validations:
      required: true
    attributes:
      label: 问题描述
      description: 详细描述您遇到的问题或建议
      placeholder: 请在此输入...

最佳实践建议

1. 多模板分类：可以为bug报告、功能请求等创建不同模板
2. 必填验证：确保关键信息完整，提高issue质量
3. 引导性描述：帮助用户提供有效信息
4. 自动化配置：结合GitHub Actions实现自动标签分配

注意事项

迁移后需测试模板实际效果，确保：

• 各字段显示正常
• 验证规则生效
• 移动端兼容性
• 多语言支持（如有需要）

通过合理配置issue模板，可以显著提高开源项目的issue质量，减少维护者与贡献者的沟通成本，促进项目健康发展。