SIA-R6: deprecate rule (#1461)

* Add doc on writing rules * Deprecate SIA-R6 * Extract API * Add deprecation message --------- Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Siteimprove · Aug 31, 2023 · 89fdf18 · 89fdf18
1 parent 6cd2f1e
commit 89fdf18
Show file tree

Hide file tree

Showing 8 changed files with 75 additions and 20 deletions.
diff --git a/.changeset/bright-pumpkins-accept.md b/.changeset/bright-pumpkins-accept.md
@@ -0,0 +1,7 @@
+---
+"@siteimprove/alfa-rules": minor
+---
+
+**Breaking:** SIA-R6 is now deprecated, following ACT rules changes.
+
+The rule is still available as `Deprecated.DR6` for a while.
diff --git a/docs/review/api/alfa-rules.api.md b/docs/review/api/alfa-rules.api.md
@@ -29,7 +29,7 @@ import { Text } from '@siteimprove/alfa-dom';
 const _default: Rule.Atomic<Page, Document, Question.Metadata, Element<string>>;
 
 // @public (undocumented)
-const _default_10: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
+const _default_10: Rule.Atomic<Page, Document, {}, Document>;
 
 // @public (undocumented)
 const _default_11: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
@@ -38,10 +38,10 @@ const _default_11: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
 const _default_12: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
 
 // @public (undocumented)
-const _default_13: Rule.Atomic<Page, Attribute<string>, {}, Attribute<string>>;
+const _default_13: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
 
 // @public (undocumented)
-const _default_14: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
+const _default_14: Rule.Atomic<Page, Attribute<string>, {}, Attribute<string>>;
 
 // @public (undocumented)
 const _default_15: Rule.Atomic<Page, Attribute<string>, {}, Attribute<string>>;
@@ -125,7 +125,7 @@ const _default_38: Rule.Composite<Page, Element<string>, Question.Metadata, Elem
 const _default_39: Rule.Atomic<Page, Element<string>, Question.Metadata, Element<string>>;
 
 // @public @deprecated (undocumented)
-const _default_4: Rule.Atomic<Page, Attribute<string>, {}, Attribute<string>>;
+const _default_4: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
 
 // @public (undocumented)
 const _default_40: Rule.Atomic<Page, Element<string>, Question.Metadata, Element<string>>;
@@ -157,8 +157,8 @@ const _default_48: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
 // @public (undocumented)
 const _default_49: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
 
-// @public (undocumented)
-const _default_5: Rule.Atomic<Page, Element<string>, Question.Metadata, Element<string>>;
+// @public @deprecated (undocumented)
+const _default_5: Rule.Atomic<Page, Attribute<string>, {}, Attribute<string>>;
 
 // @public (undocumented)
 const _default_50: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
@@ -223,8 +223,8 @@ const _default_68: Rule.Atomic<Page, Element<string>, Question.Metadata, Element
 // @public (undocumented)
 const _default_69: Rule.Atomic<Page, Text, Question.Metadata, Text | Group<Element<string>>>;
 
-// @public @deprecated (undocumented)
-const _default_7: Rule.Atomic<Page, Text, Question.Metadata, Text>;
+// @public (undocumented)
+const _default_7: Rule.Atomic<Page, Element<string>, Question.Metadata, Element<string>>;
 
 // @public (undocumented)
 const _default_70: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
@@ -289,8 +289,8 @@ const _default_88: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
 // @public (undocumented)
 const _default_89: Rule.Atomic<Page, Document, Question.Metadata, Document>;
 
-// @public (undocumented)
-const _default_9: Rule.Atomic<Page, Document, {}, Document>;
+// @public @deprecated (undocumented)
+const _default_9: Rule.Atomic<Page, Text, Question.Metadata, Text>;
 
 // @public (undocumented)
 const _default_90: Rule.Atomic<Page, Element<string>, {}, Element<string>>;
@@ -318,11 +318,12 @@ const _default_97: Rule.Atomic<Page, Attribute<string>, {}, Attribute<string>>;
 
 declare namespace deprecatedRules {
     export {
-        _default_4 as DR18,
-        _default_5 as DR34,
-        _default_6 as DR36,
-        _default_7 as DR66,
-        _default_8 as DR69
+        _default_4 as DR6,
+        _default_5 as DR18,
+        _default_6 as DR34,
+        _default_7 as DR36,
+        _default_8 as DR66,
+        _default_9 as DR69
     }
 }
 export { deprecatedRules }

diff --git a/packages/alfa-rules/README.md b/packages/alfa-rules/README.md
@@ -0,0 +1,42 @@
+# Alfa Rules
+
+This package contains the implementation of Alfa's Accessibility rules. Most of these are direct implementation of the corresponding [ACT rule](https://www.w3.org/WAI/standards-guidelines/act/rules/), while some are Siteimprove specific rules.
+
+All rules are named "SIA-RXX" with "XX" being a unique number. This is the abbreviation of "SiteImprove Accessibility Rule". Rule numbers are never re-used even if a rule gets removed, … Thus some numbers can be "missing". When rules share significant amount of code, this can be stored in the [`src/common`](./src/common) directory.
+
+## Rule lifecycle
+
+Each rule lives in its own subdirectory of [`src`](./src), named `sia-rXX` with `XX` being sequential numbers without any leading zeros. These directory mostly contain a single `rule.ts` file, sometimes additional helper files. Similarly tests live in a `sia-rXX` subdirectory of [`test`](./test), mostly as a single file `rule.spec.tsx`.
+
+Rules have tags. A rule must at least have a `Scope` and a `Stability` tag, plus an optional `Version` tag (version 1 is assumed if missing).
+* Most rules only exist with the `Stability.Stable` tag.
+* Rules that make use of new capacities that are not implemented downstream, or newer version with breaking changes, have a `Stability.Experimental` instead. When both a stable and experimental version of a rule need to co-exist, the experimental version lives in a `sia-erXX` sub-directory instead.
+* Rules that have been deprecated, or former versions of a rule, have a `Stability.Deprecated` instead. Deprecated rules live in a `sia-drXX` sub-directory instead.
+
+## Adding a new rule
+
+New rules can directly be added in their own `sia-rXX` directory. If the rule doesn't use anything that isn't implemented downstream, it can be set as stable directly, otherwise set it as experimental. Example of breaking changes include a new type of answers for questions, a new type of test target, …
+
+Make sure to record the rule in [`tsconfig.json`](./tsconfig.json) and [the rule list](./src/rules.ts). Set a scope of either component of page depending if the rule makes sense when testing individual components.
+
+Add tests for the rule. The rule tests effectively act as final integration tests for the rest of Alfa's code. Rules are the final code that Alfa uses, so nearly everything else only exists to be used in rules.
+
+## Creating a new version of a rule
+
+Most changes in a rule don't require a new version and can be done directly in the rule. Changes that require a new version are any breaking changes to the API of the rule. Notably, changing the questions asked, non-backward-compatible change in the `Diagnostic`, changing the number of expectations, …
+
+When a new version is added, we need to create it as an experimental rule, so that both versions have time to co-exist while we upgrade the consumers downstream. Create the `sia-erXX` directory and put the new version here. Remember to change the stability to experimental and to increase the version number (or add one at `2` if the old version doesn't have any yet). Add the experimental rule to [the experimental rule list](./src/experimental.ts).
+
+## Deprecating a rule
+
+Rename its directories from `sia-rXX` to `sia-drXX`, update the `tsconfig.json`, remove the rule from 
+[the list of rules](./src/rules.ts) and add it to [the list of deprecated rules](./src/deprecated.ts). Update the stability from stable to deprecated, add a `@deprecated` TSdoc tag.
+
+Deprecated rules can be deleted at a later point.
+
+## Promoting rule version 
+
+When downstream consumers are ready (or mostly ready) to consume a rule, it can be promoted to stable.
+
+Deprecate the stable rule. Move the experimental one from `sia-erXX` to `sia-rXX` directories, update the `tsconfig.json`, rules list, deprecated rules list, and experimental rules list. Change the stability of the rule.
+
diff --git a/packages/alfa-rules/src/deprecated.ts b/packages/alfa-rules/src/deprecated.ts
@@ -1,3 +1,4 @@
+export { default as DR6 } from "./sia-dr6/rule";
 export { default as DR18 } from "./sia-dr18/rule";
 export { default as DR34 } from "./sia-dr34/rule";
 export { default as DR36 } from "./sia-dr36/rule";

diff --git a/packages/alfa-rules/src/rules.ts b/packages/alfa-rules/src/rules.ts
@@ -3,7 +3,6 @@ export { default as R2 } from "./sia-r2/rule";
 export { default as R3 } from "./sia-r3/rule";
 export { default as R4 } from "./sia-r4/rule";
 export { default as R5 } from "./sia-r5/rule";
-export { default as R6 } from "./sia-r6/rule";
 export { default as R7 } from "./sia-r7/rule";
 export { default as R8 } from "./sia-r8/rule";
 export { default as R9 } from "./sia-r9/rule";

diff --git a/packages/alfa-rules/src/sia-r6/rule.ts → packages/alfa-rules/src/sia-dr6/rule.ts b/packages/alfa-rules/src/sia-r6/rule.ts → packages/alfa-rules/src/sia-dr6/rule.ts
@@ -15,10 +15,15 @@ const { hasAttribute, isDocumentElement } = Element;
 const { isEmpty } = Iterable;
 const { and, not, tee, test } = Predicate;
 
+/**
+ * @deprecated
+ * This rule has been deprecated because `xml:lang` attribute are not used
+ * anymore.
+ */
 export default Rule.Atomic.of<Page, Element>({
   uri: "https://alfa.siteimprove.com/rules/sia-r6",
   requirements: [Criterion.of("3.1.1")],
-  tags: [Scope.Page, Stability.Stable],
+  tags: [Scope.Page, Stability.Deprecated],
   evaluate({ document }) {
     // These will be set at most once since the rule only applies to the document element
     let cachedLang: Language;

diff --git a/...ages/alfa-rules/test/sia-r6/rule.spec.tsx → ...ges/alfa-rules/test/sia-dr6/rule.spec.tsx b/...ages/alfa-rules/test/sia-r6/rule.spec.tsx → ...ges/alfa-rules/test/sia-dr6/rule.spec.tsx
@@ -1,7 +1,7 @@
 import { h } from "@siteimprove/alfa-dom";
 import { test } from "@siteimprove/alfa-test";
 
-import R6, { Outcomes } from "../../src/sia-r6/rule";
+import R6, { Outcomes } from "../../src/sia-dr6/rule";
 
 import { evaluate } from "../common/evaluate";
 import { passed, failed, inapplicable } from "../common/outcome";

diff --git a/packages/alfa-rules/tsconfig.json b/packages/alfa-rules/tsconfig.json
@@ -48,6 +48,7 @@
     "src/experimental.ts",
     "src/index.ts",
     "src/rules.ts",
+    "src/sia-dr6/rule.ts",
     "src/sia-dr18/rule.ts",
     "src/sia-dr34/rule.ts",
     "src/sia-dr36/rule.ts",
@@ -104,7 +105,6 @@
     "src/sia-r56/rule.ts",
     "src/sia-r57/rule.ts",
     "src/sia-r59/rule.ts",
-    "src/sia-r6/rule.ts",
     "src/sia-r60/rule.ts",
     "src/sia-r61/rule.ts",
     "src/sia-r62/diagnostics.ts",
@@ -157,6 +157,7 @@
     "test/common/outcome.ts",
     "test/common/dom/get-colors.spec.tsx",
     "test/common/predicate/is-at-the-start.spec.tsx",
+    "test/sia-dr6/rule.spec.tsx",
     "test/sia-dr18/rule.spec.tsx",
     "test/sia-dr34/rule.spec.tsx",
     "test/sia-dr36/rule.spec.tsx",
@@ -168,7 +169,6 @@
     "test/sia-r3/rule.spec.tsx",
     "test/sia-r4/rule.spec.tsx",
     "test/sia-r5/rule.spec.tsx",
-    "test/sia-r6/rule.spec.tsx",
     "test/sia-r7/rule.spec.tsx",
     "test/sia-r8/rule.spec.tsx",
     "test/sia-r9/rule.spec.tsx",