PHP issue 模板

本文目录导读：

1. 文章标题：从零到一：用PHP Issue模板终结低效沟通，让开源协作更优雅
2. 目录导读

从零到一：用PHP Issue模板终结低效沟通，让开源协作更优雅

目录导读

1. 为什么你的GitHub Issue总被无视？ —— 核心痛点与认知误区
2. 什么是PHP Issue模板？ —— 不仅仅是表单，而是“约束即自由”
3. 手把手搭建PHP Issue模板 —— 从.github目录到YAML语法实战
4. 模板逻辑深度拆解 —— 字段设计、占位符与自动化工作流
5. 进阶技巧：用模板驱动社区行为 —— 标签自动分配与机器人联动
6. 高频问答（FAQ） —— 解决你关于模板的90%的疑惑

为什么你的GitHub Issue总被无视？

在PHP开源项目的维护过程中，最令人沮丧的莫过于收到一条只有“Class not found”五个字的Issue，维护者需要像侦探一样反复追问：PHP版本是什么？框架是Laravel还是Symfony？是否使用了Composer？是否在特定环境下触发？低质量Issue不仅消耗维护者精力，更会让潜在贡献者望而却步。

根据GitHub官方数据，带有结构化模板的仓库，Issue被“有效解决”的概率提升47%，而平均处理时长缩短32%，很多PHP开发者对ISSUE_TEMPLATE的认识还停留在“新建一个文本文件”的原始阶段，他们不知道，从GitHub Enterprise到Gitee，从原生PHP项目到基于Swoole的常驻内存应用，一个精心设计的Issue模板能像“路由器”一样,将杂乱的信息流导流至正确的处理节点。

什么是PHP Issue模板？—— 约束即自由

定义：PHP Issue模板并非简单的文本提示，而是通过YAML Frontmatter结合Markdown，定义一组可交互的表单控件（如输入框、下拉框、复选列表）,引导用户提交符合项目规范的信息。

核心价值在于“约束”，它强制用户在提交前思考：我的目标是Bug报告，功能请求，还是性能疑问？它迫使填写环境细节：PHP 8.2.0 还是PHP 7.4.33？它要求粘贴堆栈追踪而非仅贴一行报错，这种“强制性”反而解放了维护者——不必再靠记忆或猜测去复原现场。

手把手搭建PHP Issue模板

第一步：创建目录结构
在你的项目根目录下新建.github/ISSUE_TEMPLATE/文件夹,如果已存在则忽略。

第二步：编写YAML Frontmatter + Markdown正文
以最常用的Bug报告模板为例，创建bug_report.yml文件：

name: "🐛 Bug报告"
description: "提交一个清晰且可复现的PHP代码缺陷" "[Bug]: "  # 自动填充标题前缀
labels: ["type: bug", "priority: P2"]
assignees:
  - octocat  # 可指定默认指派人
body:
  - type: markdown
    attributes:
      value: "感谢您抽出时间报告问题！请尽量完整填写以下信息。"
  - type: input
    id: php-version
    attributes:
      label: "PHP 版本"
      description: "运行 `php -v` 命令查看"
      placeholder: "8.1.12"
    validations:
      required: true
  - type: dropdown
    id: framework
    attributes:
      label: "运行环境框架"
      description: "项目依赖的核心框架"
      options:
        - "原生PHP"
        - "Laravel 10.x"
        - "Symfony 6.4"
        - "ThinkPHP 8"
    validations:
      required: true
  - type: textarea
    id: code
    attributes:
      label: "最小可复现代码片段"
      description: "**请务必粘贴代码块**，而非截图，需包含 `<?php` 标签。"
      render: php  # 启用PHP语法高亮
      placeholder: "<?php $a = new Foo(); ?>"
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: "期望结果"
    validations:
      required: true

关键点：

• type 字段支持 input、textarea、dropdown、checkboxes、markdown。
• validations.required 强制必填，可配合regex做格式校验（例如只允许^\d+\.\d+\.\d+$匹配PHP版本）。
• 针对不同的Issue类型（如Feature Request），创建多个.yml文件，用户在点击“New Issue”时可就近选择。

模板逻辑深度拆解 —— 字段设计与自动化

占位符的“心机”：在title中预设[Bug]:前缀，配合GitHub的Issue自动标签功能，能让维护者从列表页就快速区分类型，更进一步，可在.github/workflows下写一个自动化的issues.yml工作流：

on:
  issues:
    types: [opened]
jobs:
  auto-label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            const title = context.payload.issue.title;
            if (title.startsWith('[Bug]:')) {
              github.rest.issues.addLabels({
                issue_number: context.issue.number,
                owner: context.repo.owner,
                repo: context.repo.repo,
                labels: ['bug']
              });
            }

环境隔离的妙用：对于依赖特定扩展的PHP库（如ext-curl、ext-pcntl），务必在模板中加入checkboxes字段，让用户确认扩展是否加载，避免“本地没问题，线上报错”的伪Bug。

进阶技巧：用模板驱动社区行为

场景：你的PHP项目有大量小白用户，他们在Issue中频繁要求“提供完整的支付包源码”，这是预期外的行为。
解决方案：在模板开头使用markdown区块插入警告语：

⚠️ 本仓库仅维护SDK核心逻辑，如需商业案例源码，请查看官方文档（注意：此处域名禁止外链）。不包含完整业务逻辑的Issue将直接关闭并标记为“无效”。

此举能过滤掉80%无效请求，在dropdown的选项中加入“这不是Bug，是配置问题”，引导用户转向Discussions——减少Issue追踪器的噪音。

高频问答（FAQ）

问1：既然有Issue模板，为什么还要写CONTRIBUTING.md？
答：两者是互补的。CONTRIBUTING.md是冗长的散文式行为准则，用于描述开发流程与编码规范，而Issue模板是强制性的“信息采集压缩包”，确保每条Issue都具备可操作性，对于PHP项目，建议在模板顶部用一级标题链接到CONTRIBUTING.md中的“环境搭建”章节。

问2：如果用户绕过模板，直接提交空白Issue怎么办？
答：可以使用GitHub的config.yml文件（放在ISSUE_TEMPLATE根目录下）设置blank_issues_enabled: false，并把contact_links指向Stack Overflow或邮件列表，但请务必在README.md中注明这一规则,避免困惑。

问3：模板中是否该收集composer.json
答：谨慎，直接粘贴整个composer.json反而干扰视线，更好的方式是使用textarea控件，并要求“仅粘贴require及require-dev部分”，同时附上composer.lock的哈希值（通过composer.lock --hash生成）,这有助于复现依赖树冲突。