TS-8: Issue Tracking
This technical standard defines how issues (aka. tasks, tickets, or work items) should be tracked.
Objectives
Issue tracking serves several key purposes:
- Source of truth for all changes — Every significant change to the system must be initiated as an issue. The issue tracker becomes the authoritative record of what work needs to be done, who is working on it, and its current state.
- Manage work-in-progress — Provide visibility into current development activities, track progress through workflow states, and ensure nothing falls through the cracks.
- Plan future work — Capture requirements, prioritize tasks, and coordinate development roadmaps across teams.
- Coordinate parallel workstreams — Organize work by codebase areas so that developers can see which issues are related and which might conflict with each other. This is especially important for larger teams where many issues are in progress simultaneously, as it helps prevent merge conflicts and unintended interactions between parallel changes.
- Track changes through their lifecycle — Follow each change from initial reporting or proposal, through design and iteration, testing and integration, to final release. This enables full understanding of the state of the project and all its moving pieces at any time.
- Create an audit trail — Maintain a record of decisions, changes, and the reasoning behind them for future reference and accountability.
Issue tracking systems
Software projects MUST have an issue tracking system (aka. issue tracker).
The issue tracker MUST serve as the authoritative source for all work in the project. Every significant change to the source code or configuration of a software component MUST be initiated with the opening of a new issue in the issue tracker associated with that particular component. Exceptions MAY be made for small "chores" (see TS-9: Version Control), which do not alter the configuration or behavior of the system.
The issue tracker is the central mechanism through which all development and operational work flows. No significant changes should begin without first creating an issue, and all changes should progress through the issue tracking system as they move through the development lifecycle.
Issue identifiers
Each issue MUST have a unique identifier. This is auto-generated by most issue trackers. The identifier can be used to cross-reference issues, and to create references to issues from source code commits, branches, and pull requests.
Relationship to code repositories
Issue trackers SHOULD be directly attached to source code repositories to enable integration and automation.
Integration benefits
Tight integration between issue trackers and version control systems is essential. This integration creates a unified workflow where every code change is linked to the work that initiated it, enabling complete visibility into the state of the project.
Integrating issue trackers with version control systems provides several benefits:
- Unified workflow — Issues initiate all work, and that work flows directly into the version control system. Developers don’t switch between separate tools; the two systems are seamlessly connected.
- Automated state transitions — Issues can be automatically advanced through workflow states (eg. from "Review" to "Testing") based on version control events.
- Automatic closure — Issues can be automatically closed when their associated branches are merged.
- Cross-referencing — Commits, branches, and pull requests can reference issues, creating a bidirectional link between code changes and tracking records.
- Branch lifecycle management — Issue trackers can automatically manage the creation and cleanup of temporary branches.
- Complete lifecycle tracking — Follow each change from the initial issue through design, iteration, testing, integration, and release. This provides a clear audit trail and enables understanding the current state of every piece of work.
- Visibility and traceability — Developers can see exactly which code changes are associated with each issue, and stakeholders can see which issues have been resolved in a given release.
See TS-9: Version Control for further discussion of this relationship.
Repository organization
It is best practice to have one issue tracker per source code repository. However, it is also common to have a single issue tracker that is used to manage changes across multiple source code repositories. The optimum approach will vary depending on how a software system is segmented, and how a project’s development and operations teams are organized.
Cross-repository and cross-team coordination
While issue trackers integrated with version control systems are essential for managing work within and across repositories, they focus on the technical details of implementation. For larger organizations, additional project management tools MAY be useful for higher-level coordination across multiple repositories, teams, and business functions. Such tools can help coordinate dependencies, manage roadmaps, track broader initiatives, and facilitate communication between development and non-technical stakeholders. However, these tools SHOULD NOT be used as the primary mechanism for managing technical work — that role belongs to the integrated issue trackers described above.
Ownership of issue trackers
Issue trackers are a development tool. Their purpose is to help manage the fine-grained nuances of development and operations tasks. For this reason, issue trackers MUST be owned by the development and operations teams. They MUST NOT be controlled by product managers, delivery managers, or other business-oriented roles.
Issue trackers SHOULD NOT be used as broader project management tools. Other tools are more appropriate for planning and prioritizing business requirements, managing product roadmaps, and other such product-oriented concerns.
Product managers, or other representatives of the customer or business, shouldn’t have write access to the issue trackers, except to log bugs and incidents, as any other user would. Tasks to track the implementation of business requirements MUST be added to the issue trackers by the development teams, in collaboration with product managers.
Keeping the issue tracker focused
Issue trackers are designed for ephemeral, short-lived work. The name says it: these systems track current issues — bugs to fix, tasks in progress, incidents under investigation. That ephemerality is a feature, not a limitation. Issues open, get worked, and close. The lifespan of an issue SHOULD be short.
When issue trackers are also used to manage feature requests, requirements specifications, product roadmaps, and long-term backlogs, they quickly become sprawling and expensive to maintain. Teams end up investing disproportionate time grooming and pruning a backlog that grows faster than it shrinks, and signal gets buried in noise.
Better to use purpose-built tools for long-lived artifacts. Requirements specifications and architectural decisions SHOULD be maintained as documents under version control, co-located with the source code they describe. This keeps them portable across issue tracking systems, durable across tool migrations, and reviewable through the same pull request workflow as the code.
For open source projects in particular, feature requests SHOULD be directed to a discussion forum (such as GitHub Discussions) rather than the issue tracker. Forums are better suited to open-ended conversation, community voting, and long-running threads that may or may not ever result in implementation.
Issue types
Each issue MUST be scoped to exactly one small, discrete change – an incremental update to the behavior or configuration of the system under version control, or a small iteration in its internal design (code structure, design patterns, data structures, etc.).
An issue may or may not be small enough to be implemented in a single atomic commit. If not, a temporary branch MAY be used to implement the changes over multiple commits. See TS-9: Version Control.
Each issue MUST clearly define the goal for implementing the change. Having a reason for every change is important for a number of reasons. Not least it helps to keep the scope of changes small and focused.
To emphasize this constraint, each issue SHOULD be assigned a primary type from the following list:
- Bug
- Dev
- Epic
- Errata
- Feature
- Incident
- Maintenance
- Refactoring
- Runtime
- Spike
- Support
- Task
- Vulnerability
In most cases, a single primary type is sufficient. However, in rare cases where an issue legitimately spans multiple types (for example, a runtime optimization that also requires refactoring, or a bug fix that involves security hardening), secondary types MAY be assigned as needed. When multiple types are assigned, ensure the primary type clearly communicates the principal intent of the work.
Some issue tracking systems support the creation of custom issue types, each with unique input fields and templates. It is RECOMMENDED to use such features where available.
Bug
Bugs are defects, errors, or regressions in the expected behavior of a computer program, either in terms of its functionality and behaviors, or its non-functional attributes such as latency or availability. The defects are discovered in production or a production-like environment, or in a production-grade branch.
Bugs are caused by changes in a program’s business logic or its configuration, causing the system to behave in unintended ways, to produce incorrect results, or to otherwise not work as expected.
Every identified bug MUST be logged in the appropriate issue tracker. There SHOULD be one issue per bug, unless multiple bugs are thought likely to have the same root cause, in which case the bug reports MAY be merged into a single issue.
Bug issues SHOULD capture step-by-step instructions to reproduce the error, followed by the expected versus actual outcomes of following those steps.
If relevant, bug issues SHOULD also record the runtime environments in which the errors were discovered. In the context of web applications, the runtime environment is the web browser and the underlying operating system on which the browser is installed. For errors seen in remote services, it may be useful to capture the client devices used to access those services.
Bug tickets should also capture any other relevant materials, such as screenshots or the stderr output, and any other context that may help the development and operations teams to replicate the error.
--- name: Bug about: Report an error or regression in an expected behavior title: "" labels: BUG assignees: "" --- ## Description Write a concise description of the bug. ## Steps to reproduce 1. Go to … 2. Click on … 3. Scroll down to … ## Outcomes - **Expected**: … - **Actual**: … ## Environment Please describe the environments in which you installed the software, or the client devices from which you accessed it. Example: - **OS**: [eg. Windows 10, macOS Sequoia] - **Browser**: [eg. Chrome, Firefox] - **Version**: [eg. 89] ## Additional artifacts Please attach screenshots, stderr output, or other artifacts that may help the project's maintainers to diagnose the issue.
Dev
A dev issue represents a small, incremental change to code or configuration that contributes toward delivering some kind of value, such as a new feature, a refactoring improvement, a bug fix, or any other modification to the system under version control.
Dev issues are the building blocks of larger efforts, capturing individual steps that are too granular to be tracked as features, refactoring, or other higher-level issue types. By definition, dev issues always involve changes to the source code or configuration of a software component.
Most development work of this nature does not need to be formally tracked in the issue tracker. Developers are expected to break down their work into small increments as a matter of course, without requiring a ticket for each step. However, there are situations where it is useful to record a dev issue — for example, to create a reminder to complete a specific piece of work, to make a small task visible to the team, or to capture a discrete unit of work that does not fit neatly into any other issue category.
Dev issues SHOULD be kept small in scope. If a dev issue grows in complexity, consider whether it would be better represented as a feature, refactoring, or other more specific issue type.
--- name: Dev about: Remember to implement a small increment toward value delivery title: "" labels: DEV assignees: "" ---
Epic
Most issue tracking systems support multiple related issues being grouped under a single parent issue, often known as an "epic".
Where multiple issues need to be completed to deliver value to one or more stakeholder groups, the issues SHOULD be grouped under a single epic. Epics serve as organizational containers for related work and provide visibility into larger initiatives.
The scope and granularity of an epic is flexible and depends on the needs of the project. Epics may represent months-long initiatives spanning many issues, or they may group a smaller number of related issues that together form a cohesive unit of work. Teams SHOULD choose the appropriate level of granularity for their context.
Examples of epic scales:
- Large initiative — A multi-month effort (e.g., "Authentication system overhaul")
- Feature area — A collection of related features or improvements (e.g., "Reporting dashboard")
- Small feature — A single user-facing feature broken into multiple implementation tasks (e.g., "Add dark mode support")
- INI-1 Project initialization + INI-2 Implement application framework + INI-3 Configure development environment + INI-4 Setup build process + INI-5 Prepare other development tools + INI-6 Install authentication module
Epics MAY span multiple repositories.
--- name: Epic about: Create a container for a group of related issues title: "" labels: EPIC assignees: "" --- ## Description Write a concise description of this epic.
Errata
Errata issues are used to report mistakes, inaccuracies, or omissions in documentation or other written content. This includes both user-facing documentation (such as user manuals, help pages, and API specifications) and developer-facing documentation (such as inline code comments, architecture decision records, contribution guidelines and READMEs).
Errata issues are distinct from bug reports. Bugs describe incorrect behavior in software; errata describe incorrect information in documentation. If a piece of documentation accurately describes the current behavior of the system but that behavior is itself wrong, the issue is a bug, not an erratum.
Examples of errata include typographical errors, outdated instructions, incorrect code samples, broken links, factual inaccuracies, and misleading or ambiguous wording. Errata issues SHOULD clearly identify the location of the mistake and propose a correction where possible.
--- name: Errata about: Report a mistake in documentation or other content title: "" labels: ERRATA assignees: "" --- ## Mistake Provide details of the mistake. Include the section, page, or URL. ``` Alternatively, copy and paste the erroneous text here. ``` ## Correction Provide details of the correction. ``` Alternatively, suggest how the erroneous text should be changed. ``` ## Sources Provide links to any resources that support the correction.
Behavior
Behavior issues MUST be used to specify new or modified functionality, or to propose that existing operations or behaviors be deprecated, removed or superseded, before such changes are implemented in the software.
The purpose of functional changes is to provide specific capabilities to end users. Changes may be made to external interfaces such as APIs, CLIs, and GUIs, or be scoped to internal processes or algorithms that will have an impact on the user-facing behavior of the system.
If the changes do not have implications for the operations or user-facing functions of the system, it is not a behavior. More likely, the changes being introduced qualify as a bug or improvement work (eg. refactoring or performance optimization).
Features originate from functional requirements (FRs) defined as part of the system requirements specification (SRS). Features SHOULD be specified using a consistent convention for acceptance criteria, such as user stories or use cases, which describe the features from the perspective of the users to whom they provide value. See TS-1: Software Requirements Specification.
--- name: Behavior about: Propose an idea for a new or improved operation or user-facing feature title: "" labels: BEHAVIOR assignees: "" --- ## Description Write a concise description of the feature you're requesting. ## Use cases Explain why this feature would be useful, and how it would be used. Which users would benefit from this feature? ## Benefits List the benefits of this feature, such as improved user experience, increased efficiency, or new capabilities. ## Requirements Outline any specific requirements or criteria for the feature, such as performance considerations, compatibility with existing systems, or any other relevant factors. ## Mock-ups If applicable, include mock-ups or other design artifacts that help to illustrate the proposed changes. ## Alternatives What alternative solutions were considered, if any? ## Additional notes Add any other context, background information, or references that might be helpful in understanding the requirements.
Incident
An incident is an unplanned event that leads to a disruption to the normal operations of a system in production, or a degradation in the system’s performance. Incidents include outages, security breaches, and data loss. Any event that causes a production system to become unavailable, to degrade in its performance, or to otherwise not function as expected, should be recorded as an incident.
Special types of issues MUST be used to track the analysis and resolution of incidents. Ideally, these tasks SHOULD be added to the issue trackers in an automated way.
This issue type is relevant only to software services, and not to software-as-a-product, shrinkwrap software, libraries, or other such software components.
--- name: Incident about: Log an event that unexpectedly disrupted or degraded production services title: "" labels: INCIDENT assignees: "" --- ## Description Write a short description of this incident. Include the date and time of the incident, what happened, and how it was discovered. ## Impact List the systems, applications, or services affected by the incident. Describe how users were impacted, eg. downtime, latency, or data loss. ## Timeline Record when the incident was first detected, how it was discovered (eg. through monitoring tools or user reports), and write a chronology of actions taken to address the incident. ## Analysis Write an analysis of the cause of the incident. Include other contributing factors, besides the root cause. ## Resolution Describe the immediate fixes applied to resolve the incident. ## Communication List the stakeholders who were informed about the incident, including a summary of communications sent to users or internal teams (eg. status dashboard updates, email notifications). ## Mitigation strategies Summarize the actions to be taken following the post-mortem analysis. These should be focused on long-term mitigation strategies to prevent similar incidents from recurring in the future, rather than the immediate fixes applied to resolve this particular incident. ## Additional Information Add any additional information or context that may be relevant. Add links to any relevant documentation or reports related to this incident.
Maintenance
Maintenance work covers any general housekeeping and ad hoc chores that are necessary in the upkeep of a software system.
This category of work includes the routine upgrading of dependencies and changes to the configuration of tools and infrastructure. It also includes improvements made to artifacts such as documentation, test scripts, and requirements specifications – anything except source code and configuration from which executable programs are compiled.
In some cases maintenance work may involve the refactoring of source code and configuration, for example to maintain compatibility with breaking API changes in updated dependencies. If this is the case, this work might be better logged as a refactoring task.
--- name: Maintenance about: Plan a routine housekeeping task title: "" labels: MAINTENANCE assignees: "" --- ## Description Write a concise description of the maintenance work that needs to be done. ## Due What's the deadline for this, if the work needs to be completed by a specific date, eg. before the EOL of a dependency? ## Steps to complete 1. … 2. … 3. … ## Additional notes Add any additional information or context that might help to complete this task.
Quality
The user experience of a software system will be influenced by two things:
- The operations of the software, or what it does – its features.
- How well those operations work – its quality attributes.
While feature issues track the implementation of functional requirements (FRs), a separate type of issue SHOULD be used to track the implementation of non-functional requirements (NFRs), also known as quality requirements (QRs).
Both FRs and NFRs originate in the system requirements specification. FRs describe expected operations and behaviors, while NFRs describe the constraints within which those operations are expected to perform. For example, a functional requirement may be that a system allows users to search for a product by its stock keeping unit (SKU) code, and a non-functional requirement may be that it returns search results in less than one second while supporting up to 10 concurrent searches.
Non-functional attributes of a software system include availability, consistency, latency, security, and compliance requirements. These are external quality attributes of a system, because they impact the user experience. They are also dynamic quality attributes, because they emerge at runtime. By comparison, refactoring tends to focus on the internal, static qualities of a system – qualities that emerge at compile time (or earlier) and that impact the developer experience. The focus of refactoring work is on the needs of the developers and maintainers of the software, whereas the focus of this quality work is on delivering better quality user experiences.
An important difference between functional and non-functional requirements is that NFRs are cross-cutting concerns. Their implementation tends to impact fundamentals such as internal code structure, data structures, and choices of database systems and other infrastructure. Therefore, it can be relatively more expensive to retrofit tighter non-functional requirements into an existing system, than it is to add new features. For this reason, quality constraints SHOULD be specified early in a software project’s lifecycle. Ideally, the up-front system design will be undertaken with an understanding of the non-functional requirements.
Still, quality requirements may emerge over time. For example, as usage of a system grows, it may be necessary to support up to 1,000 concurrent searches, rather than the original 10, while still maintaining the performance target of one second in the request-response cycle. Dedicated issues SHOULD be raised to track the implementation of the necessary changes.
If possible, quality issues should specify metrics against which the system can be benchmarked, such as Mean Time Between Failures (MTBF), Mean Time to Recover/Repair (MTTR), or the application’s crash rate and time to recovery. More indirect measurements such as the open/close rates of incidents, and even user analytics such as shopping cart abandonment rate, may also be useful.
Alternatively, it may be possible to define acceptance criteria in terms of conformance to published standards, such as the 256-bit Advanced Encryption Standard (for encrypting sensitive data in storage), 256-bit SSL/TLS encryption (for data in transit), Web Content Accessibility Guidelines (for usability), and the EU General Data Protection Regulations (for the handling of personally-identifiable data).
--- name: Quality about: Define a constraint on the system's dynamic quality attributes (latency, availability, security, etc.) title: "" labels: QUALITY assignees: "" --- ## Description Write a concise description of the runtime quality improvements that need to be made. ## Current state Describe the current state of the relevant non-functional quality attributes, eg. security, availability, or latency. If possible, provide current performance metrics, eg. response time, throughput, or CPU usage. ## Desired state Define the criteria for considering the improvements to be successful. If possible, specify measurable metrics. ## Proposed solutions Outline the steps or strategies for achieving the desired improvements. Mention any tools, techniques, or methodologies to be used, eg. code profiling, load testing, or security auditing. ## Impact List the components or modules that are expected to need to be changed to achieve the desired improvements. Identify any dependencies that need to be considered, too. ## Risks Identify potential risks. For each risk, describe possible mitigation strategies. ## Validation Describe the testing strategy that will be used to validate the improvements, eg. benchmarking, stress tests, security tests. Establish a baseline for comparison. ## Additional notes Add any other context, background information, or references that might be helpful in understanding the requirements.
Refactoring
Refactoring issues typically cover work to refactor code or configuration with the aim of making the system easier to further develop and maintain, without changing the existing features or performance of the system.
Good architecture and clean code is the foundation on which high quality systems are built. It is necessary to continuously iterate the design of a system to support its evolving requirements.
Refactoring will ultimately benefit the users and owners of the software, for example through faster delivery of features, greater robustness, and higher scalability. But the focus of this category of work is on the needs of the developers and maintainers of the software, rather than the users, the customers, or other stakeholders.
Refactoring SHOULD be undertaken as a normal part of the implementation of features, performance enhancements, and bug fixes. This in-flight refactoring work SHOULD be scoped only to the changes necessary to support the features, performance enhancements, or bug fixes being implemented. The objective is that, after every change, the design of the system should have been iterated in such a way that it looks like it had been designed to support its current featureset from the beginning.
Including refactoring work in the scope of other changes keeps the internal quality consistent over time. It also gives an accurate measure of the true cost of changing the system, which in turn allows more accurate estimation of future changes.
However, it is not always possible to refactor a system as features are added. Sometimes, up-front design changes are required before new features can be supported. Other times, after-the-fact design changes are required once the impact of having added new features is fully understood. In these cases, refactoring SHOULD be undertaken as separate work items. Refactoring issues SHOULD be raised to track this work.
Refactoring issues SHOULD be linked to any related feature issues that are dependent upon the design changes.
Technical debt (aka. design debt) is a popular metaphor for explaining the value of standalone refactoring work to customers. When writing a refactoring ticket, consider the short-term costs and potential risks versus the longer-term benefits to be gained by implementing the proposed changes. Is there any data that can be generated to measure the impact of these changes, such as extensions to test coverage, reductions in the number of lines of code, or improvements to code complexity metrics such as Cyclomatic Complexity or NPath?
--- name: Refactoring about: Suggest how code can be redesigned to improve the developer experience title: "" labels: REFACTORING assignees: "" --- ## Description Write a concise description of the code or module that needs improving. ## Business case What is the business case for investing in this work? ## Current state List the specific files or functions that are targeted for refactoring. Describe the current issues or pain points in this code, eg. complexity, redundancy, or maintainability. ## Goals Describe the desired state of the code after refactoring. Specify what improvements are expected, eg. better maintainability, reduced code duplication, or easier testing. ## Impact List any dependencies or other parts of the codebase that might be affected by the refactoring. ## Risks Assess the potential risks associated with the refactoring, and how they will be mitigated. ## Methodology Outline the steps or strategies for refactoring. This may include breaking down large functions, renaming variables, improving code structure, etc. Mention any tools or techniques that could be used during the refactoring process, such as code analysis tools, automated system tests, or design patterns that could be used as a bridge to the new design. Suggest a testing strategy that will give sufficient confidence that the refactoring does not introduce regressions. Which tests will be the most important to protect from regressions - eg. unit, integration, or system tests? Will test coverage need to be extended beforehand? If so, which tests will need to be added? ## Additional notes Add any other context, background information, or references that might be helpful in understanding the requirements.
Spike
A technical spike is a short, focused period of work used to explore or investigate a technical challenge, uncertainty, or decision point. It’s common in agile software development and helps teams reduce risk by gaining clarity before committing to a full implementation.
A technical spike involves:
- Rapid prototyping or experimentation.
- Researching tools, libraries, or approaches.
- Testing feasibility of a solution or integration.
- Clarifying unknowns in architecture, performance, or compatibility.
- Time-boxed effort, typically a few days to a week.
- Delivering findings, recommendations, or a proof of concept.
Spikes are typically time-boxed (eg. 1–2 days) and don’t aim to produce production-ready code — just insight.
--- name: Spike about: Research and evaluate options to solve a problem title: "" labels: SPIKE assignees: "" --- ## Goal What question are we trying to answer or what do we need to learn? ## Context Why is this spike needed? What problem or decision is blocking us? ## Scope - [ ] Research item 1 - [ ] Research item 2 - [ ] Research item 3 ## Success criteria What does "done" look like for this spike? ## Timebox [X days/hours] ## Deliverable - Written summary of findings - Recommendation with pros/cons - (Optional) Proof of concept or code samples ## Next steps What decisions or tasks will this spike inform?
Support
In open source software projects, support tickets may be raised by end users. Even in proprietary, distributed software-as-a-service systems, support requests may originate from downstream users in the same organization.
The purpose of this type of issue is to provide a mechanism for users to request technical help, such as troubleshooting, configuration assistance, or advice on how to use the software. These types of issues may be generated automatically from helpdesk systems, or they may be raised manually by users or customer support staff.
--- name: Support about: Request technical help title: "" labels: SUPPORT assignees: "" --- ## How can we help? Write your support request here. ## Checklist Please check the boxes `[x]`: - [ ] I have tried to find a solution in the documentation. - [ ] I have searched for similar questions in this issue tracker. - [ ] I have looked elsewhere online, such as StackOverflow.
Task
Task issues are used to track work that does not involve changes to code or configuration. By definition, task issues do not modify the source code, configuration, or other artifacts managed by the repository. They may include operational work, personnel management, permission and role adjustments, organizational activities, or other work that falls outside the scope of the codebase.
Unlike dev issues, which always modify code or configuration, task issues represent work that is necessary for the smooth operation of a project but is fundamentally separate from the technical implementation.
If a task could be more precisely categorized under another issue type, prefer that type instead. Task issues SHOULD be used only when no other issue type is a good fit.
--- name: Task about: Log a miscellaneous unit of work, not easily categorized title: "" labels: TASK assignees: "" ---
Vulnerability
A vulnerability is a weakness in the software, its dependencies, or its infrastructure that could be exploited by an attacker to compromise the confidentiality, integrity, or availability of the system or its data.
Vulnerabilities are distinct from bugs. Bugs are errors that cause a system to behave incorrectly. Vulnerabilities are weaknesses that create a security risk, regardless of whether they cause the system to malfunction under normal conditions.
Examples of vulnerabilities include command injection, broken authentication, insecure direct object references, cross-site scripting (XSS), insecure deserialization, use of components with known CVEs, and misconfigurations in infrastructure or access controls.
Vulnerability issues SHOULD be treated as sensitive information. Where an issue tracking system supports private or confidential issues, vulnerability reports SHOULD be filed privately and disclosed publicly only after a fix has been released.
The severity of a vulnerability SHOULD be assessed using a recognised scoring system, such as the Common Vulnerability Scoring System (CVSS). At minimum, vulnerabilities SHOULD be classified into one of the following severity levels: critical, high, medium, or low.
For vulnerabilities originating in third-party dependencies, the relevant CVE identifier(s) SHOULD be referenced in the issue. Dependency scanning tools may generate vulnerability issues automatically. In such cases, the tool’s output SHOULD be attached or summarised in the issue.
Vulnerability issues SHOULD be resolved with urgency proportional to their severity. Critical and high severity vulnerabilities SHOULD be prioritized above other work.
--- name: Vulnerability about: Report a potential security issue title: "" labels: VULNERABILITY assignees: "" --- > [!CAUTION] > Do not include sensitive details such as working exploits or proof-of-concept attack code in public issues. Use a private security advisory or another confidential channel if available. ## Description Write a concise description of the vulnerability. What is the weakness, and where does it exist in the system? ## Severity Rate the severity: **Critical** / **High** / **Medium** / **Low** Provide a CVSS score if available, or explain the reasoning behind the severity rating. ## Affected components List the files, modules, services, dependencies, or infrastructure components known to be affected. ## Steps to reproduce Describe how the vulnerability can be demonstrated or triggered. Omit or redact sensitive exploitation details where appropriate. 1. … 2. … 3. … ## Impact What could an attacker achieve by exploiting this vulnerability? Consider impacts on confidentiality, integrity, and availability. ## Proposed mitigation Describe the recommended fix or workaround. Include links to patches, updated dependency versions, or relevant security advisories. ## References - CVE identifier(s), if applicable: … - Links to upstream advisories, security bulletins, or relevant standards: …
Decision tree
Use this decision tree to determine the appropriate issue type for your work.
Does this involve changes to code or configuration?
│
├─ NO ─── *TASK*
│
└─ YES
│
├─ Is this fixing a problem?
│ │
│ ├─ YES
│ │ │
│ │ └─ Is it in documentation or other content?
│ │ │
│ │ ├─ YES ─── *ERRATA*
│ │ │
│ │ └─ NO
│ │ │
│ │ └─ Is it a security issue?
│ │ │
│ │ ├─ YES ── *VULNERABILITY*
│ │ └─ NO ─── *BUG*
│ │
│ └─ NO ───┐
│ │
├─ Does this change system behavior
│ from the user's perspective?
│ │
│ ├─ YES ─── *BEHAVIOR*
│ │
│ └─ NO ────┐
│ │
├─ Is this about a runtime quality attribute
│ (latency, availability, security, etc.)?
│ │
│ ├─ YES ─── *QUALITY*
│ │
│ └─ NO ────┐
│ │
├─ Is this about code structure,
│ design patterns, or internal improvements?
│ │
│ ├─ YES ─── *REFACTORING*
│ │
│ └─ NO ────┐
│ │
├─ Is this an investigation, prototype,
│ or feasibility study?
│ │
│ ├─ YES ─── *SPIKE*
│ │
│ └─ NO ────┐
│ │
├─ Is this routine maintenance
│ or operational work?
│ │
│ ├─ YES ─── *MAINTENANCE*
│ │
│ └─ NO ────┐
│ │
├─ Is this a request for technical
│ help from a user?
│ │
│ ├─ YES ─── *SUPPORT*
│ │
│ └─ NO ────┐
│ │
├─ Is this an unexpected event
│ that disrupted production?
│ │
│ ├─ YES ─── *INCIDENT*
│ │
│ └─ NO ────┐
│ │
├─ Is this a small incremental change
│ that contributes to a larger effort?
│ │
│ ├─ YES ─── *DEV*
│ │
│ └─ NO ────┐
│ │
└─ Will multiple increments of work
be required?
│
├─ YES ─── *EPIC*
│
└─ NO ─── *TASK*Scenario | Description | Type |
|---|---|---|
User reports broken login | Login is failing in production | BUG |
Code sample in README returns wrong output | Documentation is incorrect; the software itself is fine | ERRATA |
Implement OAuth integration | New authentication method for users | BEHAVIOR |
Extract database layer into separate module | Improve code organization without changing behavior | REFACTORING |
Response times exceed SLA | API is too slow, needs optimization | QUALITY |
Assess feasibility of migrating to PostgreSQL | Investigation of whether/how to switch databases | SPIKE |
Update dependencies | Routine maintenance without behavior changes | MAINTENANCE |
User asks how to configure single sign-on | Request for help using the software | SUPPORT |
Production database down | Unplanned outage requiring emergency response | INCIDENT |
Add pagination to list endpoint | Small step as part of a larger runtime initiative | DEV |
Add error handling to payment module | Potential security issue discovered in code review | VULNERABILITY |
Add team member to repository access | Permission adjustment outside the codebase | TASK |
Group 5 related features | Multiple issues that together deliver a user feature | EPIC |
Issue lifecycle
Issues MUST change in state as the work progresses through the software development lifecycle. The issue lifecycle provides the primary mechanism for understanding what work is happening, who is responsible for it, and where it stands.
The states MUST be designed to accurately model the real-world development process, which varies from project to project, and even from team to team within a project.
The following lifecycle states are common to most software projects, and are a good starting point:
- Open: The issue has been created, but no work has yet been done on it. Open tickets are said to exist in the "backlog".
- Development: The issue is being actively worked on by the assigned developer.
- Review: The issue has been completed and is awaiting review by a peer or a team lead.
- Testing: The issue has been reviewed and is now passing through quality assurance gates.
- Closed: Work is complete and the issue is considered to be closed.
Relationship to version control
Issue statuses provide visibility into the work-in-progress without necessarily mapping directly to version control states. For example, a ticket in the "development" state may be represented by a branch in the source code repository, but a ticket in the "review" state may not have a corresponding branch. Even issues in development may be continuously integrated into a shared trunk line, and therefore have no associated topic branch.
The important principle is that the issue tracker serves as the single source of truth for understanding the state of all work in the project, regardless of how it’s represented in version control. See TS-9: Version Control for details on how issue tracking and version control interact.
Boards
Issues SHOULD be represented on boards, or other views, that provide a visual indication of the current state of progress of each ticket.
Boards MUST be organized at the team level, not at the individual contributor level. The purpose is to provide shared understanding of everything that the whole team is working on.
Keep it simple. There is a tendency to overload boards with metadata such as target release dates, estimations, time tracking, and so on. Avoid this. Prefer to keep boards simple and lightweight. They are a development tool, not a project management tool.
Assignment
For issues that are in an interim state between open and closed, each issue SHOULD be assigned to at least one team member. These are the members of the development team who are currently responsible for progressing the ticket to the next phase of its lifecycle, and who are the current point of contact for enquiries about the work.
Assignment of a ticket MAY change over time. This makes it easy to see who is working on what at any moment in time — it is simply a matter of filtering tickets in the issue tracking system.
Multiple people may work on a ticket simultaneously (eg. during pair programming).
As a very general rule, individual contributors SHOULD be assigned to just one ticket most of the time. Exceptions may be made when a ticket is repeatedly in a blocked state, in which case assignees can pick up other tickets in the meantime.
The detailed mechanics of how issue assignment maps to ownership of associated temporary branches in version control sit somewhat outside the scope of these technical standards — they depend on the team’s development methodology (eg. solo, pair, or mob programming) and the capabilities of the issue tracking system in use. The basic principle is that issues and their associated branches SHOULD have clear ownership, and the two SHOULD be kept in sync. See also TS-9: Version Control.