Enforce heading sentence case throughout the BEH (#57143)

* Enforce heading sentence case. * Linting * Update title and remove unnecessary TOC * Update docs/how-to-guides/README.md Co-authored-by: Aki Hamano <[email protected]> * Update docs/reference-guides/richtext.md Co-authored-by: Aki Hamano <[email protected]> * Update docs/explanations/user-interface/block-design.md Co-authored-by: Aki Hamano <[email protected]> * Update docs/how-to-guides/internationalization.md Co-authored-by: Aki Hamano <[email protected]> --------- Co-authored-by: Aki Hamano <[email protected]>
WordPress · Dec 18, 2023 · 1f42ec7 · 1f42ec7
1 parent 22bad55
commit 1f42ec7
Show file tree

Hide file tree

Showing 49 changed files with 193 additions and 215 deletions.
diff --git a/docs/contributors/README.md b/docs/contributors/README.md
@@ -18,7 +18,7 @@ Find the section below based on what you are looking to contribute:
 
 -   **Internationalization?** See the [localizing and translating section](/docs/contributors/localizing.md)
 
-### Repository Management
+### Repository management
 
 The Gutenberg project uses GitHub for managing code and tracking issues. Please see the following sections for the project methodologies using GitHub.
 

diff --git a/docs/contributors/accessibility-testing.md b/docs/contributors/accessibility-testing.md
@@ -2,11 +2,11 @@
 
 This is a guide on how to test accessibility on Gutenberg. This is a living document that can be improved over time with new approaches and techniques.
 
-## Getting Started
+## Getting started
 
 Make sure you have set up your local environment following the instructions on [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md).
 
-## Keyboard Testing
+## Keyboard testing
 
 In addition to mouse, make sure the interface is fully accessible for keyboard-only users. Try to interact with your changes using only the keyboard:
 
@@ -18,7 +18,7 @@ If the elements can be focused using arrow keys, but not <kbd>Tab</kbd> or <kbd>
 
 If the interaction is complex or confusing to you, consider that it's also going to impact keyboard-only users.
 
-## Screen Reader Testing
+## Screen reader testing
 
 According to the [WebAIM: Screen Reader User Survey #8 Results](https://webaim.org/projects/screenreadersurvey8/#usage), these are the most common screen reader and browser combinations:
 

diff --git a/docs/contributors/code/README.md b/docs/contributors/code/README.md
@@ -14,7 +14,7 @@ The Gutenberg project uses GitHub for managing code and tracking issues. The mai
 
 Browse [the issues list](https://github.com/wordpress/gutenberg/issues) to find issues to work on. The [good first issue](https://github.com/wordpress/gutenberg/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22) and [good first review](https://github.com/WordPress/gutenberg/pulls?q=is%3Aopen+is%3Apr+label%3A%22Good+First+Review%22) labels are good starting points.
 
-## Contributor Resources
+## Contributor resources
 
 -   [Getting Started](/docs/contributors/code/getting-started-with-code-contribution.md) documents getting your development environment setup, this includes your test site and developer tools suggestions.
 -   [Git Workflow](/docs/contributors/code/git-workflow.md) documents the git process for deploying changes using pull requests.

diff --git a/docs/contributors/code/backward-compatibility.md b/docs/contributors/code/backward-compatibility.md
@@ -61,7 +61,7 @@ deprecated( 'wp.components.ClipboardButton', {
 } );
 ```
 
-## Dev Notes
+## Dev notes
 
 Dev notes are [posts published on the make/core site](https://make.wordpress.org/core/tag/dev-notes/) prior to WordPress releases to inform third-party developers about important changes to the developer APIs, these changes can include:
 
@@ -70,7 +70,7 @@ Dev notes are [posts published on the make/core site](https://make.wordpress.org
 -   Unavoidable backward compatibility breakage, with reasoning and migration flows.
 -   Important deprecations (even without breakage), with reasoning and migration flows.
 
-### Dev Note Workflow
+### Dev note workflow
 
 -   When working on a pull request and the need for a dev note is discovered, add the **Needs Dev Note** label to the PR.
 -   If possible, add a comment to the PR explaining why the dev note is needed.

diff --git a/docs/contributors/code/coding-guidelines.md b/docs/contributors/code/coding-guidelines.md
@@ -55,7 +55,7 @@ export default function Notice( { children, onRemove, isDismissible } ) {
 
 A component's class name should **never** be used outside its own folder (with rare exceptions such as [`_z-index.scss`](https://github.com/WordPress/gutenberg/blob/HEAD/packages/base-styles/_z-index.scss)). If you need to inherit styles of another component in your own components, you should render an instance of that other component. At worst, you should duplicate the styles within your own component's stylesheet. This is intended to improve maintainability by isolating shared components as a reusable interface, reducing the surface area of similar UI elements by adapting a limited set of common components to support a varied set of use-cases.
 
-#### SCSS File Naming Conventions for Blocks
+#### SCSS file naming conventions for blocks
 
 The build process will split SCSS from within the blocks library directory into two separate CSS files when Webpack runs.
 
@@ -75,7 +75,7 @@ In the Gutenberg project, we use [the ES2015 import syntax](https://developer.mo
 
 These separations are identified by multi-line comments at the top of a file which imports code from another file or source.
 
-#### External Dependencies
+#### External dependencies
 
 An external dependency is third-party code that is not maintained by WordPress contributors, but instead [included in WordPress as a default script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/#default-scripts-included-and-registered-by-wordpress) or referenced from an outside package manager like [npm](https://www.npmjs.com/).
 
@@ -88,7 +88,7 @@ Example:
 import moment from 'moment';
 ```
 
-#### WordPress Dependencies
+#### WordPress dependencies
 
 To encourage reusability between features, our JavaScript is split into domain-specific modules which [`export`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) one or more functions or objects. In the Gutenberg project, we've distinguished these modules under top-level directories. Each module serve an independent purpose, and often code is shared between them. For example, in order to localize its text, editor code will need to include functions from the `i18n` module.
 
@@ -101,7 +101,7 @@ Example:
 import { __ } from '@wordpress/i18n';
 ```
 
-#### Internal Dependencies
+#### Internal dependencies
 
 Within a specific feature, code is organized into separate files and folders. As is the case with external and WordPress dependencies, you can bring this code into scope by using the `import` keyword. The main distinction here is that when importing internal files, you should use relative paths specific to top-level directory you're working in.
 
@@ -114,9 +114,9 @@ Example:
 import VisualEditor from '../visual-editor';
 ```
 
-### Legacy Experimental APIs, Plugin-only APIs, and Private APIs
+### Legacy experimental APIs, plugin-only APIs, and private APIs
 
-#### Legacy Experimental APIs
+#### Legacy experimental APIs
 
 Historically, Gutenberg has used the `__experimental` and `__unstable` prefixes to indicate that a given API is not yet stable and may be subject to change. This is a legacy convention which should be avoided in favor of the plugin-only API pattern or a private API pattern described below.
 
@@ -352,7 +352,7 @@ const { privateValidateBlocks } = unlock( package1PrivateApis );
 privateValidateBlocks( blocks, true );
 ```
 
-#### Private React Component properties
+#### Private React component properties
 
 To add an private argument to a stable component you'll need
 to prepare a stable and an private version of that component.
@@ -517,7 +517,7 @@ alert( 'My name is ' + name + '.' );
 alert( `My name is ${ name }.` );
 ```
 
-### Optional Chaining
+### Optional chaining
 
 [Optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) is a new language feature introduced in version 2020 of the ECMAScript specification. While the feature can be very convenient for property access on objects which are potentially null-ish (`null` or `undefined`), there are a number of common pitfalls to be aware of when using optional chaining. These may be issues that linting and/or type-checking can help protect against at some point in the future. In the meantime, you will want to be cautious of the following items:
 
@@ -529,11 +529,11 @@ alert( `My name is ${ name }.` );
     -   Example: `document.body.classList.toggle( 'has-focus', nodeRef.current?.contains( document.activeElement ) );` may wrongly _add_ the class, since [the second argument is optional](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle). If `undefined` is passed, it would not unset the class as it would when `false` is passed.
     -   Example: `<input value={ state.selected?.value.trim() } />` may inadvertently cause warnings in React by toggling between [controlled and uncontrolled inputs](https://reactjs.org/docs/uncontrolled-components.html). This is an easy trap to fall into when eagerly assuming that a result of `trim()` will always return a string value, overlooking the fact the optional chaining may have caused evaluation to abort earlier with a value of `undefined`.
 
-### React Components
+### React components
 
 It is preferred to implement all components as [function components](https://reactjs.org/docs/components-and-props.html), using [hooks](https://reactjs.org/docs/hooks-reference.html) to manage component state and lifecycle. With the exception of [error boundaries](https://reactjs.org/docs/error-boundaries.html), you should never encounter a situation where you must use a class component. Note that the [WordPress guidance on Code Refactoring](https://make.wordpress.org/core/handbook/contribute/code-refactoring/) applies here: There needn't be a concentrated effort to update class components in bulk. Instead, consider it as a good refactoring opportunity in combination with some other change.
 
-## JavaScript Documentation using JSDoc
+## JavaScript documentation using JSDoc
 
 Gutenberg follows the [WordPress JavaScript Documentation Standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/), with additional guidelines relevant for its distinct use of [import semantics](/docs/contributors/code/coding-guidelines.md#imports) in organizing files, the [use of TypeScript tooling](/docs/contributors/code/testing-overview.md#javascript-testing) for types validation, and automated documentation generation using [`@wordpress/docgen`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/docgen).
 
@@ -542,7 +542,7 @@ For additional guidance, consult the following resources:
 -   [JSDoc Official Documentation](https://jsdoc.app/index.html)
 -   [TypeScript Supported JSDoc](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html)
 
-### Custom Types
+### Custom types
 
 Define custom types using the [JSDoc `@typedef` tag](https://jsdoc.app/tags-typedef.html).
 
@@ -577,7 +577,7 @@ Custom types can also be used to describe a set of predefined options. While the
 
 Note the use of quotes when defining a set of string literals. As in the [JavaScript Coding Standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/), single quotes should be used when assigning a string literal either as the type or as a [default function parameter](#nullable-undefined-and-void-types), or when [specifying the path](#importing-and-exporting-types) of an imported type.
 
-### Importing and Exporting Types
+### Importing and exporting types
 
 Use the [TypeScript `import` function](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#import-types) to import type declarations from other files or third-party dependencies.
 
@@ -599,7 +599,7 @@ When considering which types should be made available from a WordPress package,
 
 In this snippet, the `@typedef` will support the usage of the previous example's `import('@wordpress/data')`.
 
-#### External Dependencies
+#### External dependencies
 
 Many third-party dependencies will distribute their own TypeScript typings. For these, the `import` semantics should "just work".
 
@@ -609,7 +609,7 @@ If you use a [TypeScript integration](https://github.com/Microsoft/TypeScript/wi
 
 For packages which do not distribute their own TypeScript types, you are welcomed to install and use the [DefinitelyTyped](http://definitelytyped.org/) community-maintained types definitions, if one exists.
 
-### Generic Types
+### Generic types
 
 When documenting a generic type such as `Object`, `Function`, `Promise`, etc., always include details about the expected record types.
 
@@ -659,7 +659,7 @@ Similar to the "Custom Types" advice concerning type unions and with literal val
 const BREAKPOINTS = { huge: 1440 /* , ... */ };
 ```
 
-### Nullable, Undefined, and Void Types
+### Nullable, undefined, and void types
 
 You can express a nullable type using a leading `?`. Use the nullable form of a type only if you're describing either the type or an explicit `null` value. Do not use the nullable form as an indicator of an optional parameter.
 
@@ -731,7 +731,7 @@ When documenting a [function type](https://github.com/WordPress/gutenberg/blob/a
  */
 ```
 
-### Documenting Examples
+### Documenting examples
 
 Because the documentation generated using the `@wordpress/docgen` tool will include `@example` tags if they are defined, it is considered a best practice to include usage examples for functions and components. This is especially important for documented members of a package's public API.
 
@@ -756,7 +756,7 @@ When documenting an example, use the markdown <code>\`\`\`</code> code block to
  */
 ````
 
-### Documenting React Components
+### Documenting React components
 
 When possible, all components should be implemented as [function components](https://reactjs.org/docs/components-and-props.html#function-and-class-components), using [hooks](https://reactjs.org/docs/hooks-intro.html) for managing component lifecycle and state.
 

diff --git a/docs/contributors/code/getting-started-with-code-contribution.md b/docs/contributors/code/getting-started-with-code-contribution.md
@@ -183,7 +183,7 @@ If so, you need to instruct Apache to allow following such links:
 
 Tools like MAMP tend to configure MySQL to use ports other than the default 3306, often preferring 8889. This may throw off WP-CLI, which will fail after trying to connect to the database. To remedy this, edit `wp-config.php` and change the `DB_HOST` constant from `define( 'DB_HOST', 'localhost' )` to `define( 'DB_HOST', '127.0.0.1:8889' )`.
 
-### On A Remote Server
+### On a remote server
 
 You can use a remote server in development by building locally and then uploading the built files as a plugin to the remote server.
 
@@ -203,7 +203,7 @@ You can launch Storybook by running `npm run storybook:dev` locally. It will ope
 
 You can also test Storybook for the current `trunk` branch on GitHub Pages: [https://wordpress.github.io/gutenberg/](https://wordpress.github.io/gutenberg/)
 
-## Developer Tools
+## Developer tools
 
 We recommend configuring your editor to automatically check for syntax and lint errors. This will help you save time as you develop by automatically fixing minor formatting issues. Here are some directions for setting up Visual Studio Code, a popular editor used by many of the core developers, these tools are also available for other editors.
 

diff --git a/docs/contributors/code/git-workflow.md b/docs/contributors/code/git-workflow.md
@@ -73,7 +73,7 @@ Do not make a new pull request for updates; by pushing your change to your repos
 
 That’s it! Once approved and merged, your change will be incorporated into the main repository. 🎉
 
-## Branch Naming
+## Branch naming
 
 You should name your branches using a prefixes and short description, like this: `[type]/[change]`.
 
@@ -87,7 +87,7 @@ Suggested prefixes:
 
 For example, `add/gallery-block` means you're working on adding a new gallery block.
 
-## Keeping Your Branch Up To Date
+## Keeping your branch up to date
 
 When many different people are working on a project simultaneously, pull requests can go stale quickly. A "stale" pull request is one that is no longer up to date with the main line of development, and it needs to be updated before it can be merged into the project.
 
@@ -105,7 +105,7 @@ git rebase trunk
 git push --force-with-lease origin your-branch-name
 ```
 
-## Keeping Your Fork Up To Date
+## Keeping your fork up to date
 
 Working on pull request starts with forking the Gutenberg repository, your separate working copy. Which can easily go out of sync as new pull requests are merged into the main repository. Here your working repository is a `fork` and the main Gutenberg repository is `upstream`. When working on new pull request you should always update your fork before you do `git checkout -b my-new-branch` to work on a feature or fix.
 
@@ -138,7 +138,7 @@ The above commands will update your `trunk` branch from _upstream_. To update an
 
 ## Miscellaneous
 
-### Git Archeology
+### Git archeology
 
 When looking for a commit that introduced a specific change, it might be helpful to ignore revisions that only contain styling or formatting changes.
 

diff --git a/docs/contributors/code/react-native/getting-started-react-native.md b/docs/contributors/code/react-native/getting-started-react-native.md
@@ -55,7 +55,7 @@ npm run native ios
 
 which will attempt to open your app in the iOS Simulator if you're on a Mac and have it installed.
 
-### Running on Other iOS Device Simulators
+### Running on other iOS device simulators
 
 To compile and run the app using a different device simulator, use the following, noting the double sets of `--` to pass the simulator option down to the `react-native` CLI.
 
@@ -71,7 +71,7 @@ npm run native ios -- -- --simulator="iPhone Xs Max"
 
 To see a list of all of your available iOS devices, use `xcrun simctl list devices`.
 
-### Customizing the Demo Editor
+### Customizing the demo Editor
 
 By default, the Demo editor renders most of the supported core blocks. This is helpful to showcase the editor's capabilities, but can be distracting when focusing on a specific block or feature. One can customize the editor's initial state by leveraging the `native.block_editor_props` hook in a `packages/react-native-editor/src/setup-local.js` file.
 
@@ -119,7 +119,7 @@ When you first open the project in Visual Studio, you will be prompted to instal
 
 One of the extensions we are using is the [React Native Tools](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native). This allows you to run the packager from VSCode or launch the application on iOS or Android. It also adds some debug configurations so you can set breakpoints and debug the application directly from VSCode. Take a look at the [extension documentation](https://marketplace.visualstudio.com/items?itemName=vsmobile.vscode-react-native) for more details.
 
-## Unit Tests
+## Unit tests
 
 Use the following command to run the test suite:
 
@@ -137,11 +137,11 @@ npm run test:native:debug
 
 Then, open `chrome://inspect` in Chrome to attach the debugger (look into the "Remote Target" section). While testing/developing, feel free to sprinkle `debugger` statements anywhere in the code that you'd like the debugger to break.
 
-## Writing and Running Unit Tests
+## Writing and running unit tests
 
 This project is set up to use [jest](https://jestjs.io/) for tests. You can configure whatever testing strategy you like, but jest works out of the box. Create test files in directories called `__tests__` or with the `.test.js` extension to have the files loaded by jest. See an example test [here](https://github.com/WordPress/gutenberg/blob/HEAD/packages/react-native-editor/src/test/api-fetch-setup.test.js). The [jest documentation](https://jestjs.io/docs/getting-started) is also a wonderful resource, as is the [React Native testing tutorial](https://jestjs.io/docs/tutorial-react-native).
 
-## End-to-End Tests
+## End-to-end tests
 
 In addition to unit tests, the Mobile Gutenberg (MG) project relies upon end-to-end (E2E) tests to automate testing critical flows in an environment similar to that of an end user. We generally prefer unit tests due to their speed and ease of maintenance. However, assertions that require OS-level features (e.g. complex gestures, text selection) or visual regression testing (e.g. dark mode, contrast levels) we use E2E tests.