# GitHub 问题表单模板 ## 概述 GitHub 问题表单模板是基于 YAML 的表单，它取代了 Markdown 模板，提供了一种结构化的方式来收集问题信息。问题表格提供以下内容，而不是自由格式的文本： * **结构化字段**：文本输入、下拉菜单、复选框、文本区域等 * **验证**：必填/可选字段、正则表达式模式、最小/最大长度 * **自动分配** ：默认受让人和标签 * **元数据**：问题类型和项目分配问题表单作为 YAML 文件（“*.yml”或“*.yaml”）存储在“.github/ISSUE_TEMPLATE/”中。 ## 快速入门：创建您的第一期表格 ### 基本结构每个问题表单都需要三个顶级密钥：名称：错误报告描述：为我们的项目提交错误报告身体： - 类型：降价属性：值：| 感谢您报告此错误！ ### 常见字段类型有关完整规范，请参阅[字段类型参考]()。 **简单示例：** # 简单的文本输入 - 类型：输入身份证号：电子邮件属性：标签：电子邮件占位符：you@example.com 验证：必填：真实 # 多行文本 - 类型：文本区域 id: 描述属性：标签：发生什么事了？占位符：描述问题... 验证：必填：真实 # 下拉菜单 - 类型：下拉菜单 id: 严重程度属性：标签：严重性选项： - 严重 - 高 - 中号 - 低验证：必填：真实 # 复选框 - 类型：复选框 id: 清单属性：标签：清单选项： - 标签：我搜索过现有问题必填：真实 - 标签：我使用的是最新版本 ## 顶级配置这些键出现在 YAML 文件的根目录中：关键|类型 |必填|目的 ---|---|---|--- `名称` |字符串| ✓ |问题选择器中显示的模板名称 `描述` |字符串| ✓ |模板菜单中的简要说明 `身体` |数组 | ✓ |表单字段数组 `标题` |字符串| |默认问题标题（例如“[Bug]：”） `标签` |数组/字符串 | |自动为新问题添加标签 `受让人` |数组/字符串 | |自动分配用户 `项目` |数组/字符串 | |自动添加到项目（需要 ID） `类型` |字符串| |组织级别的问题类型 ### 配置示例名称：错误报告描述：提交错误报告标题：“[错误]：” 标签：[“bug”、“分类”] 受让人： - 维护者用户名项目： - 组织名称/项目编号身体： # 此处的表单字段 **重要提示：** `projects` 字段需要写入权限。如果贡献者缺乏访问权限，请改为启用自动添加工作流程。 ## 按类别划分的字段类型详细参考请参见[字段类型参考]()。 ### 输入类型 1. **markdown** \- 仅显示内容（无用户输入） 2. **输入** \- 单行文本字段 3. **textarea** \- 具有可选代码渲染的多行文本字段 4. **dropdown** \- 单选或多选选项 5. **复选框** \- 具有可选所需验证的多个复选框 6. **隐藏** \- 元数据字段（可选） ### 验证模式请参阅[验证参考]()： * 必填字段验证 * 正则表达式模式 * 最小/最大长度 * 代码渲染选项 ## 模板示例 `assets/templates/` 目录包含现成的模板： * `bug-report.yml` \- 具有严重性和版本跟踪的专业错误报告表 * `feature-request.yml` \- 包含问题/解决方案细分的功能请求模板 * `security-vulnerability.yml` \- 具有负责任的披露指南的安全问题模板为您的存储库复制并自定义这些模板。有关根据您的需求调整模板的示例，请参阅[转换指南]()。 ## 最佳实践 1. **引导验证**：在继续之前使用复选框确认问题搜索 2. **渐进式披露**：从重要领域入手，拓展高级选项 3. **有用的占位符**：在占位符中提供示例 4. **合理的默认值**：预选常用下拉选项 5. **渲染代码块** ：使用 `render: shell` 或 `render: markdown` 来记录日志 6. **保持简短**：最多瞄准 5-8 个字段以减少摩擦 7. **明智地要求**：仅将关键字段设为必填 8. **本地测试**：提交前使用GitHub的表单预览 ## 常见问题 GitHub 提供问题表单验证。请参阅[常见验证错误]()了解： * 语法错误 * 无效的字段类型 * 缺少必需的属性 * 重复的ID * 架构违规 ## 工作流程：从 Markdown 到 YAML 要将现有 Markdown 模板转换为 YAML 形式： 1. 将部分提取到字段条目中 2. 将 Markdown 部分映射到适当的字段类型 3. 添加有用的属性（占位符、描述） 4.添加验证规则 5. 在 GitHub 中测试表单 6.删除旧的Markdown模板有关详细的并排比较和分步转换过程，请参阅[转换指南]()。 ## 如何验证您的表单是否有效创建问题表单模板后，验证其在 GitHub 中是否正常运行： ### 测试步骤 1. **提交并推送**您的`.yml`文件到存储库中的`.github/ISSUE_TEMPLATE/` 2. **导航到 GitHub 存储库中的问题**选项卡 3. **点击“新问题”**按钮 4. **验证模板是否出现在模板选择器菜单中** 5. **选择您的模板**并验证表单是否正确呈现： * 所有字段均显示正确的标签和说明 * 占位符出现在适当的字段中 * 下拉选项显示正确 * 复选框和必填字段已标记 6. **测试现场验证**： * 尝试在不填写必填字段的情况下提交（应该被阻止） * 测试正则表达式验证（如果适用）（例如版本格式） * 验证条件渲染工作 7. **填写并提交**表格以确认问题创建按预期工作 8. **检查生成的问题**以确保响应格式正确 ### 验证失败故障排除如果您的模板未出现或失败： * 检查 [常见验证错误]() 是否存在 YAML 语法问题 * 验证文件位于正确位置：`.github/ISSUE_TEMPLATE/filename.yml` * 确保 YAML frontmatter 具有必需的“name”、“description”和“body”键 * 尝试硬刷新您的浏览器或在私人/隐身窗口中打开 * 检查 GitHub 的问题模板文档以了解最近的更改 ### 成功指标 ✅ 模板出现在问题选择器菜单中 ✅ 表单字段以正确的类型和属性呈现 ✅ 必填字段验证可防止空提交 ✅ 默认值和标签显示正确 ✅ 正则表达式验证按预期工作 ✅ 提交的问题包含格式正确的回复 ** ** ## 资源 ### 参考文件 * [字段类型参考]() \- 带有示例的完整字段类型规范 * [验证模式]() \- 验证规则和正则表达式模式 * [常见验证错误]() \- 故障排除指南 ### 资产 * `templates/` \- 即用型模板文件 * `examples/` \- 转换示例和比较

Github 问题表单模板

包含技能