Merge branch 'docs-aqualls-cleanup2' into 'master'

Re-flow note boxes back into body text

See merge request gitlab-org/gitlab!46834

doc/development/adding_service_component.md

@@ -59,10 +59,8 @@ TIP: **Tip:**
 
 ## Bundling a service with GitLab
 
-NOTE: **Note:**
 Code shipped with GitLab needs to use a license approved by the Legal team. See the list of [existing approved licenses](https://about.gitlab.com/handbook/engineering/open-source/#using-open-source-libraries).
 
-NOTE: **Note:**
 Notify the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/) when adding a new dependency that must be compiled. We must be able to compile the dependency on all supported platforms.
 
 New services to be bundled with GitLab need to be available in the following environments.

doc/development/approval_rules.md

@@ -20,7 +20,7 @@ feature to work.
 
 NOTE: **Note:**
 This is a living document and should be updated accordingly when parts
-of the codebase touched in this document changed/removed or when new components
+of the codebase touched in this document are changed or removed, or when new components
 are added.
 
 ## Data Model

doc/development/diffs.md

@@ -99,7 +99,6 @@ Gitlab::Git::DiffCollection.collection_limits[:max_bytes] = Gitlab::Git::DiffCol
 
 No more files will be rendered at all if 5 megabytes have already been rendered.
 
-NOTE: **Note:**
 All collection limit parameters are currently sent and applied on Gitaly. That is, once the limit is surpassed,
 Gitaly will only return the safe amount of data to be persisted on `merge_request_diff_files`.
 
@@ -114,7 +113,6 @@ That is, it's equivalent to 10kb if the maximum allowed value is 100kb.
 The diff will still be persisted and expandable if the patch size doesn't
 surpass `ApplicationSettings#diff_max_patch_bytes`.
 
-NOTE: **Note:**
 Although this nomenclature (Collapsing) is also used on Gitaly, this limit is only used on GitLab (hardcoded - not sent to Gitaly).
 Gitaly will only return `Diff.Collapsed` (RPC) when surpassing collection limits.
 
@@ -129,7 +127,6 @@ Commit::DIFF_SAFE_LINES = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines
 
 File diff will be suppressed (technically different from collapsed, but behaves the same, and is expandable) if it has more than 5000 lines.
 
-NOTE: **Note:**
 This limit is currently hardcoded and only applied on GitLab.
 
 ## Viewers

doc/development/fe_guide/editor_lite.md

