Commit 6a493ca3 authored by Craig Norris's avatar Craig Norris

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

Re-flow notes into body text

See merge request gitlab-org/gitlab!46835
parents ee93e6a2 254b0ad9
......@@ -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.
......
......@@ -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).
......
......@@ -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
......
......@@ -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
......
......@@ -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:
......
......@@ -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
......
......@@ -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
......
......@@ -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.
......
......@@ -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.
......
......@@ -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
......
......@@ -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.
......@@ -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
......
......@@ -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).
......
......@@ -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.
......
......@@ -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`.
......
......@@ -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.
......
......@@ -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.
......@@ -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.
......
......@@ -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.
......
......@@ -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:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment