Issues, Discussions, Labels, Templates, And Triage

GitHub Issues are where a project turns scattered observations into trackable work. A bug report, feature request, refactoring idea, documentation gap, support question, release blocker, or design decision can all start as a conversation, but not every conversation deserves the same workflow. A useful issue has enough context for someone else to decide what should happen next. A weak issue becomes a guessing exercise that wastes maintainer time, frustrates reporters, and hides important work behind vague titles.

Use GitHub's official documentation for current feature behavior. GitHub documents Issues, Discussions, and labels. Those docs describe current product capabilities such as issue metadata, sub-issues, dependencies, Projects integration, discussion categories, and labels. This lesson focuses on the working model a PHP developer needs: when to open an issue, when to use a discussion, how labels and templates reduce ambiguity, and how triage turns incoming noise into maintainable work.

Issues Are Work Containers

An issue should represent work or a decision that can be tracked. It does not need to contain the final answer, but it should contain enough information to move the project forward. For a bug, that means expected behavior, actual behavior, reproduction steps, environment details, and any logs with secrets removed. For a feature request, that means the user need, proposed behavior, constraints, and tradeoffs. For a refactor, that means the pain being addressed and how the team will know the refactor helped.

A good issue title is specific enough to identify the problem in a list. Bug is useless. Checkout rejects valid coupons when cart currency is EUR gives maintainers a working handle. The body should separate facts from guesses. This started after #184 is useful if it is observed from dates or versions. I think the cache is broken is a hypothesis and should be labeled as one.

Issues are also useful for preserving decisions. A pull request shows code that changed; an issue can show why the team agreed to change it. When a future maintainer asks why the PHP API returns 422 for one validation path and 409 for another, a linked issue can preserve the business rule and alternatives that were rejected.

Discussions Are For Open-Ended Conversation

Not every conversation should become an issue. GitHub Discussions are better for open-ended questions, announcements, ideas, community support, and conversations where the outcome is not yet a concrete task. GitHub's documentation describes discussions as a place for project conversations such as asking and answering questions, sharing announcements, and gathering community input. Issues are better when the conversation needs assignment, prioritization, closure, and direct connection to code work.

The distinction matters for maintainers. If every support question becomes an issue, the issue tracker stops showing what work actually needs to be done. If every confirmed bug stays in a discussion, it may never receive ownership or link to a pull request. A common workflow is to start broad questions in Discussions, then open or convert to an issue when the team identifies a specific bug, feature, documentation change, or task.

For PHP projects, discussions can be useful for installation questions, proposed API directions, migration concerns, and community examples. Issues should track confirmed defects, accepted feature work, security-safe public tasks, documentation gaps, and release blockers. Security vulnerabilities normally need a private reporting path, not a public issue or open discussion that gives attackers details before maintainers can respond.

Labels Are Classification, Not Decoration

Labels help classify issues, pull requests, and discussions. A label should answer a question maintainers actually ask: what kind of work is this, how urgent is it, who owns it, what area does it touch, what status is it in, or what help is needed? Labels become noise when every maintainer invents a personal taxonomy or when labels overlap so heavily that nobody knows which one to use.

Useful label families include type labels such as bug, feature, documentation, and refactor; area labels such as API, database, auth, frontend, or deployment; status labels such as needs reproduction, blocked, accepted, or ready for review; and contribution labels such as good first issue or help wanted. Do not use labels as a substitute for explanation. A bug label does not tell anyone how to reproduce the bug. A priority-high label without reasoning creates anxiety rather than clarity.

Labels should be reviewed periodically. If a label has not been used in a year, remove it or document when it should be used. If two labels mean the same thing, merge the policy even if GitHub does not automatically merge history the way the team imagines. If labels drive automation, be extra cautious: a label that triggers deployment, project movement, or notification should be treated as part of the workflow contract.

Templates Improve Input Quality

Issue templates and forms help reporters provide the information maintainers need. They are especially useful for public projects where contributors do not know the team's hidden expectations. A good bug template for a PHP application might ask for PHP version, package version, operating system, database engine, exact command or request, expected behavior, actual behavior, reproduction repository or code sample, and relevant logs with secrets removed.

