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

Re-flow notes into body text

See merge request gitlab-org/gitlab!46835

doc/development/api_graphql_styleguide.md

@@ -689,7 +689,7 @@ end
 ```
 
 Fields can also be authorized against multiple abilities, in which case
-all of ability checks must pass. **Note:** This requires explicitly
+all of ability checks must pass. This requires explicitly
 passing a block to `field`:
 
 ```ruby
@@ -702,7 +702,6 @@ module Types
 end
 ```
 
-NOTE: **Note:**
 If the field's type already [has a particular
 authorization](#type-authorization) then there is no need to add that
 same authorization to the field.

doc/development/changelog.md

@@ -125,7 +125,6 @@ the `--ee` option:
 bin/changelog --ee 'Hey DZ, I added a feature to GitLab!'
 ```
 
-NOTE: **Note:**
 All entries in the `CHANGELOG.md` file apply to all editions of GitLab.
 Changelog updates are based on a common [GitLab codebase](https://gitlab.com/gitlab-org/gitlab/),
 and are mirrored without proprietary code to [GitLab FOSS](https://gitlab.com/gitlab-org/gitlab-foss/) (also known as GitLab Community Edition).

doc/development/chaos_endpoints.md

@@ -50,8 +50,7 @@ each endpoint can be set to `true`. This will run the chaos process in a Sidekiq
 
 To simulate a memory leak in your application, use the `/-/chaos/leakmem` endpoint.
 
-NOTE: **Note:**
-The memory is not retained after the request finishes. Once the request has completed, the Ruby garbage collector will attempt to recover the memory.
+The memory is not retained after the request finishes. After the request has completed, the Ruby garbage collector will attempt to recover the memory.
 
 ```plaintext
 GET /-/chaos/leakmem
@@ -145,8 +144,8 @@ curl http://localhost:3000/-/chaos/sleep?duration_s=60&token=secret
 
 This endpoint will simulate the unexpected death of a worker process using a `kill` signal.
 
-NOTE: **Note:**
-Since this endpoint uses the `KILL` signal, the worker is not given a chance to cleanup or shutdown.
+Because this endpoint uses the `KILL` signal, the worker isn't given an
+opportunity to cleanup or shutdown.
 
 ```plaintext
 GET /-/chaos/kill

doc/development/code_review.md

@@ -390,8 +390,7 @@ When ready to merge:
 - When you set the MR to "Merge When Pipeline Succeeds", you should take over
   subsequent revisions for anything that would be spotted after that.
 
-NOTE: **Note:**
-Thanks to "Pipeline for Merged Results", authors won't have to rebase their
+Thanks to **Pipeline for Merged Results**, authors won't have to rebase their
 branch as frequently anymore (only when there are conflicts) since the Merge
 Results Pipeline will already incorporate the latest changes from `master`.
 This results in faster review/merge cycles since maintainers don't have to ask

doc/development/distributed_tracing.md

@@ -186,7 +186,7 @@ variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Side
 
 ### 3. Start the GitLab application
 
-Once the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the
+After the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the
 application.
 
 When `GITLAB_TRACING` is configured properly, the application will log this on startup:

doc/development/import_project.md

@@ -23,7 +23,6 @@ The first option is to simply [import the Project tarball file via the GitLab UI
 
 It should take up to 15 minutes for the project to fully import. You can head to the project's main page for the current status.
 
-NOTE: **Note:**
 This method ignores all the errors silently (including the ones related to `GITALY_DISABLE_REQUEST_LIMITS`) and is used by GitLab's users. For development and testing, check the other methods below.
 
 ### Importing via the `import-project` script

doc/development/migration_style_guide.md

@@ -382,8 +382,7 @@ Example changes:
 - `change_column_default`
 - `create_table` / `drop_table`
 
-NOTE: **Note:**
-`with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible.
+The `with_lock_retries` method **cannot** be used within the `change` method, you must manually define the `up` and `down` methods to make the migration reversible.
 
 ### How the helper method works
 
@@ -443,7 +442,6 @@ the `with_multiple_threads` block, instead of re-using the global connection
 pool. This ensures each thread has its own connection object, and won't time
 out when trying to obtain one.
 
-NOTE: **Note:**
 PostgreSQL has a maximum amount of connections that it allows. This
 limit can vary from installation to installation. As a result, it's recommended
 you do not use more than 32 threads in a single migration. Usually, 4-8 threads
@@ -618,7 +616,6 @@ Before PostgreSQL 11, adding a column with a default was problematic as it would
 have caused a full table rewrite. The corresponding helper `add_column_with_default`
 has been deprecated and will be removed in a later release.
 
-NOTE: **Note:**
 If a backport adding a column with a default value is needed for %12.9 or earlier versions,
 it should use `add_column_with_default` helper. If a [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3)
 is involved, backporting to %12.9 is contraindicated.
@@ -964,7 +961,6 @@ in a previous migration.
 
 ### Example: Add a column `my_column` to the users table
 
-NOTE: **Note:**
 It is important not to leave out the `User.reset_column_information` command, in order to ensure that the old schema is dropped from the cache and ActiveRecord loads the updated schema information.
 
 ```ruby

doc/development/ordering_table_columns.md

@@ -51,7 +51,6 @@ In these examples, the `id` and `user_id` columns are packed together, which
 means we only need 8 bytes to store _both_ of them. This in turn means each row
 will require 8 bytes less space.
 
-Note: **NOTE:**
 Since Ruby on Rails 5.1, the default data type for IDs is `bigint`, which uses 8 bytes.
 We are using `integer` in the examples to showcase a more realistic reordering scenario.
 

doc/development/profiling.md

@@ -16,7 +16,6 @@ There is a `Gitlab::Profiler.profile` method, and corresponding
 `bin/profile-url` script, that enable profiling a GET or POST request to a
 specific URL, either as an anonymous user (the default) or as a specific user.
 
-NOTE: **Note:**
 The first argument to the profiler is either a full URL
 (including the instance hostname) or an absolute path, including the
 leading slash.

doc/development/rake_tasks.md

@@ -18,7 +18,7 @@ bundle exec rake setup
 
 The `setup` task is an alias for `gitlab:setup`.
 This tasks calls `db:reset` to create the database, and calls `db:seed_fu` to seed the database.
-Note: `db:setup` calls `db:seed` but this does nothing.
+`db:setup` calls `db:seed` but this does nothing.
 
 ### Environment variables
 

doc/development/reference_processing.md

@@ -13,7 +13,6 @@ abstractions in the `Banzai` pipeline: `ReferenceFilter` and `ReferenceParser`.
 This page explains what these are, how they are used, and how you would
 implement a new filter/parser pair.
 
-NOTE: **Note:**
 Each `ReferenceFilter` must have a corresponding `ReferenceParser`.
 
 It is possible to share reference parsers between filters - if two filters find
@@ -199,6 +198,5 @@ In practice, all reference parsers inherit from [`BaseParser`](https://gitlab.co
   - `#references_relation` an active record relation for objects by ID.
   - `#nodes_user_can_reference(user, nodes)` to filter nodes directly.
 
-NOTE: **Note:**
 A failure to implement this class for each reference type means that the
 application will raise exceptions during Markdown processing.

doc/development/service_measurement.md

@@ -22,7 +22,6 @@ The measuring module is a tool that allows to measure a service's execution, and
 The measuring module will log these measurements into a structured log called [`service_measurement.log`](../administration/logs.md#service_measurementlog),
 as a single entry for each service execution.
 
-NOTE: **Note:**
 For GitLab.com, `service_measurement.log` is ingested in Elasticsearch and Kibana as part of our monitoring solution.
 
 ## How to use it
@@ -70,9 +69,8 @@ def extra_attributes_for_measurement
 end
 ```
 
-NOTE: **Note:**
-Once the measurement module is injected in the service, it will be behind generic feature flag.
-In order to actually use it, you need to enable measuring for the desired service by enabling the feature flag.
+After the measurement module is injected in the service, it will be behind a generic feature flag.
+To actually use it, you need to enable measuring for the desired service by enabling the feature flag.
 
 ### Enabling measurement using feature flags
 

doc/development/testing_guide/end_to_end/beginners_guide.md

@@ -58,7 +58,6 @@ Check both [GitLab Community Edition](https://gitlab-org.gitlab.io/gitlab-foss/c
 for previously-written tests for this feature. For analyzing the code coverage,
 you must understand which application files implement specific features.
 
-NOTE: **Note:**
 In this tutorial we're writing a login end-to-end test, even though it has been
 sufficiently covered by lower-level testing, because it's the first step for most
 end-to-end flows, and is easiest to understand.
@@ -74,7 +73,6 @@ under the stage.
 
 ![DevOps lifecycle by stages](img/gl-devops-lifecycle-by-stage-numbers_V12_10.png)
 
-NOTE: **Note:**
 If the test is Enterprise Edition only, the test will be created in the `features/ee`
 directory, but follow the same DevOps lifecycle format.
 
@@ -210,7 +208,6 @@ end
 1. Check if the user avatar appears in the top navigation.
 1. Check if the user avatar *does not* appear in the top navigation.
 
-NOTE: **Note:**
 Behind the scenes, `be_signed_in` is a
 [predicate matcher](https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/built-in-matchers/predicate-matchers)
 that [implements checking the user avatar](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/page/main/menu.rb#L74).

doc/development/testing_guide/end_to_end/best_practices.md

@@ -6,7 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # End-to-end testing Best Practices
 
-NOTE: **Note:**
 This is a tailored extension of the Best Practices [found in the testing guide](../best_practices.md).
 
 ## Link a test to its test-case issue
@@ -269,7 +268,7 @@ We don't run tests that require Administrator access against our Production envi
 
 When you add a new test that requires Administrator access, apply the RSpec metadata `:requires_admin` so that the test will not be included in the test suites executed against Production and other environments on which we don't want to run those tests.
 
-Note: When running tests locally or configuring a pipeline, the environment variable `QA_CAN_TEST_ADMIN_FEATURES` can be set to `false` to skip tests that have the `:requires_admin` tag.
+When running tests locally or configuring a pipeline, the environment variable `QA_CAN_TEST_ADMIN_FEATURES` can be set to `false` to skip tests that have the `:requires_admin` tag.
 
 ## Prefer `Commit` resource over `ProjectPush`
 
@@ -294,7 +293,6 @@ Resource::Repository::ProjectPush.fabricate! do |push|
 end
 ```
 
-NOTE: **Note:**
 A few exceptions for using a `ProjectPush` would be when your test calls for testing SSH integration or
 using the Git CLI.
 

doc/development/testing_guide/end_to_end/environment_selection.md

@@ -55,7 +55,6 @@ RSpec.describe 'Area' do
 end
 ```
 
-NOTE: **Note:**
 If the test has a `before` or `after`, you must add the `only` metadata
 to the outer `RSpec.describe`.
 

doc/development/testing_guide/frontend_testing.md

@@ -30,7 +30,6 @@ We have started to migrate frontend tests to the [Jest](https://jestjs.io) testi
 
 Jest tests can be found in `/spec/frontend` and `/ee/spec/frontend` in EE.
 
-NOTE: **Note:**
 Most examples have a Jest and Karma example. See the Karma examples only as explanation to what's going on in the code, should you stumble over some use cases during your discovery. The Jest examples are the one you should follow.
 
 ## Karma test suite
@@ -311,7 +310,6 @@ it('tests a promise rejection', async () => {
 
 You can also simply return a promise from the test function.
 
-NOTE: **Note:**
 Using the `done` and `done.fail` callbacks is discouraged when working with
 promises. They should only be used when testing callback-based code.
 

doc/development/testing_guide/testing_migrations_guide.md

@@ -239,6 +239,5 @@ describe Gitlab::BackgroundMigration::ArchiveLegacyTraces, schema: 2018052915262
 end
 ```
 
-NOTE: **Note:**
 These tests do not run within a database transaction, as we use a deletion database
 cleanup strategy. Do not depend on a transaction being present.

doc/development/uploads.md

@@ -220,7 +220,6 @@ In this setup, an extra Rails route must be implemented in order to handle autho
   and [its routes](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/config/routes/git_http.rb#L31-32).
 - [API endpoints for uploading packages](packages.md#file-uploads).
 
-Note: **Note:**
 This will fallback to _disk buffered upload_ when `direct_upload` is disabled inside the [object storage setting](../administration/uploads.md#object-storage-settings).
 The answer to the `/authorize` call will only contain a file system path.
 

doc/development/value_stream_analytics.md

@@ -59,8 +59,8 @@ def timestamp_projection
 end
 ```
 
-NOTE: **Note:**
-More complex expressions are also possible (e.g. using `COALESCE`). Look at the existing event classes for examples.
+More complex expressions are also possible (for example, using `COALESCE`).
+Review the existing event classes for examples.
 
 In some cases, defining the `timestamp_projection` method is not enough. The calculation query should know which table contains the timestamp expression. Each `Event` class is responsible for making modifications to the calculation query to make the `timestamp_projection` work. This usually means joining an additional table.
 

doc/development/what_requires_downtime.md

@@ -106,13 +106,12 @@ class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration[4.2]
 end
 ```
 
-This will take care of renaming the column, ensuring data stays in sync, copying
-over indexes and foreign keys, etc.
+This will take care of renaming the column, ensuring data stays in sync, and
+copying over indexes and foreign keys.
 
-NOTE: **Note:**
-If a column contains 1 or more indexes that do not contain the name of
-the original column, the above procedure will fail. In this case you will first
-need to rename these indexes.
+If a column contains one or more indexes that don't contain the name of the
+original column, the previously described procedure will fail. In that case,
+you'll first need to rename these indexes.
 
 ### Step 2: Add A Post-Deployment Migration
 
@@ -137,7 +136,6 @@ class CleanupUsersUpdatedAtRename < ActiveRecord::Migration[4.2]
 end
 ```
 
-NOTE: **Note:**
 If you're renaming a [large table](https://gitlab.com/gitlab-org/gitlab/-/blob/master/rubocop/rubocop-migrations.yml#L3), please carefully consider the state when the first migration has run but the second cleanup migration hasn't been run yet.
 With [Canary](https://gitlab.com/gitlab-com/gl-infra/readiness/-/tree/master/library/canary/) it is possible that the system runs in this state for a significant amount of time.
 
@@ -148,7 +146,7 @@ done without requiring downtime. However, this does require that any application
 changes are deployed _first_. Thus, changing the constraints of a column should
 happen in a post-deployment migration.
 
-NOTE: Avoid using `change_column` as it produces an inefficient query because it re-defines
+Avoid using `change_column` as it produces an inefficient query because it re-defines
 the whole column type.
 
 You can check the following guides for each specific use case: