ARB Standards & Guidelines¶

Scope: ARB
Type: Standard
Version: 2022-initial

Goal¶

To define a template for ARB Standards and Guidelines, as well as the means for their approval.

ARB writes standards to set benchmarks of quality and document our expectations. ARB writes guidelines to speed adoption and foster compliance.

Both standards and guidelines should make adoption easier than charting your own course.

Ownership¶

Direct questions to the Owner: Seth A. Roby email redacted

Resources to comply with this standard should be directed via the Executive sponsor: Eric Taggart

Timeline & Enforcement¶

By the end of 2022, all standards MUST live up to the attributes mentioned in this standard. Any standards that do not meet these requirements by that date SHALL no longer be considered ARB standards.

Exception Process¶

Exceptions that do not meet the standards by the deadline MAY petition the ARB for an extension. A majority vote will extend the deadline for three months. Additional extensions MAY be requested for up to one year after the initial deadline.

Terminology¶

• ARB Standard any document that follows the requirements of this document, using the “Type: Standard” subhead, and which has been given a majority vote of the ARB membership. OIT personnel MUST follow all ARB standards.
• ARB Guideline any document that follows the requirements of this document, using the “Type: Guideline” subhead, and which has been given a majority vote of the ARB membership. OIT personnel SHOULD follow all ARB guidelines.
• ARB Recommendation not defined or subject to this standard. The recommendations are found elsewhere and are meant to provide information to the OIT and UCI community without requiring compliance.
• ARB Artifact is any ARB Standard, ARB Guideline, or ARB Recommendation
• The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119

Requirements¶

Format¶

1. The document MUST be formatted in Markdown.

Sections¶

1. The document MUST include a Title section, for ease of reference.
2. The document MUST include a Version section, to distinguish changes over time.
   1. The version MUST be made up of the adoption year and a one-word description
3. The document MUST include a Goal section, to explain why the document is needed.
   1. It SHOULD contain no more than four sentences.
4. The document MUST include a Ownership section, to identify the parties responsible for the standard in its current form.
   1. It MUST contain an Owner
   2. It SHOULD contain an Executive sponsor to speed up adoption
5. The document MUST include a Timeline & Enforcement section, to signal expectations
   1. It MUST explain when the standard goes into effect
   2. If there are deadlines, the document MUST note the consequences of failing to meet the standard by the deadline
   3. If there are deadlines, the document MUST contain an Exception Process explaining how to obtain an exception, and what the exception means.
6. The document MUST include a Terminology section, defining any terms of art used in the document
   1. The document SHOULD include a reference to RFC 2119.
7. The document MUST include a Requirements section, explaining how to comply
   1. To make reference easier, the body SHOULD be presented in sections, with each section containing a nested, numbered list.
   2. For example, this item can be referenced as “Sections, item 7.ii”

Change management¶

1. The document MUST be checked in to OIT’s GitHub repository.
2. All changes to the document MUST be made via Pull Requests.
   1. All Pull Requests MUST be announced the the ARB membership
   2. All Pull Requests SHOULD be open for no less than one month, to allow for the proposed change to be thoroughly discussed.
   3. No Pull Request should be merged until a vote approves the change

Voting¶

1. A consensus vote of the ARB is required for any document to become a guideline or a standard