Templates should not be hostile. A template that demands too much information for every issue can discourage valid reports. A template that says search first but does not help people search is not enough. Use templates to guide, not to scold. If a project has multiple issue types, provide separate templates: bug report, feature request, documentation issue, security-safe report, and support question redirect. For security-sensitive reports, point to the security policy instead of collecting exploit details in public.

Pull request templates serve a different purpose. They ask authors to explain what changed, why it changed, how it was tested, what issue it closes, and what risk reviewers should inspect. A template should improve review quality. If authors fill it with N/A every time, the template is too broad, too vague, or not enforced by team culture.

Triage Turns Input Into Action

Triage is the process of reading incoming issues and deciding what happens next. It is not only closing bad reports. Good triage clarifies the report, adds labels, asks for missing reproduction, links duplicates, routes work to the right maintainer, moves support questions to discussions, identifies security-sensitive content, and closes items that the project will not do.

A healthy triage response is respectful and specific. Cannot reproduce is often too abrupt. Better: I cannot reproduce this on PHP 8.3 with MySQL 8 using the steps above. Please add the exact request body and database driver version. I am labeling this needs reproduction until we can confirm it. That response tells the reporter what is missing and what will happen next.

Triage also protects maintainers from endless backlog growth. Not every request should be accepted. A project can close an issue because it is out of scope, duplicate, unsupported, stale after a clear request for information, or better handled in a discussion. Closing should explain the reason so future readers learn the project boundary. A closed issue with a good explanation is often more valuable than an open issue nobody plans to handle.

Issues, Pull Requests, And Projects

Issues connect to pull requests and Projects. Linking a pull request to an issue helps readers see that work is in progress and can close the issue automatically when the pull request merges if closing keywords are used correctly. Projects can display issues and pull requests by status, priority, iteration, assignee, or custom fields. These tools help only when the underlying issue quality is strong.

A project board filled with vague issues is a vague project board. Before building automation around issues, define what an issue means. Does ready mean ready for implementation or ready for review? Does blocked require a linked blocker? Who owns priority-high? Which issues are allowed to enter a release milestone? The workflow should be understandable without asking the one maintainer who remembers the rules.

For a PHP team, an issue might move from needs reproduction to accepted after a failing test proves the bug, then to in progress when a branch exists, then close when a pull request merges. A feature request might begin as a discussion, become an issue after design agreement, then split into sub-issues for database migration, API behavior, UI changes, and documentation.

Common Failure Modes

The most common issue failure is missing reproduction. A report that says login broken may be true, but it is not actionable. Ask for the path, request data, user role, PHP version, browser or client, expected behavior, actual behavior, and whether the issue appears in production, staging, or local development. If the reporter cannot share private data, ask for a minimal example that preserves the failure shape.

Another failure is using issues as private memory. If a team discusses decisions in chat and leaves only do the thing in the issue, future contributors cannot understand the work. Move durable decisions back to the issue. Link related pull requests, design notes, and follow-up tasks.

A third failure is label inflation. Too many labels make filtering harder. Labels should reduce work, not create a second taxonomy project. If a maintainer cannot explain when to apply a label, it probably needs a clearer description or removal.

Verification And Review

Review issue quality by sampling recent issues. Can a new contributor tell which issues are bugs, accepted work, support questions, and design discussions? Are duplicates linked? Are labels meaningful? Do templates collect the information maintainers need? Are stale issues closed with explanations rather than ignored? Are security-sensitive reports redirected away from public disclosure?

The learner should be able to open actionable issues, choose between issues and discussions, design useful labels, write templates that improve reports, triage respectfully, link issues to pull requests, and keep an issue tracker useful as the project grows.

## Summary

Briefly describe the problem.

## Environment

- Package/application version:
- PHP version:
- Operating system or runtime:
- Database or external service, if relevant:

## Reproduction

Provide the smallest request, command, or code sample that shows the problem. Link a minimal repository if that is easier.

## Expected behavior

What did you expect to happen?

## Actual behavior

What happened instead?

## Logs or screenshots

Paste only the relevant lines. Remove tokens, passwords, session IDs, private URLs, and customer data.

## Additional context

Add anything else that may help maintainers understand the issue.