如何规范提交 Issue，帮助快速定位和解决问题

一、Bug Report 模板结构

以 vLLM Ascend 仓库为例，一个标准的 Bug Report 模板包含以下字段：

字段	填写说明
Your current environment	运行环境信息：操作系统、硬件型号（如 Ascend 910B/A2）、驱动版本、CANN 版本、vLLM 版本等
Describe the issue	对问题的详细描述，包括现象、影响范围、复现概率等
Reproduction request	提供可复现问题的最小步骤或命令，例如 curl 请求、Python 脚本等
Observed evidence	实际观察到的错误日志、HTTP 响应截图或其他证据
Related fixes	关联的已有 PR 或 Issue，帮助维护者理解上下文

二、如何提交 Issue（操作步骤）

步骤 1：进入仓库 Issues 页面

打开仓库地址，点击顶部导航栏的 Issues 标签页，可以看到已有的 Issue 列表。

ℹ️ 提示： 点击右上角 New issue 按钮即可开始创建新 Issue。

步骤 2：选择 Issue 类型

点击 New issue 后，系统会提供多种模板供选择：

1. Bug report — 用于报告缺陷和问题
2. Feature request — 用于提出新功能建议
3. Documentation improvement — 用于文档改进建议

步骤 3：填写模板字段

选择模板后，按照模板中的字段逐一填写。以下为必填要点：

1. 标题：简明扼要地描述问题，格式建议为 “[Bug]: 简短描述”
2. 环境信息：列出操作系统、硬件型号、软件版本等
3. 问题描述：清晰描述遇到的问题及期望行为
4. 复现步骤：提供可执行的复现命令或代码片段
5. 报错日志：将日志粘贴到 Markdown 代码块中，或上传附件

三、优秀 Issue 示例

以下是一个高质量的 Bug Issue 示例：

✅ 分析：

• 标题使用了标准格式 “[Bug][兼容性] + 问题描述”
• 环境信息完整列出（硬件、驱动、框架版本）
• 提供了具体的复现命令（curl 请求）
• 关联了相关的已有 Issue 和 PR

四、报错日志的正确贴法

报错日志是维护者排查问题的关键依据，请按以下方式提供：

方式一：Markdown 代码块（推荐）

在 Issue 正文中使用三个反引号包裹日志内容：

```bash curl http://localhost:8000/v1/chat/completions \   -H 'Content-Type: application/json' \\   --data '{"model": "...", "messages": [...]}' ```

方式二：上传附件

当日志内容较长时，可以将日志保存为 .log 或 .txt 文件，直接拖拽到 Issue 编辑框中上传。

方式三：截图补充

对于终端输出、Web 界面报错等场景，可以截取屏幕图片作为补充证据。但请注意：

1. 截图应作为辅助材料，尽量同时提供文本形式的日志
2. 截图前务必检查是否有敏感信息（账号、IP、内部域名等）
3. 必要时使用马赛克或裁剪工具遮挡敏感区域

五、常见错误与避坑指南

❌ 错误做法

❌	错误示例
	标题写 "报错了" 或 "有问题"，没有任何具体信息
	只贴一行错误信息，没有环境和复现步骤
	日志中包含真实账号、邮箱、内部域名
	用口语化描述代替技术细节，如 "就是跑不起来"

✅ 正确做法

✅	正确示例
	标题格式：[Bug]: 模块名 + 具体问题描述
	按模板逐项填写，确保环境、描述、复现步骤完整
	提交前逐项检查
	使用 Markdown 代码块格式化日志，长日志上传附件

六、速查卡片

提交 Issue 前，花 2 分钟过一遍这份清单：

✓  标题使用 [Bug]/[Feature] 前缀 ✓  环境信息完整（OS + 硬件 + 软件版本） ✓  问题描述清晰，包含期望行为和实际行为 ✓  提供可复现的步骤或命令 ✓  报错日志使用 ``` 代码块包裹或上传附件 ✓  关联了相关的 Issue 或 PR（如有）