@@ -58,7 +58,7 @@ The editor follows the same public API as [provided by Monaco editor](https://mi
 | Function | Arguments | Description
 | ----- | ----- | ----- |
 | `updateModelLanguage` | `path`: String | Updates the instance's syntax highlighting to follow the extension of the passed `path`. Available only on _instance_ level|
-| `use` | Array of objects | Array of **extensions** to apply to the instance. Note: `use` accepts only the array of _objects_, which means that the extensions' ES6 modules should be fetched and resolved in your views/components before being passed to `use`. This prop is available on _instance_ (applies extension to this particular instance) and _global edtor_ (applies the same extension to all instances) levels. |
+| `use` | Array of objects | Array of **extensions** to apply to the instance. Accepts only the array of _objects_, which means that the extensions' ES6 modules should be fetched and resolved in your views/components before being passed to `use`. This prop is available on _instance_ (applies extension to this particular instance) and _global edtor_ (applies the same extension to all instances) levels. |
 | Monaco Editor options | See [documentation](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.istandalonecodeeditor.html) | Default Monaco editor options |
 
 ## Tips

doc/development/fe_guide/frontend_faq.md

@@ -180,10 +180,9 @@ which adds the appropriate `core-js` polyfills once for each JavaScript feature
 we're using that our target browsers don't support. You don't need to add `core-js`
 polyfills manually.
 
-NOTE: **Note:**
-GitLab still manually adds non-`core-js` polyfills for extending browser features
-(such as GitLab's SVG polyfill) that allow us reference SVGs by using `<use xlink:href>`.
-These polyfills should be added to `app/assets/javascripts/commons/polyfills.js`.
+GitLab adds non-`core-js` polyfills for extending browser features (such as
+GitLab's SVG polyfill), which allow us to reference SVGs by using `<use xlink:href>`.
+Be sure to add these polyfills to `app/assets/javascripts/commons/polyfills.js`.
 
 To see what polyfills are being used:
 

doc/development/fe_guide/graphql.md

@@ -741,8 +741,8 @@ describe('Some component with Apollo mock', () => {
 })
 ```
 
-NOTE: **Note:**
-When mocking resolved values, make sure the structure of the response is the same as actual API response: i.e. root property should be `data` for example
+When mocking resolved values, ensure the structure of the response is the same
+as the actual API response. For example, root property should be `data`.
 
 When testing queries, please keep in mind they are promises, so they need to be _resolved_ to render a result. Without resolving, we can check the `loading` state of the query:
 

doc/development/fe_guide/performance.md

@@ -77,9 +77,8 @@ controller with the `index` action. If a corresponding file exists at
 `pages/projects/issues/index/index.js`, it will be compiled into a webpack
 bundle and included on the page.
 
-NOTE: **Note:**
-Previously we had encouraged the use of
-`content_for :page_specific_javascripts` within haml files, along with
+Previously, GitLab encouraged the use of
+`content_for :page_specific_javascripts` within HAML files, along with
 manually generated webpack bundles. However under this new system you should
 not ever need to manually add an entry point to the `webpack.config.js` file.
 

doc/development/fe_guide/style/javascript.md

@@ -141,7 +141,7 @@ module.exports = SomeClass;
 export default SomeClass;
 ```
 
-_Note:_ We still use `require` in `scripts/` and `config/` files.
+We still use `require` in `scripts/` and `config/` files.
 
 ## Absolute vs relative paths for modules
 

doc/development/fe_guide/style/vue.md

@@ -190,7 +190,7 @@ Please check this [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules)
    ```
 
 1. Default key should be provided if the prop is not required.
-   _Note:_ There are some scenarios where we need to check for the existence of the property.
+   There are some scenarios where we need to check for the existence of the property.
    On those a default key should not be provided.
 
    ```javascript
@@ -409,7 +409,7 @@ Useful links:
 ## Vue testing
 
 Over time, a number of programming patterns and style preferences have emerged in our efforts to effectively test Vue components.
-The following guide describes some of these. **These are not strict guidelines**, but rather a collection of suggestions and 
+The following guide describes some of these. **These are not strict guidelines**, but rather a collection of suggestions and
 good practices that aim to provide insight into how we write Vue tests at GitLab.
 
 ### Mounting a component
@@ -425,7 +425,7 @@ To achieve this:
 Creating a global, mutable wrapper provides a number of advantages, including the ability to:
 
 - Define common functions for finding components/DOM elements:
-  
+
   ```javascript
   import MyComponent from '~/path/to/my_component.vue';
   describe('MyComponent', () => {
@@ -533,8 +533,8 @@ the mounting function (`mount` or `shallowMount`) to be used to mount the compon
 
 ### Setting component state
 
-1. Avoid using [`setProps`](https://vue-test-utils.vuejs.org/api/wrapper/#setprops) to set 
-component state wherever possible. Instead, set the component's 
+1. Avoid using [`setProps`](https://vue-test-utils.vuejs.org/api/wrapper/#setprops) to set
+component state wherever possible. Instead, set the component's
 [`propsData`](https://vue-test-utils.vuejs.org/api/options.html#propsdata) when mounting the component:
 
     ```javascript

doc/development/fe_guide/tooling.md

@@ -20,7 +20,7 @@ To check all currently staged files (based on `git diff`) with ESLint, run the f
 yarn eslint-staged
 ```
 
-_A list of problems found will be logged to the console._
+A list of problems found will be logged to the console.
 
 To apply automatic ESLint fixes to all currently staged files (based on `git diff`), run the following script:
 
@@ -28,7 +28,7 @@ To apply automatic ESLint fixes to all currently staged files (based on `git dif
 yarn eslint-staged-fix
 ```
 
-_If manual changes are required, a list of changes will be sent to the console._
+If manual changes are required, a list of changes will be sent to the console.
 
 To check **all** files in the repository with ESLint, run the following script:
 
@@ -36,7 +36,7 @@ To check **all** files in the repository with ESLint, run the following script:
 yarn eslint
 ```
 
-_A list of problems found will be logged to the console._
+A list of problems found will be logged to the console.
 
 To apply automatic ESLint fixes to **all** files in the repository, run the following script:
 
@@ -44,7 +44,7 @@ To apply automatic ESLint fixes to **all** files in the repository, run the foll
 yarn eslint-fix
 ```
 
-_If manual changes are required, a list of changes will be sent to the console._
+If manual changes are required, a list of changes will be sent to the console.
 
 CAUTION: **Caution:**
 Limit use to global rule updates. Otherwise, the changes can lead to huge Merge Requests.
@@ -60,9 +60,8 @@ rules only if you are invoking/instantiating existing code modules.
 - [`no-new`](https://eslint.org/docs/rules/no-new)
 - [`class-method-use-this`](https://eslint.org/docs/rules/class-methods-use-this)
 
-NOTE: **Note:**
-Disable these rules on a per-line basis. This makes it easier to refactor
-in the future. E.g. use `eslint-disable-next-line` or `eslint-disable-line`.
+Disable these rules on a per-line basis. This makes it easier to refactor in the
+future. For example, use `eslint-disable-next-line` or `eslint-disable-line`.
 
 ### Disabling ESLint for a single violation
 

doc/development/fe_guide/vue.md

@@ -62,7 +62,7 @@ Be sure to read about [page-specific JavaScript](./performance.md#page-specific-
 While mounting a Vue application, you might need to provide data from Rails to JavaScript.
 To do that, you can use the `data` attributes in the HTML element and query them while mounting the application.
 
-_Note:_ You should only do this while initializing the application, because the mounted element will be replaced with Vue-generated DOM.
+You should only do this while initializing the application, because the mounted element will be replaced with Vue-generated DOM.
 
 The advantage of providing data from the DOM to the Vue instance through `props` in the `render` function
 instead of querying the DOM inside the main Vue component is avoiding the need to create a fixture or an HTML element in the unit test,
@@ -235,7 +235,7 @@ describe('~/todos/app.vue', () => {
     mock.restore();
   });
 
-  // NOTE: It is very helpful to separate setting up the component from
+  // It is very helpful to separate setting up the component from
   // its collaborators (i.e. Vuex, axios, etc.)
   const createWrapper = (props = {}) => {
     wrapper = shallowMount(App, {
@@ -245,7 +245,7 @@ describe('~/todos/app.vue', () => {
       },
     });
   };
-  // NOTE: Helper methods greatly help test maintainability and readability.
+  // Helper methods greatly help test maintainability and readability.
   const findLoader = () => wrapper.find(GlLoadingIcon);
   const findAddButton = () => wrapper.find('[data-testid="add-button"]');
   const findTextInput = () => wrapper.find('[data-testid="text-input"]');

doc/development/fe_guide/vue3_migration.md

@@ -82,7 +82,6 @@ const FunctionalComp = (props, slots) => {
 }
 ```
 
-NOTE: **Note:**
 It is not recommended to replace stateful components with functional components unless you absolutely need a performance improvement right now. In Vue 3, performance gains for functional components will be negligible.
 
 ## Old slots syntax with `slot` attribute

doc/development/fe_guide/vuex.md

@@ -15,14 +15,14 @@ Vuex should be strongly considered when:
 - There are complex interactions with Backend, e.g. multiple API calls
 - The app involves interacting with backend via both traditional REST API and GraphQL (especially when moving the REST API over to GraphQL is a pending backend task)
 
-_Note:_ All of the below is explained in more detail in the official [Vuex documentation](https://vuex.vuejs.org).
+The information included in this page is explained in more detail in the
+official [Vuex documentation](https://vuex.vuejs.org).
 
 ## Separation of concerns
 
 Vuex is composed of State, Getters, Mutations, Actions, and Modules.
 
-When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state.
-_Note:_ The action itself will not update the state, only a mutation should update the state.
+When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state. The action itself will not update the state; only a mutation should update the state.
 
 ## File structure
 
@@ -66,7 +66,7 @@ export const createStore = () =>
 
 The first thing you should do before writing any code is to design the state.
 
-Often we need to provide data from haml to our Vue application. Let's store it in the state for better access.
+Often we need to provide data from HAML to our Vue application. Let's store it in the state for better access.
 
 ```javascript
   export default () => ({

doc/development/i18n/externalization.md

@@ -21,7 +21,7 @@ All `rake` commands described on this page must be run on a GitLab instance, usu
 In order to be able to work on the [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss)
 project you must download and configure it through [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/set-up-gdk.md).
 
-Once you have the GitLab project ready, you can start working on the translation.
+After you have the GitLab project ready, you can start working on the translation.
 
 ## Tools
 
@@ -104,9 +104,8 @@ Active Record's `:message` option accepts a `Proc`, so we can do this instead:
 validates :group_id, uniqueness: { scope: [:project_id], message: -> (object, data) { _("already shared with this group") } }
 ```
 
-NOTE: **Note:**
 Messages in the API (`lib/api/` or `app/graphql`) do
-not need to be externalised.
+not need to be externalized.
 
 ### HAML files
 
@@ -385,8 +384,8 @@ Namespaces should be PascalCase.
   s__('OpenedNDaysAgo|Opened')
   ```
 
-Note: The namespace should be removed from the translation. See the [translation
-guidelines for more details](translation.md#namespaced-strings).
+The namespace should be removed from the translation. See the
+[translation guidelines for more details](translation.md#namespaced-strings).
 
 ### HTML
 

doc/development/i18n/proofreader.md

@@ -121,10 +121,8 @@ are very appreciative of the work done by translators and proofreaders!
 
 ## Become a proofreader
 
-NOTE: **Note:**
-Before requesting Proofreader permissions in CrowdIn please make
-sure that you have a history of contributing translations to the GitLab
-project.
+Before requesting Proofreader permissions in CrowdIn, be sure you have a history
+of contributing translations to the GitLab project.
 
 1. Contribute translations to GitLab. See instructions for
    [translating GitLab](translation.md).
@@ -146,8 +144,8 @@ project.
    - link to your GitLab profile
    - link to your CrowdIn profile
 
-   In the merge request description, please include links to any projects you
-   have previously translated.
+   In the merge request description, include links to any projects you have
+   previously translated.
 
 1. Your request to become a proofreader will be considered on the merits of
    your previous translations by [GitLab team members](https://about.gitlab.com/company/team/)

doc/development/new_fe_guide/development/accessibility.md

@@ -12,7 +12,7 @@ Using semantic HTML plays a key role when it comes to accessibility.
 
 WAI-ARIA (the Accessible Rich Internet Applications specification) defines a way to make Web content and Web applications more accessible to people with disabilities.
 
-> Note: It is [recommended](https://www.w3.org/TR/using-aria/#notes2) to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements.
+The W3C recommends [using semantic elements](https://www.w3.org/TR/using-aria/#notes2) as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements.
 
 ### Role
 

doc/development/query_recorder.md

@@ -26,7 +26,6 @@ end
 
 As an example you might create 5 issues in between counts, which would cause the query count to increase by 5 if an N+1 problem exists.
 
-NOTE: **Note:**
 In some cases the query count might change slightly between runs for unrelated reasons. In this case you might need to test `exceed_query_limit(control_count + acceptable_change)`, but this should be avoided if possible.
 
 ## Cached queries

doc/development/secure_coding_guidelines.md

@@ -219,11 +219,11 @@ the mitigations for a new feature.
 
 - [More details](https://dev.gitlab.org/gitlab/gitlabhq/-/merge_requests/2530/diffs)
 
-#### Feature-specific Mitigations
+#### Feature-specific mitigations
 
 For situations in which an allowlist or GitLab:HTTP cannot be used, it will be necessary to implement mitigations directly in the feature. It is best to validate the destination IP addresses themselves, not just domain names, as DNS can be controlled by the attacker. Below are a list of mitigations that should be implemented.
 
-**Important Note:** There are many tricks to bypass common SSRF validations. If feature-specific mitigations are necessary, they should be reviewed by the AppSec team, or a developer who has worked on SSRF mitigations previously.
+There are many tricks to bypass common SSRF validations. If feature-specific mitigations are necessary, they should be reviewed by the AppSec team, or a developer who has worked on SSRF mitigations previously.
 
 - Block connections to all localhost addresses
   - `127.0.0.1/8` (IPv4 - note the subnet mask)
@@ -429,9 +429,8 @@ The Path Traversal check can also be used to forbid any absolute path:
 requires :file_path, type: String, file_path: true
 ```
 
-NOTE: **Note:**
 Absolute paths are not allowed by default. If allowing an absolute path is required, you
-need to provide an array of paths to the parameter `allowlist`.  
+need to provide an array of paths to the parameter `allowlist`.
 
 ## OS command injection guidelines
 

doc/development/sidekiq_style_guide.md

@@ -118,7 +118,6 @@ As a general rule, a worker can be considered idempotent if:
 
 A good example of that would be a cache expiration worker.
 
-NOTE: **Note:**
 A job scheduled for an idempotent worker will automatically be
 [deduplicated](#deduplication) when an unstarted job with the same
 arguments is already in the queue.
@@ -158,7 +157,6 @@ end
 It's encouraged to only have the `idempotent!` call in the top-most worker class, even if
 the `perform` method is defined in another class or module.
 
-NOTE: **Note:**
 If the worker class is not marked as idempotent, a cop will fail.
 Consider skipping the cop if you're not confident your job can safely
 run multiple times.
@@ -484,9 +482,7 @@ class ExternalDependencyWorker
 end
 ```
 
-NOTE: **Note:**
-Note that a job cannot be both high urgency and have
-external dependencies.
+A job cannot be both high urgency and have external dependencies.
 
 ## CPU-bound and Memory-bound Workers
 

doc/development/testing_guide/best_practices.md

@@ -361,7 +361,7 @@ Finished in 34.51 seconds (files took 0.76702 seconds to load)
 1 example, 0 failures
 ```
 
-Note: `live_debug` only works on JavaScript enabled specs.
+`live_debug` only works on JavaScript enabled specs.
 
 #### Run `:js` spec in a visible browser
 
@@ -584,9 +584,9 @@ this trait should be either fixed to not rely on Sidekiq processing jobs, or the
 `:sidekiq_might_not_need_inline` trait should be updated to `:sidekiq_inline` if
 the processing of background jobs is needed/expected.
 
-NOTE: **Note:**
-The usage of `perform_enqueued_jobs` is only useful for testing delayed mail
-deliveries since our Sidekiq workers aren't inheriting from `ApplicationJob` / `ActiveJob::Base`.
+The usage of `perform_enqueued_jobs` is useful only for testing delayed mail
+deliveries, because our Sidekiq workers aren't inheriting from `ApplicationJob`
+/ `ActiveJob::Base`.
 
 #### DNS