Skip to content

Conversation

@alexstine
Copy link
Contributor

What?

This PR adds a new heading 3 to the PR template, "Testing Instructions for Keyboard".

Why?

It is my thinking that if users are forced to think about keyboard testing for user interface (UI) changes, some accessibility regressions could be prevented and new features could go out with fewer A11Y concerns. This also comes with the added benefit that it is more inclusive for everyone. Different people learn in different ways and also have different abilities. For example, someone may really benefit from being able to see the changes in a screenshot where I as a reviewer need to understand how I can test with my screen reader. This requires following a certain pattern on the keyboard that may not be obvious from the standard "Testing Instructions" heading 2 as they could be steps more geared towards sighted reviewers.

How?

A quick edit to the pull request template file.

Testing Instructions

Check the code diff. That is the best way for this. I will include the new sample template in a comment.

Screenshots or screencast

@alexstine alexstine added [Type] Enhancement A suggestion for improvement. [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Accessibility Feedback Need input from accessibility labels Nov 22, 2022
@alexstine alexstine self-assigned this Nov 22, 2022
@codesandbox
Copy link

codesandbox bot commented Nov 22, 2022

CodeSandbox logoCodeSandbox logo  Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

@alexstine
Copy link
Contributor Author

Raw:

<!-- Thanks for contributing to Gutenberg! Please follow the Gutenberg Contributing Guidelines:
https://github.com/WordPress/gutenberg/blob/trunk/CONTRIBUTING.md -->

## What?
<!-- In a few words, what is the PR actually doing? -->

## Why?
<!-- Why is this PR necessary? What problem is it solving? Reference any existing previous issue(s) or PR(s), but please add a short summary here, too -->

## How?
<!-- How is your PR addressing the issue at hand? What are the implementation details? -->

## Testing Instructions
<!-- Please include step by step instructions on how to test this PR. -->
<!-- 1. Open a Post or Page. -->
<!-- 2. Insert a Heading Block. -->
<!-- 3. etc. -->

### Testing Instructions for Keyboard
<!-- How can you test the changes by using the keyboard only? Please note, this is required for PRs that change the user interface (UI). This ensures the PR can be tested for any possible accessibility regressions. -->

## Screenshots or screencast <!-- if applicable -->

Rendered:

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Copy link
Contributor

@tellthemachines tellthemachines left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this PR! I'm happy to approve as-is, but also leaving an an alternative suggestion here: we could instead make it clear in the testing instructions comments that steps to test have to be keyboard accessible. The current approach with the separate heading might be easier to notice though, especially if folks are just skimming the headings, so let's try it out!

@alexstine
Copy link
Contributor Author

I left this open for a little while to see if it received additional feedback. I see some reactions, thanks @tellthemachines for the thoughts. Let's give it a try and see what people think and if PRs improve.

@alexstine alexstine merged commit 78699b3 into trunk Nov 30, 2022
@alexstine alexstine deleted the add/keyboard-instructions-pr-template branch November 30, 2022 05:50
@github-actions github-actions bot added this to the Gutenberg 14.7 milestone Nov 30, 2022
@noisysocks
Copy link
Member

I think it's a great idea to flag this as many people might not appreciate that testing instructions can be difficult to follow when using a keyboard. Can we include it all in the one Testing Instructions section though? Otherwise we're creeping back to having a long and arduous pull request template—the kind that we had before #39229.

@tellthemachines
Copy link
Contributor

I'm inclined to keep it like this for a little while to see how much of a difference it makes - my concern with including it in the Testing Instructions section is that folks will skim read and ignore it.

@alexstine
Copy link
Contributor Author

Kind of like that old accessibility checkbox. Everyone checked it, true or not. I was pushing for some accountability here. If you cannot test it with the keyboard, it likely does not belong in the project. That is my hard stance on A11Y.

mpkelly pushed a commit to mpkelly/gutenberg that referenced this pull request Dec 7, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Accessibility Feedback Need input from accessibility [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants