From 6061524b5cdf03ff1ae06bba22d4a6bb10a013d9 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Mon, 8 May 2023 15:04:44 +0200 Subject: [PATCH 1/3] add initial documentation for how to contribute to Backstage Accessibility Signed-off-by: Emma Indal --- CONTRIBUTING.md | 4 +++ docs/accessibility/index.md | 60 +++++++++++++++++++++++++++++++++++++ microsite/sidebars.json | 3 +- 3 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 docs/accessibility/index.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7828791080..f0658a3bc1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -99,3 +99,7 @@ This project adheres to the [Spotify FOSS Code of Conduct][code-of-conduct]. By ## Security Issues? See [SECURITY](SECURITY.md). + +## Accessibility + +We encourage you to catch any accessibility issues already in the development phase of new features to Backstage, see our [Accessibility documentation](./docs/accessibility/index.md) for more details. diff --git a/docs/accessibility/index.md b/docs/accessibility/index.md new file mode 100644 index 0000000000..c12fc76b91 --- /dev/null +++ b/docs/accessibility/index.md @@ -0,0 +1,60 @@ +--- +id: index +title: Backstage Accessibility +description: Documentation on Backstage Accessibility +--- + +In an effort to bake accessibility practices further into our process of building features for Backstage, we’ve rolled out automated CI tests to the OSS project on some of our core features, Software Catalog, Software Templates, Search and TechDocs. As these are just a few plugins of many out there, we want to encourage you to consider the accessibility implications of your work on Backstage in order to build a great experience for everyone. + +## How to contribute + +There are multiple ways to contribute to making Backstage accessible to everyone, below we list examples of some ways you can do that. + +### Run Lighthouse in CI on your plugin + +If your plugin lives in the [Backstage main repository](https://github.com/backstage/backstage/) you can modify the [urls in the Lighthouse config](https://github.com/backstage/backstage/blob/master/lighthouserc.js#L19-L34) to run the Lighthouse checks on urls where your plugin exists as well. E.g. + +```diff + ci: { + collect: { + url: [ ++ /** Your plugin paths */ ++ 'http://localhost:3000/your-plugin-path, + /** Software Catalog */ + 'http://localhost:3000/catalog', + 'http://localhost:3000/catalog-import', + 'http://localhost:3000/catalog/default/component/backstage', + ... + ], + settings: { + ... + }, + ... + }, + assert: { + ... + }, + }, +``` + +To make sure the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml) is running when changes are made to your plugin folders, also modify the [list of paths](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml#L7-L16). + +### Run the Lighthouse CLI locally when developing new features + +If you want to use the Lighthouse CLI and run the checks based on the config you can use the following command: + +``` +yarn dlx @lhci/cli@0.11.x autorun +``` + +> Note: running this command will use the [Lighthouse config](https://github.com/backstage/backstage/blob/master/lighthouserc.js#L19-L34) so make sure to adjust it to your needs if needed. + +### Use Lighthouse Github Action on your own repo + +If your Backstage plugin lives outside of the [Backstage main repository](https://github.com/backstage/backstage/), and you use Github Actions for continuous integration, we encourage you to add and modify the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml) to your needs. + +### Report identified issues + +It’s important to remember that the automated checks can just catch a very low number of accessibility issues, therefore we encourage you to do manual testing of your plugins using Assistive technology (e.g. Screen readers, alternative navigation, screen magnifiers, to mention a few) as well. + +If you have identified accessibility issues and don’t have time right now for a contribution, please open an issue over at [Backstage Issues](https://github.com/backstage/backstage/issues) to let us know. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index cf2f9b7b56..1515c483b9 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -408,6 +408,7 @@ "label": "Core Services", "items": ["backend-system/core-services/index"] } - ] + ], + "Accessibility": ["accessibility/index"] } } From 1d2932d97194db66a663e5a970c78fa8330718f5 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Mon, 8 May 2023 15:47:12 +0200 Subject: [PATCH 2/3] update links Signed-off-by: Emma Indal --- docs/accessibility/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/accessibility/index.md b/docs/accessibility/index.md index c12fc76b91..4d0c72761b 100644 --- a/docs/accessibility/index.md +++ b/docs/accessibility/index.md @@ -12,7 +12,7 @@ There are multiple ways to contribute to making Backstage accessible to everyone ### Run Lighthouse in CI on your plugin -If your plugin lives in the [Backstage main repository](https://github.com/backstage/backstage/) you can modify the [urls in the Lighthouse config](https://github.com/backstage/backstage/blob/master/lighthouserc.js#L19-L34) to run the Lighthouse checks on urls where your plugin exists as well. E.g. +If your plugin lives in the [Backstage main repository](https://github.com/backstage/backstage/) you can modify the [urls in the Lighthouse config](https://github.com/backstage/backstage/blob/39ba2284d73885b7ca8290cb38e2b1e4d983c8d6/lighthouserc.js#L19-L34) to run the Lighthouse checks on urls where your plugin exists as well. E.g. ```diff ci: { @@ -37,7 +37,7 @@ If your plugin lives in the [Backstage main repository](https://github.com/backs }, ``` -To make sure the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml) is running when changes are made to your plugin folders, also modify the [list of paths](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml#L7-L16). +To make sure the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) is running when changes are made to your plugin folders, also modify the [list of paths](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml#L7-L16). ### Run the Lighthouse CLI locally when developing new features @@ -47,11 +47,11 @@ If you want to use the Lighthouse CLI and run the checks based on the config you yarn dlx @lhci/cli@0.11.x autorun ``` -> Note: running this command will use the [Lighthouse config](https://github.com/backstage/backstage/blob/master/lighthouserc.js#L19-L34) so make sure to adjust it to your needs if needed. +> Note: running this command will use the [Lighthouse config](https://github.com/backstage/backstage/blob/39ba2284d73885b7ca8290cb38e2b1e4d983c8d6/lighthouserc.js#L19-L34) so make sure to adjust it to your needs if needed. ### Use Lighthouse Github Action on your own repo -If your Backstage plugin lives outside of the [Backstage main repository](https://github.com/backstage/backstage/), and you use Github Actions for continuous integration, we encourage you to add and modify the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml) to your needs. +If your Backstage plugin lives outside of the [Backstage main repository](https://github.com/backstage/backstage/), and you use Github Actions for continuous integration, we encourage you to add and modify the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) to your needs. ### Report identified issues From 924b231f46ab2b3f376c27a28a8fd706e0e4b97d Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 9 May 2023 08:38:56 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Bailey Brooks Signed-off-by: Emma Indal --- docs/accessibility/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/accessibility/index.md b/docs/accessibility/index.md index 4d0c72761b..24685b95ce 100644 --- a/docs/accessibility/index.md +++ b/docs/accessibility/index.md @@ -4,11 +4,11 @@ title: Backstage Accessibility description: Documentation on Backstage Accessibility --- -In an effort to bake accessibility practices further into our process of building features for Backstage, we’ve rolled out automated CI tests to the OSS project on some of our core features, Software Catalog, Software Templates, Search and TechDocs. As these are just a few plugins of many out there, we want to encourage you to consider the accessibility implications of your work on Backstage in order to build a great experience for everyone. +In an effort to bake accessibility practices further into our process of building features for Backstage, we support automated CI tests for some of our core features in the OSS project: Software Catalog, Software Templates, Search, and TechDocs. As these are just a few of the many plugins out there, we encourage you to consider the accessibility implications of your work on Backstage in order to build a great experience for everyone. ## How to contribute -There are multiple ways to contribute to making Backstage accessible to everyone, below we list examples of some ways you can do that. +There are multiple ways to contribute to making Backstage more accessible, you'll find below a list of examples to help you get started. ### Run Lighthouse in CI on your plugin @@ -37,7 +37,7 @@ If your plugin lives in the [Backstage main repository](https://github.com/backs }, ``` -To make sure the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) is running when changes are made to your plugin folders, also modify the [list of paths](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml#L7-L16). +To make sure the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) is running when changes are made to your plugin folders, modify the [list of paths](https://github.com/backstage/backstage/blob/10759b6ad2561bd86183ad940256f9a309c7a6b0/.github/workflows/verify_accessibility.yml#L7-L16). ### Run the Lighthouse CLI locally when developing new features @@ -51,10 +51,10 @@ yarn dlx @lhci/cli@0.11.x autorun ### Use Lighthouse Github Action on your own repo -If your Backstage plugin lives outside of the [Backstage main repository](https://github.com/backstage/backstage/), and you use Github Actions for continuous integration, we encourage you to add and modify the [Accessibility Github workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) to your needs. +If your Backstage plugin lives outside of the [Backstage main repository](https://github.com/backstage/backstage/), and you use GitHub Actions for continuous integration, we encourage you to add and modify the [Accessibility GitHub workflow](https://github.com/backstage/backstage/blob/master/.github/workflows/verify_accessibility.yml) to your needs. ### Report identified issues -It’s important to remember that the automated checks can just catch a very low number of accessibility issues, therefore we encourage you to do manual testing of your plugins using Assistive technology (e.g. Screen readers, alternative navigation, screen magnifiers, to mention a few) as well. +It’s important to remember that automated checks can only catch a small number of accessibility issues, therefore we also encourage you to conduct manual testing of your plugins using Assistive technology (screen readers, alternative navigation, and screen magnifiers are a few examples). -If you have identified accessibility issues and don’t have time right now for a contribution, please open an issue over at [Backstage Issues](https://github.com/backstage/backstage/issues) to let us know. +If you have identified accessibility issues and don’t have time to contribute a fix, please open an issue over at [Backstage Issues](https://github.com/backstage/backstage/issues) to let us know.