Accessibility Validation Rules Review Process

From MemberWiki

Accessibility Home | Issue Tracker | WCAG 2.0 Rules | Rules Format 1.0 | Cache | Proposed WCAG 2.0 Techniques | Rule Review | Testsuite | Evaluation Results | Reporting Practices

Contents 1 Introduction 2 General Rules Review Process 2.1 Submission 2.2 Review 2.3 Approved 2.4 Rule modification 3 Rules Repository

Introduction

The Accessibility Validation Rule Codification Requirements set forth by this group specify the format for validation rules to be used by rule authors and expected by accessibility tool vendors. To ensure that rule authors comply with this specification and to facilitate the maintainability and broadest applicability of validation rules offered by this group, this document sets forth a Rules Review Process that each contributing organization must follow in order to have its rules included in the rules repository (discussed below). Both the process for submitting, reviewing, and approving new validation rules and for editing existing rules as well as the criteria by which validation rules are to be evaluated are discussed in this document.

General Rules Review Process

The following steps outline the procedure for either contributing a new validation rule to the rules repository or for modifying an existing validation rule for the purposes of enhancing or repairing it. Notice that, for each step, there is a corresponding state for that rule that should be noted in that rule's documentation. For instance:

/*
 * description of rule
 * dependencies, browser specifics, etc.
 * State: [Submitted, Reviewing, Approved]
 */

Submission

The first step is for an individual or contributing organization to submit a validation rule to the group for consideration. At this time, the new rule is considered to be in the submitted state and cannot appear in any rulesets. Submission of a validation rule may occur either by:

1. an individual directly committing a new validation rule to the rules repository and notifying the group via the mailing list at accessibility@openajax.org of this commit. In this case, the individual must belong to a member organization of the OpenAjax Alliance and have write-access to the rules repository. (See the discussion of the rules repository below on how to be granted write-access to this repository.) The individual is also responsible for marking the rule as 'Submitted'.
2. an individual submitting a validation rule to the OpenAjax Alliance Accessibility Tools Task Force mailing list at accessibility@openajax.org. In this case, the chair of the task force must designate an owner of that rule who will be responsible for committing the rule to the rules repository and marking the rule as 'Submitted'. This tactic is useful for those organizations who do not wish to become members of the OpenAjax Alliance, but who wish to contribute to this effort. Organizations or individuals who are members of organizations that are not members of the OpenAjax Alliance and who wish to make regular contributions are encouraged to become members of the OAA.

Proposed rules that need to be reviewed will be committed into a location in the repository that is specifically for rules that have not yet been approved. This location is still to be determined. Once approved, the rules will be removed from that location and committed to the location for all approved rules.

Review

Following the submission of a validation rule, the rule must be reviewed by designated active members of the Accessibility Tools Task Force. It is the responsibility of the chair of this task force to designate an individual or group of individuals to perform the review of a newly submitted validation rule. At this point, the rule must be marked as being in the Reviewing state and cannot appear in an active ruleset in the rules repository.

Rules should be reviewed with the following criteria in mind:

1. submitted rule conforms to the Accessibility Validation Rule Codification Requirements, including, at minimum:
   1. a rule id taken from the range of rule ids designated for the contributing organization
   2. a context property and well-formed context expression for that rule
   3. a validate function containing the rule logic for that rule
2. submitted rule is syntactically correct JavaScript that could be entered into a JavaScript interpreter of the reviewers' choosing and not produce any syntax errors
3. submitted rule could be entered into a file and consumed by a browser or run by a test harness and not produce any runtime errors or exceptions
4. submitted rule follows common best practices for coding and formatting such as:
   1. correct and consistent indentation of blocks of code such as control flow structures, conditional expressions, and function definitions
   2. appropriate and meaningful documentation throughout code explaining algorithm and rule logic as well as introductory documentation describing the test being performed and the dependencies of the rule object
   3. conforming to best practices for JavaScript coding
5. submitted is either browser-neutral or is indicated in its documentation as specific to a single browser; browser-dependent rules should be avoided or use alternative or wrapper APIs contributed by this group to ensure consistent behavior
6. submitted rule is highly-scalable and prizes performance (e.g. favors caching strategies over repeated queries of DOM)
7. submitted rule includes a test case with appropriate test metadata

Approved

Once the validation rule is reviewed by those designated by the chair, the validation rule is either approved by that group or returned to the author for modifications based on feedback from the group. The rule is also returned to the Submitted state. The rule author should notify the group when the rule is ready for another review process. This process continues until the rule is approved by the designated group within the task force or withdrawn by the rule author.

Once the rule is approved, it should be marked as in the Approved' state in its documentation and can now be included in active rulesets in the rules repository. It should be removed from its current location in the repository and committed to the location where all approved rules are put.

Rule modification

If a validation rule is noted as having a defect, does not work according to the test case that is submitted with it, or requests for enhancements to the rule are made, the rule should be placed in the Reviewing' state once again and the process for that step should once again be resumed by the group until the rule reaches the Approved state. Requests for enhancements of a validation rule or defects noted for a validation rule should be filed in the tracking system. (You must be logged in with your sourceforge.net account and submit defects and requests for enhancements under the A11y_tools category.)

Rules Repository

The rules repository is a Subversion source code repository maintained by sourceforge.net. If you need access to this repository:

1. Obtain Apache Subversion and use it in command-line mode or through available IDE plugins such as those available for the Eclipse IDE.
2. Go to http://sourceforge.net and create an account. The user name and password you choose for this account will be your user name and password for any OpenAjax Alliance Subversion repository.
3. All OAA repositories for work within the OAA use the Subversion URL

   https://openajaxallianc.svn.sourceforge.net/svnroot/openajaxallianc

   .
4. For purposes of the Accessibility Tools Task Force, the only folder within this repository that you need to checkout is the accessrules folder. (The only directory within this project you need to use is src, unless you are using the Eclipse IDE, in which case you should also checkout the .project file and .settings directory.

The structure of the src folder is as follows:

src
  nls - localization files
  rules folders of files containing actual rule objects
  rulesets - contains ruleset objects
  scripts - contains auxiliary helper scripts for processing rules, rule logic, and rulesets
  wai-aria - contains wai-aria related files, such as aria_definitions.js, the file that contains WAI-ARIA global states and properties, WAI-ARIA property data types, and WAI-ARIA design patterns
  oaa-a11y.js - entry point for our work

If you have only read-access to this repository, you can email the OAA Accessibility Tools Task force at accessibility@openajax.org or Jon Feraiolo at jferrai@us.ibm.com to be granted write access.