Skip to content

Commit

Permalink
Editorial: move wiki documents to document folder (#1886)
Browse files Browse the repository at this point in the history
Partially resolves #1882
  • Loading branch information
spectranaut authored Mar 21, 2023
1 parent 3406020 commit 9033f63
Show file tree
Hide file tree
Showing 4 changed files with 142 additions and 1 deletion.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This repository is for the main deliverable of the ARIA Working Group, Accessibl

## Contributing to this Repository

Please review the [ARIA Process Document](https://github.com/w3c/aria/wiki/ARIA-WG-Process-Document) for information about how the working group tracks issues and pull request.
Please review the [ARIA Process Document](documentation/process.md) for information about how the working group tracks issues and pull request.

### Role of Editors

Expand Down
44 changes: 44 additions & 0 deletions documentation/onboarding.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
ARIA WG onboarding: Cheat sheet for new members

Please read the [ARIA WG Process Document](process.md)

# ARIA Meeting Information
## Inter Relay Chat(IRC)
### Access via IRC Cloud
* [IRC Cloud ARIA Channel URL](https://www.irccloud.com/irc/w3.org/channel/aria)
* Hostname:irc.irccloud.com
* Port:6697(check secure port)
* Add your nickname and more
* Go to channel #aria

### Access via [IRC Web URL](http://irc.w3.org/)
* add your **Nickname**, "your name"
* add **Channels**, "#aria"

### IRC command cheat sheet
* [ARIA Issue 1404](https://github.com/w3c/aria/issues/1401#issuecomment-786384070)

## ARIA Github Repository
* [ARIA Github Repo URL](https://github.com/w3c/aria)
* [Editor's Draft](https://w3c.github.io/aria)
* This is built from the main branch of the ARIA repository.
* [ARIA Authoring Practices (aka the "APG")](https://www.w3.org/WAI/ARIA/apg/)
* Developer guidance on best practices for ARIA usage
* [Github for APG](https://www.w3.org/WAI/ARIA/apg/)
### How to contribute to the repository
* Your Github account needs to be added to list of people who have the permission to the repo. Please send email to the chairs or <public-aria-editors@w3.org> for access.
* Assign yourself to the issues to review PR.
### Current ARIA contributors
* [Participants active in the ARIA WG](https://www.w3.org/groups/wg/aria/participants)
## Communication
* New member will receive Welcome email from Chairs. If not, let the chairs know.
* ARIA WG Public mailing list:public-aria@w3.org
* Slack channels: w3ccommunity.slack.com/ #aria, web-a11y.slack.com
## Other Specifications Managed by the ARIA Working Group
* [CORE-AAM](https://github.com/w3c/core-aam)
* Contains mappings between ARIA and platform accessibility APIs.
* [HTML-AAM](https://github.com/w3c/html-aam)
* Contains mappings between HTML and platform accessibility APIs.
* [Accessible Name and Description Computation (aka "accname")](https://github.com/w3c/accame)
* How browser should calculate the accessible name and description for elements.

56 changes: 56 additions & 0 deletions documentation/process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# ARIA WG Process Document

## Issues
1. An issue is made on the ARIA repository
2. New issues are "triaged" at the next ARIA WG meeting. During triage, the following happens:
- A release tag is added for purposes of prioritizing whether the issue is resolved in the current release of ARIA or a subsequent release.
- WG members are assigned to the issue if appropriate.
- If the issue clearly needs group discussion, the "agenda" tag 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" tag to any issue they feel needs more discussion in order to reach consensus.
4. After the issue is discussed in a meeting, a WG member should be assigned to summarize the conclusion of the discussion in the issue and open a PR with relevant changes.

## Pull Requests

Newly opened PRs are "triaged" at the next ARIA meeting. At triage, it is decide:
- Who should review the PR
- If the PR needs extra discussion by the whole ARIA WG, the "agenda" tag can be added.

### Normative Changes

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.
- 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.
3. **Tests:** If the change is testable, tests should be add to the validators directory or WPT repo before merging, or, if the PR owner does not have the expertise to write tests, issues should be file in the ARIA repository as a follow up. See [Aria Test Overview](tests.md).
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.

### 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.

1. A PR with only editorial changes MUST have "Editorial: " at the beginning of the PR's title.
2. An editorial change PR needs at least two approving review to be merged, but another reviewer can be request if the change is complex.

### Branches

Important branches in the ARIA repository:
1. **main**: All new PRs should be open against the main branch.
2. The next release branches, such as **1.3**. (At the time of current editing, Nov 4 2022, the 1.2 branch is called "stable".)

## 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 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).
41 changes: 41 additions & 0 deletions documentation/tests.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# ARIA Testing Documentation

## ARIA "author MUST" / Validator Tests

Validator tests are written for "author MUST" or "author MUST NOT" statements. An "author MUST" statement is testable if an HTML validator (such as [AXE](https://www.deque.com/axe/) or [validator.nu](https://validator.nu/) can test whether a given piece of HTML conforms to the specification. Not all "author must" statements are testable. For example, the following statement is testable:

> In order for elements with a role of img to be perceivable, authors MUST provide a label using the aria-label or aria-labelledby attribute.
But the following statement is not testable, because managing focus is dynamic and cannot be done by an html validator:

> Authors MUST manage focus on the following container roles...
The validator tests belong in the [validator-test directory](https://github.com/w3c/aria/tree/main/validator-tests). When adding or updating a test, also supply the test results required in the [README](https://github.com/w3c/aria/tree/main/validator-tests/README.md).

## ARIA "user agent MUST"

Ideally, we should have a test suite to test all "user agent MUST" statements, but we do not have the tooling to write all these tests.

If our change adds or changes a "user agent must" or "user agent must not" statement, please add a issue describing the test one the PR is ready for merge.

## ARIA IDL Interface

Automated tests for the [ARIA IDL interface](https://w3c.github.io/aria/#idl-interface) are in WPT. We have two test files:
* [aria-attribute-reflection.html](https://github.com/web-platform-tests/wpt/blob/master/html/dom/aria-attribute-reflection.html), [Results on wpt.fyi](https://wpt.fyi/results/html/dom/aria-element-reflection.html?label=experimental&label=master&aligned&view=subtest)
* [aria-element-reflection.html](https://github.com/web-platform-tests/wpt/blob/master/html/dom/aria-element-reflection.html), [Results on wpt.fyi](https://wpt.fyi/results/html/dom/aria-attribute-reflection.html?label=experimental&label=master&aligned&view=subtest)

When the IDL Interface section is updated, these tests should be update accordingly.

## CORE-AAM Tests / WPT Tests

The tests are located in [WPT's core-aam folder](https://github.com/web-platform-tests/wpt/tree/master/core-aam). They are "manual" tests in that you have to use a tool outside of the web browser and WPT test suite to inspect the accessibility API. For now, Valerie will maintain these CORE-AAM tests and no one else needs to write them.

## HTML-AAM Tests

We do not yet have tests for HTML-AAM.

## AccName Tests

We do not yet have infrastructure for AccName tests. Better AccName tests are being investigated in this issue: https://github.com/w3c/accname/issues/174

When we have a new test framework for AccName test, we will create an initial set of tests and all following PRs to AccName will have a testing requirement.

0 comments on commit 9033f63

Please sign in to comment.