From 88690c5673cf4dfb2a243a3d2ad95ed8fa47487a Mon Sep 17 00:00:00 2001 From: Valerie Young Date: Fri, 14 Jun 2024 09:20:20 -0700 Subject: [PATCH] Editorial: updates to README and process document after monorepo --- README.md | 49 +++++++++++++++++++++++++++++++++++++--- documentation/process.md | 33 ++++++++++++++++++++------- 2 files changed, 71 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 87aed39ae..e68ee64be 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,52 @@ $ git fetch origin $ git branch -u origin/main main ``` -## Other Repositories - -This repository is for the main deliverable of the ARIA Working Group, Accessible Rich Internet Applications. There are several other deliverables, such as ARIA modules, Accessibility API Mappings, and support documents. These are maintained in separate repositories listed on the [ARIA Contribution](https://www.w3.org/WAI/ARIA/contribute) page. Please file issues in the repository specific to the specification to which the issue applies. +## Specifications in this repository + +This repository contains the main deliverable of the ARIA Working Group, Accessible Rich Internet Applications (ARIA), and should be used for issues related to the ARIA spec and and issues that involve both the ARIA spec in conjunction with other specifications maintained by the ARIA working group. All other specifications maintained by ARIA can be found in this repository as well, however, we have separate issue tracking repos for these separate specifications. + +* Accessible Rich Internet Applications (aria) + * [Spec](aria/index.html) + * [Editor's Draft](https://w3c.github.io/aria/) + * [Issue Repository](https://github.com/w3c/aria) +* Accessible Name and Description Computation (accname) + * [Spec](accname/index.html) + * [Editor's Draft](https://w3c.github.io/accname/) + * [Issue Repository](https://github.com/w3c/accname) +* Core Accessibility API Mappings (core-aam) + * [Spec](core-aam/index.html) + * [Editor's Draft](https://w3c.github.io/core-aam/) + * [Issue Repository](https://github.com/w3c/core-aam) +* HTML Accessibility API Mappings (html-aam) + * [Spec](html-aam/index.html) + * [Editor's Draft](https://w3c.github.io/html-aam/) + * [Issue Repository](https://github.com/w3c/html-aam) +* Digital Publishing WAI-ARIA Module (dpub-aria) + * [Spec](dpub-aria/index.html) + * [Editor's Draft](https://w3c.github.io/dpub-aria/) + * [Issue Repository](https://github.com/w3c/dpub-aria) +* Digital Publishing Accessibility API Mappings (dpub-aam) + * [Spec](dpub-aam/index.html) + * [Editor's Draft](https://w3c.github.io/dpub-aam/) + * [Issue Repository](https://github.com/w3c/dpub-aam) +* Graphics WAI-ARIA Module (graphics-aria) + * [Spec](graphics-aria/index.html) + * [Editor's Draft](https://w3c.github.io/graphics-aria/) + * [Issue Repository](https://github.com/w3c/graphics-aria) +* Graphics Accessibility API Mappings (graphics-aam) + * [Spec](graphics-aam/index.html) + * [Editor's Draft](https://w3c.github.io/graphics-aam) + * [Issue Repository](https://github.com/w3c/graphics-aam) +* SVG Accessibility API Mappings (svg-aam) + * [Spec](svg-aam/index.html) + * [Editor's Draft](https://w3c.github.io/svg-aam/) + * [Issue Repository](https://github.com/w3c/svg-aam) +* MathML Accessibility API Mappings (mathml-aam) + * [Spec](mathml-aam/index.html) + * [Editor's Draft](https://w3c.github.io/mathml-aam/) + * [Issue Repository](https://github.com/w3c/mathml-aam) + +In addition to these specifications, there are other deliverables of the [ARIA Contribution](https://www.w3.org/WAI/ARIA/contribute) page. Please file issues in the repository specific to the specification or deliverable to which the issue applies. ## Contributing to this Repository diff --git a/documentation/process.md b/documentation/process.md index 730d2d7c0..6b81ecce5 100644 --- a/documentation/process.md +++ b/documentation/process.md @@ -1,9 +1,10 @@ # ARIA WG Process Document ## Issues -1. An issue is made on the ARIA repository +1. An issue is made on an ARIA WG repository 2. New issues are "triaged" at the next ARIA WG meeting. During triage, the following happens: - - A release label is added for purposes of prioritizing whether the issue is resolved in the current release of ARIA or a subsequent release. + - The issues is moved to the appropriate issue tracking repo, if necessary + - A release label is added for purposes of prioritizing which year we expect to be able to resolve the problem or feature request. - WG members are assigned to the issue if appropriate. - If the issue clearly needs group discussion, the "agenda" label is added to the issue in order for the issue to be scheduled for discussion at a later meeting. 3. WG members can add the "agenda" label to any issue they feel needs more discussion in order to reach consensus. @@ -26,10 +27,9 @@ PR Labels: A "normative" change is change to the specification that is not editorial, that is, it will change the implementation of the ARIA in browsers (for example, adding a new attribute) OR it will change how ARIA can or should be used by web authors (for example, changing which attributes are allowed on a role). #### Requirements for merging a normative PR: -1. **Consensus:** The change in the PR has been discussed in a ARIA WG meeting and the general direction of the change has been consensed on. The ARIA WG's consensus should be recorded in comments of the PR or in the comments of the issue that the PR resolves. - - If a PR has been opened for an issue that has not been discussed, or if the PR has been open to explore an option that the ARIA WG has not yet come to consensus on, the PR should be left in the draft state. - - During the course of review of the PR, the consensus of the ARIA WG might change. This can happen in any ARIA WG meeting. Changes should be recorded in the comments of the PR. -2. **Review:** Every PR needs at least two approving reviews from ARIA WG members, but depending on the complexity of the change, the ARIA WG may assign additional reviewers. +1. **Consensus:** The change in the PR has been discussed in a ARIA WG meeting and the general direction of the change has been consensed on. + - The ARIA WG's consensus should be recorded in comments of the PR or in the comments of the issue that the PR resolves. +2. **Review:** Every normative PR needs 3 approving reviews from ARIA WG members, but depending on the complexity of the change, the ARIA WG may assign additional reviewers. - The reviewers should be made based on the text and meaning of the change, not on whether the checklist has been fulfilled. - Any working group member can add themselves as a reviewer. - Any one from the general public is allowed to review PRs in order to inform the ARIA WG of approval or concerns. @@ -37,10 +37,27 @@ A "normative" change is change to the specification that is not editorial, that 4. **APG:** If the change requires a change to the [APG](https://github.com/w3c/aria-practices), an issue on the APG should be made describing the change. 5. **Implementation:** If the change requires implementation changes, issues should be opened on the browser after the PR has been approved. - At least one implementation is required for merge. Implementation or implementation commitment from two browsers is required for merge. -6. **Related Spec Changes:** If the change requires changes to CORE-AAM, HTML-AAM or AccName, the PRs with dependent changes should be merged at the same time. All repositories have the same review and implementation requirements before merging. Note: The fact that a PR requires implementation to merge is new as of 2022. We understand this will cause the life of a PR to be long -- and that the original champion of the PR might need to hand off work to another ARIA WG member while the PR waits for implementations. +#### Stages of a normative change + +##### Stage one: `Waiting for Review` + +In this stage, the normative change (sometimes spanning multiple specifications) should be written and reviewed. When changes have three approving reviews, we move to the next stage. + +##### Stage two: `Waiting for Tests` + +Test should be written after the spec language is approved by three approving reviews. At this time, changes to test in WPT can land because the spec changes are considered finalized, but they must land with the ".tentative" file ending. Note: not all normative changes in ARIA are currently testable, so if they are not testable, tests are not required. + +##### Stage three: `Waiting for Implementations` + +Once tests have been written, open issues on the browsers with clear links to all relevant PRs and tests. Add the `waiting for implementations` label to the PR. + +##### Stage four: merged! + +When there is at least one implementation and implementation commitment from other browsers, merge! + ### Editorial Changes An "editorial" change is a change that is not normative. Editorial changes are things like grammar fixes, improvements to a section for improve readability or clarity, re-organization, the introduction of terms, etc. @@ -56,7 +73,7 @@ Important branches in the ARIA repository: ## Normative Change Checklist -The "normative change checklist" list a kind of "to do list" for all the changes that must happen else where (in CORE-AAM, browsers, or the APG) in order for a change to be considered ready for merge. Check the box when there is a relevent issue or PR related to the item in the list, and link the relevant issue or PR. Some of the things in the list may not apply to your change, if they don't apply, check the box and write "n/a". If you aren't sure whether something applies, leave it uncheck. +The "normative change checklist" list a kind of "to do list" for all the work that must happen in order for a change to be considered ready for merge. Check the box when there is a relevant issue or PR related to the item in the list, and link the relevant issue or PR. Some of the things in the list may not apply to your change, if they don't apply, check the box and write "n/a". If you aren't sure whether something applies, leave it unchecked. The normative change checklist should be included in the PR template when you open a PR, if for some reason it is missing, you can copy it into the description of the PR: [Normative Change Checklist](https://github.com/w3c/aria/blob/main/.github/pull_request_template.md). \ No newline at end of file