Skip to content

docs(versioning): update docs to include landmark roles #3743

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joshblack merged 2 commits into from
Sep 15, 2023
Merged

docs(versioning): update docs to include landmark roles #3743

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8a18200
docs(versioning): update docs to include landmark roles
joshblack Sep 13, 2023
49ed88b
docs: update table with correct semver bump
joshblack Sep 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 56 additions & 16 deletions contributor-docs/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@
- [The type of a prop is broadened](#the-type-of-a-prop-is-broadened)
- [The type of a prop is narrowed](#the-type-of-a-prop-is-narrowed)
- [The `display` property used for the container of `children` is changed](#the-display-property-used-for-the-container-of-children-is-changed)
- [A component includes a landmark role](#a-component-includes-a-landmark-role)
- [A component no longer includes a landmark role](#a-component-no-longer-includes-a-landmark-role)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- prettier-ignore-end -->
Expand Down Expand Up @@ -40,22 +42,24 @@ For a full list of releases, visit our [releases](https://github.com/primer/reac

## Changes

| Category | Type of change | semver bump |
| :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
| Component | A component is added | `minor` |
| | A component is deprecated | `minor` |
| | A component is removed | `major` |
| Props | A prop is added | `minor` |
| | [The type of a prop is broadened](#the-type-of-a-prop-is-broadened) | `minor` |
| | [The type of a prop is narrowed](#the-type-of-a-prop-is-narrowed) | `major` |
| | A prop is deprecated | `minor` |
| | A prop is removed | `major` |
| Package | A dependency is added | `minor` |
| | A dependency is removed and it does not affect the public API of the package | `minor` |
| | A dependency is removed and it does affect the public API of the package | `major` |
| | The version of a dependency is increased to a newer minor or patch version | `minor` |
| | The version of a dependency is increased to a newer major version | `major` |
| CSS | [The `display` property used for the container of `children` is changed](#the-display-property-used-for-the-container-of-children-is-changed) | potentially `major` |
| Category | Type of change | semver bump |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
| Component | A component is added | `minor` |
| | A component is deprecated | `minor` |
| | A component is removed | `major` |
| Props | A prop is added | `minor` |
| | [The type of a prop is broadened](#the-type-of-a-prop-is-broadened) | `minor` |
| | [The type of a prop is narrowed](#the-type-of-a-prop-is-narrowed) | `major` |
| | A prop is deprecated | `minor` |
| | A prop is removed | `major` |
| Package | A dependency is added | `minor` |
| | A dependency is removed and it does not affect the public API of the package | `minor` |
| | A dependency is removed and it does affect the public API of the package | `major` |
| | The version of a dependency is increased to a newer minor or patch version | `minor` |
| | The version of a dependency is increased to a newer major version | `major` |
| CSS | [The `display` property used for the container of `children` is changed](#the-display-property-used-for-the-container-of-children-is-changed) | potentially `major` |
| Accessibility | [A component includes a landmark role](#a-component-includes-a-landmark-role) | potentially `major` |
| | [A component no longer includes a landmark role](#a-component-no-longer-includes-a-landmark-role) | potentially `major` |

## Reference

Expand Down Expand Up @@ -123,3 +127,39 @@ markup:
In this situation, changing the layout of the `button` to `flex` would collapse
the whitespace present between the text "Save" and "changes" and would be
considered a breaking change.

### A component includes a landmark role

semver bump: potentially **major**

The addition of certain [landmark](https://w3c.github.io/aria/#dfn-landmark) regions may be considered a breaking change. For example, if a component includes the `main` landmark role and another `main` element already exists then the product would violate the [`landmark-no-duplicate-main`](https://dequeuniversity.com/rules/axe/4.8/landmark-no-duplicate-main?product=RuleDescription) rule that is a part of axe.

The addition of other landmark roles may be permissible in a `minor` release if
and only if the component is uniquely identifiable from other landmarks of the
same role. This is typically done through an explicit label on the landmark or
through an element which labels the landmark.

| Role | semver bump | Description |
| :------------ | :------------------ | :----------------------------------------------------------------------------------------- |
| banner | potentially `major` | `major` if used as global site header, `minor` if used in sectioning elements |
| complementary | `minor` | |
| contentinfo | `major` | The implicit role of `<footer>`, there should only be one element with this role on a page |
| main | `major` | |
| navigation | potentially `major` | Should be used sparingly and must be uniquely labeled |
| region | `minor` | |
| search | `minor` | |

### A component no longer includes a landmark role

semver bump: potentially **major**

If a component that previously used a landmark role, there may be a breaking
change if that role is removed. Specifically, if a component specifies a `main`
landmark then removing that landmark role will cause products to fail
[`landmark-one-main`](https://dequeuniversity.com/rules/axe/4.8/landmark-one-main?product=RuleDescription) as they previously relied on this component to specify this landmark.

Generally, removing landmark roles will have a net impact on the accessibility
of products and should be treated carefully. In certain situations, it may
be possible to remove a landmark role that is superfluous in a `minor` release.
However, most cases should treat this as a breaking change and should draft a
migration plan accordingly for product teams.