nhcarrigan/docs
2
0
Fork 0
generated from nhcarrigan/template
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: overhaul labels page

Browse Source
This commit is contained in:
Naomi Carrigan 2024-07-14 13:29:04 -07:00
parent f71c63ff42
commit 3f2120f1da
Signed by: naomi
SSH Key Fingerprint: SHA256:rca1iUI2OhAM6n4FIUaFcZcicmri0jgocqKiTTAfrt8
1 changed files with 417 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

480
docs/community/labels.md
View File

@ -2,91 +2,445 @@
We use very specific labels to help categorise our issues. This page explains what each label means.
## Contribution Labels
## 1. Contribution Labels
These are the most important. These labels indicate who is encouraged to make a pull request to resolve the issue.
| Label | Explanation |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `good first issue` | An issue with this label is intended for contributors who are brand new to the project. These issues should not require prior knowledge of the codebase, and the conversation on the issue will include a detailed description of how to implement a resolution. |
| `help wanted` | These issues are open for contribution from anyone who is interested. The conversation may not include a detailed description, as these issues typically assume you have prior experience with the codebase. |
| `🔒 staff only` | These issues require specific access to the production infrastructure to test properly. These are restricted to project maintainers/staff for that reason. |
### 1.1. `good first issue`
## Aspect Labels
#### 1.1.1. Purpose
Identifies issues suitable for contributors who are new to the project.
#### 1.1.2. Characteristics
Does not require prior knowledge of the codebase. Issues with this label should include a detailed description of the implementation process.
#### 1.1.3. Expectations
Contributors are responsible for ensuring their work complies with the project's licensing terms and contribution guidelines.
### 1.2. `help wanted`
#### 1.2.1. Purpose
Indicates issues open for contribution from any interested party.
#### 1.2.2. Characteristics
Typically assumes prior experience with the codebase. As such, issues may not include a detailed implementation description.
#### 1.2.3. Expectations
Contributors should review and adhere to the project's contribution guidelines and code of conduct before submitting work on these issues.
### 1.3. `🔒 staff only`
#### 1.3.1. Purpose
Designates issues restricted to project maintainers or staff due to specific access requirements.
#### 1.3.2. Characteristics
Requires access to production infrastructure for proper testing and implementation. As such, limited to authorised project maintainers and staff.
#### 1.3.3. Expectations
Staff members working on these issues must adhere to all relevant confidentiality agreements, data protection policies, and internal security protocols.
### 1.4 Disclaimer
Labels are assigned based on the project maintainers' best judgment but may not guarantee the exact level of difficulty or access requirements for every contributor. Contributors should use their discretion and communicate with project maintainers if they have any doubts about their ability to address an issue or comply with any associated legal requirements.
## 2. Aspect Labels
These labels indicate the scope of the work required to resolve the issue.
| Label | Explanation |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `💻 aspect: code` | This is the most common. These issues require work on the project's code-base. |
| `🤖 aspect: dx` | These issues typically require changes to the project's tooling, such as automated tests, development dependencies, etc. |
| `🕹 aspect: interface` | These issues might require code changes, but these are specifically things that require changing the end-user's experience. This might be something like CSS changes, or replacing an image. |
| `📄 aspect: text` | These issues are related to a project's documentation. These don't require code changes, but might require markdown experience as most of our documentation is written in markdown. |
### 2.1. `💻 aspect: code`
## Goal Labels
#### 2.1.1. Purpose
These labels indicate the goal of the issue. Our projects tend to follow a specific modular approach, and these labels help indicate the type of changes you might be making.
Identifies issues requiring changes to the project's codebase.
| Label | Explanation |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `⭐ goal: addition` | These issues add a new feature to the project. Typically, this means you're adding a new code file from scratch, following the project's style. |
| `🛠 goal: fix` | These issues fix a bug in the project. Typically, this means you're editing existing code within existing files. |
| `✨ goal: improvement` | These issues expand upon an existing feature. Typically, this means you're adding code to an existing file, but not necessarily adding new files. |
#### 2.1.2. Characteristics
## Priority Labels
Involves direct modification to the project's source code. Familiarity with the languages and libraries used is expected.
The priority labels indicate the importance we've assigned to a specific issue. The higher the priority, the more of a focus it is for our team.
#### 2.1.3. Expectations
| Label | Explanation |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `🟥 priority: critical` | These issues are typically show-stoppers. This label is reserved for issues which need immediate attention because the project is **unusable** until they are resolved. |
| `🟧 priority: high` | This label applies to issues that aren't preventing the project from being _functional_, but are preventing further development until they're resolved. |
| `🟨 priority: medium` | Medium priority issues are things that we want resolved as soon as possible, but they aren't preventing other development from occurring. |
| `🟩 priority: low` | This is probably the most common label. This is for issues that we'd like resolved, but aren't considered as things we want done ASAP. |
| `🟪 priority: none` | This label indicates an issue that would be nice to have resolved, but isn't essential enough to dedicate maintainer time to fixing. |
Contributors must ensure their code changes comply with the project's coding standards, license terms, and any applicable software patents or copyrights.
## Status Labels
### 2.2. `🤖 aspect: dx`
Status labels allow you to see where a ticket is at in the lifecycle of the project.
#### 2.2.1. Purpose
| Label | Explanation |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `🚦 status: awaiting triage` | This is the most common status label. This label is automatically applied to new issues, and indicates that the maintainer team has not reviewed and responded to the issue. You are still welcome to share your thoughts, but these issues have not received any maintainer attention. |
| `🚧 status: blocked` | This label is applied to issues that might have a planned resolution, but that resolution depends on a separate issue being resolved. These aren't ready for work **yet**, but will be soon. |
| `⛔️ status: discarded` | This label applies to an issue that we don't intend to resolve. Typically, this is on feature requests that aren't in line with the project's goals. |
| `🙅 status: discontinued` | We rarely use this label, but this applies to feature request issues on projects that are solely in maintenance mode - that is, projects we aren't adding new features to but are still supporting and providing bug fixes for. |
| `🏷 status: label work required` | This applies to an issue that might have some discussion on it, but hasn't been appropriately labelled and categorised. |
| `🏁 status: ready for dev` | These issues are ready for contribution. If a contributor is assigned, they have indicated interest in working on the issue and we encourage you to collaborate. This pairs with the Contribution Labels listed above. |
| `🧹 status: ticket work required` | This label indicates that the issue does not have enough information for proper triage. Typically, this pairs with the Conversation Labels listed below. |
Indicates issues related to improving the project's tooling and development workflow.
## Conversation Labels
#### 2.2.2. Characteristics
These labels indicate that the issue has received initial maintainer attention, but is waiting on more information from the author or the maintainer team.
May include changes to automated tests, development dependencies, build processes, etc. Understanding of the development workflows is expected.
| Label | Explanation |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| `💬 talk: discussion` | This issue is being actively discussed, but has not been accepted as something we intend to resolve. |
| `❓ talk: question` | These issues are waiting on additional information from the author in order to triage properly. |
#### 2.2.3. Expectations
## Special Labels
Changes to tooling or dependencies must be compatible with the project's overall licensing strategy and not introduce conflicts with existing terms.
These labels are specifically used for unique events.
### 2.3. `🕹 aspect: interface`
| Label | Explanation |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Hacktoberfest` | This issue is indicated as a valid contribution opportunity for Hacktoberfest. |
| `hacktoberfest-accepted` | This is used to label pull requests which are valid Hacktoberfest contributions, but might not be merged in time for the event. |
| `invalid` | This label is specifically used on pull requests which were made with the goal of spamming Hacktoberfest contributions, and were not made in good faith. |
#### 2.3.1. Purpose
## Pull Request Labels
Designates issues that affect the end-user's experience with the project.
We have automation that applies specific labels to our pull requests.
#### 2.3.2. Characteristics
| Label | Explanation |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `✅ pull: accepted` | This pull request has been merged into the code base. |
| `⚠️ pull: merge conflict` | This pull request has conflicts with the target branch. Those need to be resolved before we can review it. |
| `🔍 pull: ready for review` | This pull request is not in draft mode and is waiting for maintainer review. |
| `❌ pull: rejected` | This pull request was not accepted by maintainers and was closed. |
| `⏫ pull: requires update` | This pull request has had changes requested by the maintainer team. |
| `⚒️ pull: work in progress` | This pull request is in draft mode and is not ready for review. |
May require changes in the code, particularly in front-end components. Can include visual modifications like CSS changes or image updates. Understanding of the end-user experience expected.
#### 2.3.3. Expectations
Contributors must ensure they have the necessary rights to any visual assets introduced or modified. Changes should comply with accessibility standards and regulations where applicable.
### 2.4. `📄 aspect: text`
#### 2.4.1. Purpose
Identifies issues related to the project's documentation.
#### 2.4.2. Characteristics
Typically does not require code changes. Proficiency in technical writing is a must.
#### 2.4.3. Expectations
Contributors must ensure the accuracy of the information provided in documentation updates. Documentation changes should adhere to any applicable style guides and licensing terms.
### 2.5 Disclaimer
Aspect labels are assigned based on the primary focus of the issue but may not encompass all potential areas of impact. Contributors are encouraged to consider potential cross-aspect effects of their work and discuss these with project maintainers when in doubt. The project maintainers reserve the right to reassign aspect labels or request additional changes if the submitted work does not align with the intended scope of the issue.
## 3. Goal Labels
These labels indicate the primary objective of the issue, reflecting our project's modular approach. They help contributors understand the nature and scope of the changes they'll be making.
### 3.1. `⭐ goal: addition`
#### 3.1.1. Purpose
Identifies issues that involve adding a new feature to the project.
#### 3.1.2. Characteristics
Typically involves creating new code files. Understanding of how different modules in the project integrate with each other is expected.
#### 3.1.3. Expectations
Contributors must ensure that new features do not infringe on existing patents or copyrights. New code should be compatible with the project's existing license. If introducing third-party libraries or dependencies, their licenses must be compatible with the project's license.
### 3.2. `🛠 goal: fix`
#### 3.2.1. Purpose
Designates issues aimed at fixing bugs in the project.
#### 3.2.2. Characteristics
Typically involves editing code within existing files. Scope should be kept to the specific bug - separate contributions should be made for unrelated bugs.
#### 3.2.3. Expectations
Bug fixes should not introduce new legal issues or licensing conflicts. Contributors should document the nature of the bug and the fix for future reference and potential legal compliance (e.g., security vulnerabilities).
### 3.3. `✨ goal: improvement`
#### 3.3.1. Purpose
Indicates issues that expand upon or enhance existing features.
#### 3.3.2. Characteristics
Usually involves adding code to existing files. Scope should be kept to the existing feature.
#### 3.3.3. Expectations
Improvements should maintain compatibility with existing licenses and legal obligations. If the improvement significantly changes the functionality, consider if additional legal reviews or updates to user agreements are necessary.
### 3.4. Disclaimer
While goal labels provide guidance on the nature of the task, the actual work required may vary or expand beyond the initial scope. Contributors are encouraged to communicate with project maintainers if they believe a different approach or additional changes are necessary to achieve the goal. The project maintainers reserve the right to request modifications or additional work to ensure that contributions align with the project's goals, standards, and legal requirements.
## 4. Priority Labels
Priority labels indicate the importance assigned to specific issues by the project maintainers. These labels help guide resource allocation and set expectations for resolution timeframes.
### 4.1. `🟥 priority: critical`
#### 4.1.1. Purpose
Identifies issues requiring immediate attention due to their severe impact on project usability.
#### 4.1.2. Characteristics
Require urgent resolution to restore project functionality. Experience with the project is a must, to avoid delays from long review processes.
#### 4.1.3. Expectations
May involve security vulnerabilities or critical bugs that could lead to legal liabilities if not addressed promptly. Resolution of these issues may need to be reported to relevant stakeholders or authorities in certain cases (e.g., data protection regulators for security breaches).
### 4.2. `🟧 priority: high`
#### 4.2.1. Purpose
Designates important issues that, while not preventing basic functionality, are impeding further development.
#### 4.2.2. Characteristics
Not critical for current project operation but blocking future progress. Require prompt attention to unblock development efforts.
#### 4.2.3. Expectations
May involve compliance deadlines or contractual obligations that need to be met. Could impact project timelines, potentially affecting agreements with stakeholders or clients.
### 4.3. `🟨 priority: medium`
#### 4.3.1. Purpose
Indicates issues that need resolution as soon as possible but are not blocking other development.
#### 4.3.2. Characteristics
Important for project improvement but not critical for current functionality. Should be addressed in a timely manner but with less urgency than high-priority issues.
#### 4.3.3. Expectations
May involve improvements to user experience or accessibility, which could have legal implications if neglected long-term. Could relate to optimizations that affect performance guarantees or service level agreements.
### 4.4. `🟩 priority: low`
#### 4.4.1. Purpose
Represents issues that should be resolved but are not considered urgent.
#### 4.4.2. Characteristics
Desirable improvements or minor issues that don't significantly impact project functionality.
#### 4.4.3. Expectations
While not urgent, neglecting these issues over time could lead to technical debt or gradual degradation of project quality, potentially affecting long-term compliance or user satisfaction.
### 4.5. `🟪 priority: none`
#### 4.5.1. Purpose
Identifies "nice-to-have" issues that are not essential for project functionality or immediate development goals.
#### 4.5.2. Characteristics
Not critical enough to dedicate maintainer time for resolution. Often left for community contributors or future consideration.
#### 4.5.3. Expectations
While not prioritized, maintainers should periodically review these issues to ensure they haven't become more significant over time, potentially accruing legal or compliance risks.
### 4.6 Disclaimer
Priority labels reflect the project maintainers' current assessment and may be subject to change. The presence of a lower-priority label does not diminish the importance of the issue or the value of contributions addressing it. Contributors should communicate with maintainers if they believe an issue's priority should be reassessed due to new information or changing circumstances.
## 5. Status Labels
Status labels indicate the current stage of an issue in the project lifecycle. These labels help manage workflow and set expectations for contributors and users.
### 5.1. `🚦 status: awaiting triage`
#### 5.1.1. Purpose
Identifies newly created issues that have not yet been reviewed by the maintainer team.
#### 5.1.2. Characteristics
Should be applied to issues when they are opened.
#### 5.1.3. Expectations
Contributors should be aware that engaging with these issues is at their own discretion, as the project team has not yet evaluated them. Maintainers should establish a reasonable timeframe for initial triage to manage expectations and potential liability.
### 5.2. `🚧 status: blocked`
#### 5.2.1. Purpose
Indicates issues with a planned resolution that depend on the completion of another issue.
#### 5.2.2. Characteristics
Not yet ready for work but expected to be addressed in the future.
#### 5.2.3. Expectations
Maintainers should clearly document dependencies to avoid potential conflicts or misunderstandings. Regular review of blocked issues is advisable to prevent indefinite delays that could impact project timelines or contractual obligations.
### 5.3. `⛔️ status: discarded`
#### 5.3.1. Purpose
Designates issues that the project team does not intend to resolve.
#### 5.3.2. Characteristics
Typically applied to feature requests that don't align with project goals.
#### 5.3.3. Expectations
Clearly communicate the rationale for discarding issues to manage user expectations and maintain transparency. Ensure that discarded issues don't conflict with any promised features or contractual obligations.
### 5.4. `🙅 status: discontinued`
#### 5.4.1. Purpose
Applies to feature requests for projects in maintenance mode.
#### 5.4.2. Characteristics
Indicates no new features will be added, but bug fixes and support continue.
#### 5.4.3. Expectations
Clearly communicate the project's maintenance status to manage user expectations and potential liability. Ensure that discontinuation doesn't breach any ongoing support agreements or licenses.
### 5.5. `🏷 status: label work required`
#### 5.5.1. Purpose
Indicates issues that need proper labeling and categorization.
#### 5.5.2. Characteristics
May have ongoing discussions but lack appropriate classification.
#### 5.5.3. Expectations
Proper labeling is crucial for efficient project management and may have implications for compliance tracking and reporting. Establish clear guidelines for labeling to ensure consistency and avoid potential misunderstandings.
### 5.6. `🏁 status: ready for dev`
#### 5.6.1. Purpose
Signifies issues that are ready for contribution.
#### 5.6.2. Characteristics
May have an assigned contributor who has expressed interest.
#### 5.6.3. Expectations
Clearly communicate contribution guidelines and any legal requirements (e.g., Contributor Covenant) to potential contributors. Ensure that collaborative efforts are managed in compliance with project licenses and contributor agreements.
### 5.7. `🧹 status: ticket work required`
#### 5.7.1. Purpose
Indicates issues lacking sufficient information for proper triage.
#### 5.7.2. Characteristics
Often paired with Conversation Labels for further clarification.
#### 5.7.3. Expectations
Establish clear guidelines for required information to avoid potential misunderstandings or misdirected efforts. Be mindful of data privacy when requesting additional information from issue reporters.
### 5.8. Disclaimer
Status labels reflect the current assessment of the project team and may change as circumstances evolve. While the project team strives to maintain accurate status labels, contributors and users should communicate with maintainers if they notice any discrepancies or have questions about an issue's status.
## 6. Conversation Labels
Conversation labels indicate that an issue has received initial maintainer attention but requires further discussion or information before proceeding. These labels help manage communication and ensure all necessary information is gathered before taking action.
### 6.1. `💬 talk: discussion`
#### 6.1.1. Purpose
Identifies issues that are under active discussion but have not yet been accepted for resolution.
#### 6.1.2. Characteristics
Ongoing dialogue between maintainers, contributors, and/or users. May involve debates about feature requests, implementation strategies, or project direction.
#### 6.1.3. Expectations
Ensure discussions remain constructive and adhere to the project's code of conduct. Be cautious about making commitments or promises during discussions that could create legal obligations. Document key decisions and rationales to maintain transparency and provide a record for future reference.
### 6.2. `❓ talk: question`
#### 6.2.1. Purpose
Indicates issues waiting on additional information from the author for proper triage.
#### 6.2.2. Characteristics
Requires clarification or more details from the issue creator. Cannot proceed with triage or resolution until the requested information is provided.
#### 6.2.3. Expectations
Clearly communicate what information is needed and why it's necessary. Be mindful of data privacy when requesting additional information. Establish and communicate timeframes for expected responses to manage the issue lifecycle efficiently.
### 6.3. Disclaimer
Conversation labels indicate ongoing dialogue and do not guarantee that an issue will be implemented or resolved in a specific manner. Participants should understand that project priorities and decisions may change based on new information or project direction.
## 7. Pull Request Labels
Pull Request (PR) labels are used to indicate the current status of pull requests and guide contributors through the review and merge process.
### 7.1. `⚠️ pull: merge conflict`
#### 7.1.1. Purpose
Indicates that the pull request has conflicts with the target branch.
#### 7.1.2. Characteristics
Conflicts need to be resolved before the PR can be reviewed or merged. May require action from the original contributor or project maintainers.
#### 7.1.3. Expectations
Clearly communicate the responsibility for resolving conflicts (e.g., whether it's the contributor's or maintainer's role). Ensure that conflict resolution doesn't introduce unintended changes or legal issues (e.g., license conflicts).
### 7.2. `🔍 pull: ready for review`
#### 7.2.1. Purpose
Signifies that the pull request is not in draft mode and is awaiting maintainer review.
#### 7.2.2. Characteristics
PR has been submitted as complete and ready for evaluation. Maintainers should prioritize reviewing these PRs.
#### 7.2.3. Expectations
Ensure contributors understand that "ready for review" doesn't guarantee acceptance or merging. Maintain clear review criteria and communicate them to contributors.
### 7.3. `⏫ pull: requires update`
#### 7.3.1. Purpose
Indicates that the maintainer team has requested changes to the pull request.
#### 7.3.2. Characteristics
Feedback has been provided, and updates are needed before further review or merging. Requires action from the contributor to address the requested changes.
#### 7.3.3. Expectations
Clearly document requested changes to maintain transparency and avoid misunderstandings. Consider setting timeframes for updates to manage the PR lifecycle effectively.
### 7.4. Disclaimer
The presence of these labels does not guarantee that a pull request will be merged. All contributions must still meet the project's quality standards, guidelines, and legal requirements.
## 8. Continuous Improvement
We encourage all project participants to provide feedback on our labeling system. If you have suggestions for improvements or notice any inconsistencies, please reach out to us in our [chat server](https://chat.nhcarrigan.com).
## 9. Legal Notice
This labels documentation is provided for informational purposes and to facilitate project management. It does not constitute a legal agreement. All contributions to the project must comply with the project's license, contributor agreement (if applicable), and relevant laws and regulations.
By using these labels and participating in the project, you agree to abide by the project's code of conduct and contribution guidelines.