Commit 4f93fa4b authored by Evan Read's avatar Evan Read Committed by Achilleas Pipinellis

Add lint rule that headings must increment one level at a time

Also fixes instances in Markdown that broke the rule.
parent 4f6ec719
......@@ -68,7 +68,7 @@ docs lint:
# Lint Markdown
# https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
- bundle exec mdl content/$DOCS_GITLAB_REPO_SUFFIX/**/*.md --ignore-front-matter --rules \
MD004,MD032,MD034
MD001,MD032,MD034
# Build HTML from Markdown
- bundle exec nanoc
# Check the internal links
......
......@@ -1109,7 +1109,7 @@ If you enable Monitoring, it must be enabled on **all** database servers.
## Troubleshooting
#### Consul and PostgreSQL changes not taking effect.
### Consul and PostgreSQL changes not taking effect.
Due to the potential impacts, `gitlab-ctl reconfigure` only reloads Consul and PostgreSQL, it will not restart the services. However, not all changes can be activated by reloading.
......@@ -1119,7 +1119,7 @@ For PostgreSQL, it is usually safe to restart the master node by default. Automa
On the consul server nodes, it is important to restart the consul service in a controlled fashion. Read our [consul documentation](consul.md#restarting-the-server-cluster) for instructions on how to restart the service.
#### `gitlab-ctl repmgr-check-master` command produces errors
### `gitlab-ctl repmgr-check-master` command produces errors
If this command displays errors about database permissions it is likely that something failed during
install, resulting in the `gitlab-consul` database user getting incorrect permissions. Follow these
......@@ -1134,7 +1134,7 @@ steps to fix the problem:
Now there should not be errors. If errors still occur then there is another problem.
#### PGBouncer error `ERROR: pgbouncer cannot connect to server`
### PGBouncer error `ERROR: pgbouncer cannot connect to server`
You may get this error when running `gitlab-rake gitlab:db:configure` or you
may see the error in the PGBouncer log file.
......@@ -1162,7 +1162,7 @@ postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>)
[Reconfigure GitLab] for the changes to take effect.
#### Issues with other components
### Issues with other components
If you're running into an issue with a component not outlined here, be sure to check the troubleshooting section of their specific documentation page.
......
......@@ -10,7 +10,7 @@ By default, merge request diffs are stored in the database, in a table named
`merge_request_diff_files`. Larger installations may find this table grows too
large, in which case, switching to external storage is recommended.
### Using external storage
## Using external storage
Merge request diffs can be stored on disk, or in object storage. In general, it
is better to store the diffs in the database than on disk.
......@@ -46,7 +46,7 @@ To enable external storage of merge request diffs, follow the instructions below
enabled: true
```
1. _The external diffs will be stored in
1. _The external diffs will be stored in
`/home/git/gitlab/shared/external-diffs`._ To change the path, for example,
to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml`
and add or amend the following lines:
......@@ -59,13 +59,13 @@ To enable external storage of merge request diffs, follow the instructions below
1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
### Using object storage
## Using object storage
Instead of storing the external diffs on disk, we recommended the use of an object
store like AWS S3 instead. This configuration relies on valid AWS credentials to
be configured already.
### Object Storage Settings
## Object Storage Settings
For source installations, these settings are nested under `external_diffs:` and
then `object_store:`. On Omnibus installations, they are prefixed by
......@@ -80,7 +80,7 @@ then `object_store:`. On Omnibus installations, they are prefixed by
| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
| `connection` | Various connection options described below | |
#### S3 compatible connection settings
### S3 compatible connection settings
The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
......@@ -146,7 +146,7 @@ The connection settings match those provided by [Fog](https://github.com/fog), a
1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
### Alternative in-database storage
## Alternative in-database storage
Enabling external diffs may reduce the performance of merge requests, as they
must be retrieved in a separate operation to other data. A compromise may be
......
......@@ -3,7 +3,7 @@
>**Notes:**
Uploads represent all user data that may be sent to GitLab as a single file. As an example, avatars and notes' attachments are uploads. Uploads are integral to GitLab functionality, and therefore cannot be disabled.
### Using local storage
## Using local storage
>**Notes:**
This is the default configuration
......@@ -48,7 +48,7 @@ _The uploads are stored by default in
1. Save the file and [restart GitLab][] for the changes to take effect.
### Using object storage **(CORE ONLY)**
## Using object storage **(CORE ONLY)**
> **Notes:**
>
......@@ -60,7 +60,7 @@ If you don't want to use the local disk where GitLab is installed to store the
uploads, you can use an object storage provider like AWS S3 instead.
This configuration relies on valid AWS credentials to be configured already.
### Object Storage Settings
## Object Storage Settings
For source installations the following settings are nested under `uploads:` and then `object_store:`. On omnibus installs they are prefixed by `uploads_object_store_`.
......@@ -73,7 +73,7 @@ For source installations the following settings are nested under `uploads:` and
| `proxy_download` | Set to true to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
| `connection` | Various connection options described below | |
#### S3 compatible connection settings
### S3 compatible connection settings
The connection settings match those provided by [Fog](https://github.com/fog), and are as follows:
......
# Project snippets
### Snippet visibility level
## Snippet visibility level
Snippets in GitLab can be either private, internal or public.
You can set it with the `visibility` field in the snippet.
......@@ -14,7 +14,7 @@ Constants for snippet visibility levels are:
| `public` | The snippet can be accessed without any authentication |
NOTE: **Note:**
From July 2019, the `Internal` visibility setting is disabled for new projects, groups,
From July 2019, the `Internal` visibility setting is disabled for new projects, groups,
and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal`
visibility setting keep this setting. You can read more about the change in the
[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388).
......
......@@ -9,7 +9,7 @@ The V3 API documentation is still
Below are the changes made between V3 and V4.
### 8.17
## 8.17
- Removed `GET /projects/:search` (use: `GET /projects?search=x`) [!8877](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8877)
- `iid` filter has been removed from `GET /projects/:id/issues` [!8967](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8967)
......@@ -18,7 +18,7 @@ Below are the changes made between V3 and V4.
- Project snippets do not return deprecated field `expires_at` [!8723](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8723)
- Endpoints under `GET /projects/:id/keys` have been removed (use `GET /projects/:id/deploy_keys`) [!8716](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8716)
### 9.0
## 9.0
- Status 409 returned for `POST /projects/:id/members` when a member already exists [!9093](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9093)
- Moved `DELETE /projects/:id/star` to `POST /projects/:id/unstar` [!9328](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9328)
......
......@@ -32,7 +32,7 @@ through the process of setting up GitLab CI/CD for end-to-end testing Javascript
with WebdriverIO, but the general strategy should carry over to other languages.
We assume you are familiar with GitLab, [GitLab CI/CD](../../README.md), [Review Apps](../../review_apps/index.md), and running your app locally, e.g., on `localhost:8000`.
### What to test
## What to test
In the widely-used [testing pyramid strategy](https://martinfowler.com/bliki/TestPyramid.html), end-to-end tests act more like a
safeguard: [most of your code should be covered by
......@@ -40,9 +40,9 @@ unit tests](https://vincenttunru.com/100-percent-coverage/) that allow you to ea
will likely want to
[limit the number of end-to-end tests](https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html)
to just enough to give you the confidence that the deployment went as intended, that your
infrastructure is up and running, and that your units of code work well together.
infrastructure is up and running, and that your units of code work well together.
### Selenium and WebdriverIO
## Selenium and WebdriverIO
[Selenium](http://www.seleniumhq.org/) is a piece of software that can control web browsers, e.g., to make them
visit a specific URL or interact with elements on the page. It can be programmatically controlled
......@@ -65,7 +65,7 @@ describe('A visitor without account', function(){
expect(browser.getUrl()).toMatch('page-that-does-not-exist');
browser.element('.content a[href="/"]').click();
expect(browser.getUrl()).not.toMatch('page-that-does-not-exist');
});
});
......
......@@ -6,12 +6,12 @@ Libravatar is a service which delivers your avatar (profile picture) to other we
This means that it is not complicated to switch to Libravatar avatar service or even self hosted Libravatar server.
# Configuration
## Configuration
In [gitlab.yml gravatar section](https://gitlab.com/gitlab-org/gitlab-ce/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122) set
the configuration options as follows:
## For HTTP
### For HTTP
```yml
gravatar:
......@@ -20,7 +20,7 @@ the configuration options as follows:
plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
## For HTTPS
### For HTTPS
```yml
gravatar:
......@@ -29,7 +29,7 @@ the configuration options as follows:
ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
```
## Self-hosted
### Self-hosted
If you are [running your own libravatar service](https://wiki.libravatar.org/running_your_own/) the URL will be different in the configuration
but the important part is to provide the same placeholders so GitLab can parse the URL correctly.
......@@ -38,7 +38,7 @@ For example, you host a service on `http://libravatar.example.com` the `plain_ur
`http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
## Omnibus-gitlab example
### Omnibus-gitlab example
In `/etc/gitlab/gitlab.rb`:
......@@ -67,7 +67,7 @@ For example, you can use `retro` set in which case the URL would look like: `pla
## Usage examples
#### For Microsoft Office 365
### For Microsoft Office 365
If your users are Office 365-users, the "GetPersonaPhoto" service can be used. Note that this service requires login, so this use case is
most useful in a corporate installation, where all users have access to Office 365.
......
......@@ -144,7 +144,7 @@ If you're working on the GitLab EE repository, the entry will be added to
| [`--type`](#--type-or--t) | `-t` | The category of the change, valid options are: `added`, `fixed`, `changed`, `deprecated`, `removed`, `security`, `performance`, `other` |
| `--help` | `-h` | Print help message |
##### `--amend`
#### `--amend`
You can pass the **`--amend`** argument to automatically stage the generated
file and amend it to the previous commit.
......@@ -166,7 +166,7 @@ author:
type:
```
##### `--force` or `-f`
#### `--force` or `-f`
Use **`--force`** or **`-f`** to overwrite an existing changelog entry if it
already exists.
......@@ -184,7 +184,7 @@ author:
type:
```
##### `--merge-request` or `-m`
#### `--merge-request` or `-m`
Use the **`--merge-request`** or **`-m`** argument to provide the
`merge_request` value:
......@@ -199,7 +199,7 @@ author:
type:
```
##### `--dry-run` or `-n`
#### `--dry-run` or `-n`
Use the **`--dry-run`** or **`-n`** argument to prevent actually writing or
committing anything:
......@@ -216,7 +216,7 @@ type:
$ ls changelogs/unreleased/
```
##### `--git-username` or `-u`
#### `--git-username` or `-u`
Use the **`--git-username`** or **`-u`** argument to automatically fill in the
`author` value with your configured Git `user.name` value:
......@@ -234,7 +234,7 @@ author: Jane Doe
type:
```
##### `--type` or `-t`
#### `--type` or `-t`
Use the **`--type`** or **`-t`** argument to provide the `type` value:
......
......@@ -446,7 +446,6 @@ The disadvantage of this:
port `render_if_exists` to CE.
- If we have typos in the partial name, it would be silently ignored.
##### Caveats
The `render_if_exists` view path argument must be relative to `app/views/` and `ee/app/views`.
......@@ -973,7 +972,7 @@ For regular JS files, the approach is similar.
1. An EE file should be created with the EE only code, and it should extend the CE counterpart.
1. For code inside functions that can't be extended, the code should be moved into a new file and we should use `ee_else_ce` helper:
##### Example:
#### Example:
```javascript
import eeCode from 'ee_else_ce/ee_code';
......@@ -1000,7 +999,7 @@ styles are usually kept in stylesheet that is common for both CE and EE, and it
to isolate such ruleset from rest of CE rules (along with adding comment describing the same)
to avoid conflicts during CE to EE merge.
#### Bad
### Bad
```scss
.section-body {
......@@ -1016,7 +1015,7 @@ to avoid conflicts during CE to EE merge.
}
```
#### Good
### Good
```scss
.section-body {
......@@ -1034,7 +1033,7 @@ to avoid conflicts during CE to EE merge.
// EE-specific end
```
### Backporting changes from EE to CE
## Backporting changes from EE to CE
Until the work completed to merge the ce and ee codebases, which is tracked on [epic &802](https://gitlab.com/groups/gitlab-org/-/epics/802), there exists times in which some changes for EE require specific changes to the CE
code base. Examples of backports include the following:
......
# Security
### Resources
## Resources
[Mozilla’s HTTP Observatory CLI][observatory-cli] and the
[Qualys SSL Labs Server Test][qualys-ssl] are good resources for finding
......@@ -56,7 +57,7 @@ Some resources on implementing Subresource Integrity:
-->
### Including external resources
## Including external resources
External fonts, CSS, and JavaScript should never be used with the exception of
Google Analytics and Piwik - and only when the instance has enabled it. Assets
......@@ -64,7 +65,7 @@ should always be hosted and served locally from the GitLab instance. Embedded
resources via `iframes` should never be used except in certain circumstances
such as with ReCaptcha, which cannot be used without an `iframe`.
### Avoiding inline scripts and styles
## Avoiding inline scripts and styles
In order to protect users from [XSS vulnerabilities][xss], we will disable
inline scripts in the future using Content Security Policy.
......
# GitLab tests in the Continuous Integration (CI) context
### Test suite parallelization on the CI
## Test suite parallelization on the CI
Our current CI parallelization setup is as follows:
......@@ -26,7 +26,7 @@ Our current CI parallelization setup is as follows:
After that, the next pipeline will use the up-to-date
`knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file.
### Monitoring
## Monitoring
The GitLab test suite is [monitored] for the `master` branch, and any branch
that includes `rspec-profile` in their name.
......
# Sign into GitLab with (almost) any OAuth2 provider
The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider
(or any OAuth2 provider compatible with this gem)
(or any OAuth2 provider compatible with this gem)
This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below:
......@@ -12,7 +12,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
1. Strategy parses user information from the response, using a **configurable** format
1. GitLab finds or creates the returned user and logs them in
### Limitations of this Strategy:
## Limitations of this Strategy:
- It can only be used for Single Sign on, and will not provide any other access granted by any OAuth provider
(importing projects or users, etc)
......@@ -20,7 +20,7 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
- It is not able to fetch user information from more than one URL
- It has not been tested with user information formats other than JSON
### Config Instructions
## Config Instructions
1. Register your application in the OAuth2 provider you wish to authenticate with.
......@@ -57,9 +57,9 @@ This strategy is designed to allow configuration of the simple OmniAuth SSO proc
1. Restart GitLab for the changes to take effect
On the sign in page there should now be a new button below the regular sign in form.
On the sign in page there should now be a new button below the regular sign in form.
Click the button to begin your provider's authentication process. This will direct
the browser to your OAuth2 Provider's authentication page. If everything goes well
the user will be returned to your GitLab instance and will be signed in.
[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example
\ No newline at end of file
[1]: https://gitlab.com/satorix/omniauth-oauth2-generic#gitlab-config-example
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