Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue to review the contributing document and add a triage process proposal #538

Merged
merged 19 commits into from
Feb 16, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# Guidelines for contributing to the JSON Schema project GitHub organisation

🚨 Work in progress! (2021/07 - @relequestual)

We invite you to join us working on JSON Schema.

The fastest way to get involved and become active in the community is to join our Slack server at https://json-schema.org/slack.
The fastest way to get involved and become active in the community is to join the `#contribute` channel in our Slack server at https://json-schema.org/slack.

If you have suggestions on how to improve our community, please do check out our [Community Discussions](https://github.com/json-schema-org/community/discussions), and start a new discussion.

# General

While each repository may have its own guidance for contributing, the following sections apply organisation wide.
The JSON Schema organization hosts different projects, and while most have similar contributing guidelines as described in this document, the JSON Schema Specification development process follows different contributing guidelines. Please, check-out the [Spec repository](https://github.com/json-schema-org/json-schema-spec/blob/main/CONTRIBUTING.md) to know more.
Relequestual marked this conversation as resolved.
Show resolved Hide resolved

The following sections apply organisation wide to all repositories.

## Key "Architectural" decisions

Expand Down Expand Up @@ -45,6 +45,10 @@ Once an ADR is part of a pull request which is labelled with `adr-required`, the

The process is designed to be lightweight, and a template is provided for ease of use.

### Triage

Please check the [triage process](TRIAGE.md) to learn how we review and label incoming issues .

### Feedback

Feedback on this process can be made informally through our [Slack server](https://json-schema.org/slack) and formally using our [Community Discussions](https://github.com/json-schema-org/community/discussions).
65 changes: 65 additions & 0 deletions TRIAGE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
## Introduction

This document will outline the process of triaging GitHub issues. **Triage** is the process of reviewing and labeling incoming issues, identifying any which are critical, and escalating the critical ones.

The core maintainers of each project are responsible for categorizing all incoming issues and delegating any critical or important issue to other maintainers. Currently one maintainer each week is responsible. Besides that part, triage provides an important way to contribute to an open source project.

Triage helps ensure issues resolve quickly by:

- Ensuring the issue's intent and purpose is conveyed precisely. This is necessary because it can be difficult for an issue to explain how an end user experiences a problem and what actions they took.
- Giving a contributor the information they need before they commit to resolving an issue.
- Lowering the issue count by preventing duplicate issues.
- Streamlining the development process by preventing duplicate discussions.

If you don't have the knowledge or time to code, consider helping with triage. The community will thank you for saving them time by spending some of yours.

## GitHub Labels

Area labels help categorize issues based on their scope:
| Label | Description |
| ------------------------ | ------------------------------------------------------------------------- |
| `bug` | Indicates that the issue is a bug or a software defect. |
| `enhancement` | Indicates that the issue suggests an improvement or new feature. |
| `documentation` | Indicates improvements or additions to documentation. |
| `roadmap` | Indicates epics and tasks related to roadmap items. |
| `programs` | Indicates epics and tasks related to Community programs. |
| `team` | Indicates issues for team collaboration. |
| `adr-required` | Indicates issues requiring Architectural Decision Record |

Severity labels:
| Label | Description |
| ------------------------ | ------------------------------------------------------------------------- |
| `High priority` | High priority flow or feature is broken/non-functional, crash. |
| `Critical priority` | Indicates Critical impact on data or site: data loss (posts, pages, comments), unexpected publishing, security issue.|



Other labels:
| Label | Description |
| ------------------------ | ------------------------------------------------------------------------- |
| `good first issue` | Indicates that the issue is suitable for newcomers to contribute to the project.|
| `question` | Indicates that the issue lacks sufficient information to be able to act on it right now and requires additional details from the reporter. The maintainer for the area must remove the tag when more info is provided, or close it if it is too old.|
benjagm marked this conversation as resolved.
Show resolved Hide resolved
| `duplicate` | Indicates that is duplicated. |

## Triage process

At the end of reading an issue, you should do one of the following:

1. Make sure to search in previous issue to ensure this is not a duplicated issue. If that is the case, mark it as `duplicate` and close it referencing the original issue. If the issue is clear, ensure it has the correct `area` assigned. Also consider if it is a `good first issue`.

2. Asses the issue severity to determine what functionality is affected and how broken it is and use the severity labels just for High and Critical cases.

3. If the submitter or the reviewer believe the resolution of the Issue is likely to result in a significant or noteworthy change it will be labeled as `adr-required`.

4. Move the issue to the correct repo if required.

5. If it's not clear what the problem or issue is, add a note for the requestor (or occasionally some other user on the thread), and mark it as `question`. If a `question` issue persists for longer than a week or so (past a second followup), it's reasonable to `close` the issue and encourage the requester to reopen if they have more details.
benjagm marked this conversation as resolved.
Show resolved Hide resolved

6. If the request is infeasable, or complete, follow up directly in the issue with the information, and `close` the issue.

### References

This process has been inspired by some great processes defined by Open Source projects like:
- [Knative triage process](https://github.com/knative/serving/blob/main/support/TRIAGE.md).
- [Grafana triage process](https://github.com/grafana/faro-web-sdk/blob/main/ISSUE_TRIAGE.md).
- [Wordpress triage process](https://github.com/wordpress-mobile/WordPress-iOS/blob/trunk/docs/issue-triage.md).