Commit 57bc5d1d authored by Amy Qualls's avatar Amy Qualls Committed by Craig Norris

Re-flow note boxes back into body text

Re-flow note boxes back into body text for pages that don't have
stage ownership. Also, small tone and style changes for things that
caught my eye while I was scrolling.
parent af754207
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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:
......
......@@ -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:
......
......@@ -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.
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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"]');
......
......@@ -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
......
......@@ -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 () => ({
......
......@@ -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
......
......@@ -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/)
......
......@@ -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
......
......@@ -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
......
......@@ -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,7 +429,6 @@ 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`.
......
......@@ -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
......
......@@ -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
......
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