Skip to content

Commit

Permalink
Process: Add documentation for labels, current and proposed
Browse files Browse the repository at this point in the history
Co-authored-by: Anssi Kostiainen <anssi.kostiainen@intel.com>
  • Loading branch information
inexorabletash and anssiko committed Jan 30, 2024
1 parent 479ce17 commit 00e8818
Show file tree
Hide file tree
Showing 2 changed files with 105 additions and 1 deletion.
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ Similarly, a stylistic change does not necessarily require opening a GitHub Issu
Follow the guidance in [SpecCodingConventions.md](SpecCodingConventions.md) for your change to ensure it aligns with best practices and existing conventions.

Bug fixes and new content changes should proceed as follows:
1. **Open an issue in GitHub Issues** with a brief description of the problem and a potential solution if it's not already obvious. A proposal or suggestion for improvement may need a bit more explanation with possible references to related information. An active issue is the best way to get attention. Members of the Working Group scan active issues constantly.
1. **Open an issue in GitHub Issues** with a brief description of the problem and a potential solution if it's not already obvious. A proposal or suggestion for improvement may need a bit more explanation with possible references to related information. An active issue is the best way to get attention. Members of the Working Group scan active issues constantly and should apply labels to help categorize them, following the guidance in [IssueTriage.md](IssueTriage.md). If you're a member of the Working Group, please apply appropriate labels to the new issue.

2. **Prepare the change in a pull request** and put a reference to the active issue(s) the change is addressing in the description. We prefer that a pull request is represented by a single type of change as outlined in the previous section for a speedy review and approval. Conversely, a specific change should also be captured by a single and not multiple pull requests. This helps to reduce the dependency between pull requests and the chance for the specification to be left in a transient state between multiple pull requests. Exceptions to this should be discussed and approved by the Working Group in one of our bi-weekly calls.

3. **Close the issue** once the pull request is reviewed and merged. Make sure to resolve any error that arises during the merge and check the post-merged published result. The Bikeshed document format isn't very good for an automatic merge, you may need to intervene and manually correct the merge's mistakes if any. You also want to make sure all the GitHub Actions that are put in place to catch document issues are all clean before merging the change into the main branch.
Expand Down
103 changes: 103 additions & 0 deletions IssueTriage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# Triage Guidance for WebNN Repo

TODO: Consider removing these, or fit these into the documentation below.

- **enhancement** - unclear if this is about the spec text, the proposed API, etc. Prefer **feature request** etc.
- **help wanted** - unclear what help is needed; use **needs PR** or **question** instead?


## Label Usage

Labels are used for:

- Understanding the status of a specific issue and next steps to resolve it.
- Understanding the scope of work remaining on broad efforts (e.g. aligning with best practices, fixing normative issues, etc)
- Identifying areas to contribute.

The working group chairs and spec editors should regularly review bugs and ensure that labels are accurate, and ensure that issues are getting appropriate attention; for example, scheduling discussion of new feature requests, discussion to resolve outstanding questions, and drawing attention to issues that are ready for a contributor to author a PR.


## Types

Every issue should have one of these issue types, and only rarely more than one.

- **bug** - a flaw in the specification that will require a normative fix; for example, an algorithm computes an output incorrectly
- **conventions** - where the spec does not conform to specification best practices from Web IDL, Bikeshed, Infra, etc.
- **use case** - a new use case for the API that should be documented or considered; may spawn other issues
- **process** - a meta issue about how the specification is evolved; for example, a discussion of issue labels
- **testing** - discussion of test coverage
- **feature request** - _PROPOSED_ - suggestion for an addition to the proposed API
- **interop** - _PROPOSED_ - discussion of differences in behavior across implementations
- **samples** - _PROPOSED_ - suggestions for additional or improved samples


## Spec Impact

These broad categories describe the projected impact on the specification and implementation of an issue.

- **editorial** - spec text could be improved, but does not imply normative behavior changes to the proposed API
- **normative** - _PROPOSED_ - resolving the issue would require behavior changes, likely affecting implementations and tests

TODO: I'm not convinced of the utility of these; maybe drop them?


## Issue Scope

Every issue should have at least one of these issue types, but occasionally multiple.

- **operation set** - discussions about the overall operator coverage of WebNN; examples include alignment with other published operator sets, use cases that require multiple new operators, compatibility with implementations, etc.
- **operator specific** - _PROPOSED_ - issues regarding the specification of a single operator or small number of operators


## Next Steps

- **question** - there is outstanding discussion needed on the issue before progress can be made
- **good first issue** - issues that do not require significant context for new contributors


- **needs PR** - _PROPOSED_ - when an issue has enough discussion that the next step is to author a PR for review
- **has PR** - _PROPOSED_ - the issue has a corresponding PR which should be reviewed

- **needs WPT** - _PROPOSED_ - a corresponding Web Platform Test should be filed, either to capture new behavior or cover a gap
- **has WPT** - _PROPOSED_ - test coverage exists (either merged or in review)


## Resolved Issues

These labels can be applied to issues when the issue is closed. This is helpful to capture why the issue was closed if it isn't clear from context.

- **duplicate**
- **invalid**
- **spam**
- **wontfix**

NOTE: GitHub supports two different actions when closing an issue: "Close as completed (Done, closed, fixed, resolved)" and "Close as not planned (Won't fix, can't repo, duplicate, stale)". The UI is subtle, but contributors are encouraged to select an appropriate resolution to assist with future review of issues, in addition to selecting an appropriate label.


## Timeline

- **cr** - issue is a blocker for the next Candidate Recommendation
- **v2**- issue is not considered a blocker for Proposed Recommendation

Implicitly, all issues not tagged **v2** must be resolved before the specification should advance to the next maturity level.


## Horizontal Reviews

These labels will generally be applied to issues by a W3C horizontal review group or to bring an issue to the attention of this group for feedback. These labels are common across W3C spec repos.

- **a11y-needs-resolution** - raised by Accessibility Group
- **a11y-tracker** - bring to attention of Accessibility Group
- **i18n-needs-resolution** - raised by Internationalization Group
- **i18n-tracker** - bring to attention of Internationalization Group
- **privacy-needs-resolution** - raised by Privacy Group
- **privacy-tracker** - bring to attention of Privacy Group
- **security-needs-resolution** - raised by Security Group
- **security-tracker** - bring to attention of Security Group
- **tag-needs-resolution** - raised by Technical Architecture Group
- **tag-tracker** - bring to attention of Technical Architecture Group


## Label Administration

If you think a new label should be introduced, an old label retired, or the usage of a label reconsidered, please file a PR modifying this file including the proposed change.

0 comments on commit 00e8818

Please sign in to comment.