diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..13b198b91 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,9 @@ +# Vale configuration file. +# +# For more information, see https://errata-ai.gitbook.io/vale/getting-started/configuration. + +StylesPath = doc/.vale +MinAlertLevel = suggestion + +[*.md] +BasedOnStyles = gitlab diff --git a/doc/.vale/gitlab/InternalLinkExtension.yml b/doc/.vale/gitlab/InternalLinkExtension.yml new file mode 100644 index 000000000..d07a26007 --- /dev/null +++ b/doc/.vale/gitlab/InternalLinkExtension.yml @@ -0,0 +1,11 @@ +--- +# Checks that internal links have .md extenstion and not .html extension. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: existence +message: Link %s must use the .md file extension. +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation +level: error +scope: raw +raw: + - '\[.+\]\((https?:){0}[\w\/\.-]+(\.html).*\)' diff --git a/doc/.vale/gitlab/RelativeLinks.yml b/doc/.vale/gitlab/RelativeLinks.yml new file mode 100644 index 000000000..1ec21740c --- /dev/null +++ b/doc/.vale/gitlab/RelativeLinks.yml @@ -0,0 +1,11 @@ +--- +# Checks for the presence of absolute hyperlinks that should be relative. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: existence +message: Link %s must be relative. +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation +level: error +scope: raw +raw: + - '\[.+\]\(https?:\/\/docs\.gitlab\.com\/omnibus.*\)' diff --git a/doc/.vale/gitlab/SentenceSpacing.yml b/doc/.vale/gitlab/SentenceSpacing.yml new file mode 100644 index 000000000..10009e473 --- /dev/null +++ b/doc/.vale/gitlab/SentenceSpacing.yml @@ -0,0 +1,15 @@ +--- +# Checks for the following in common content scenarios: +# +# - No spaces. +# - More than one space. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: existence +message: '"%s" must contain one and only one space.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation +level: error +nonword: true +tokens: + - '[a-z][.?!,][A-Z]' + - '[\w.?!,\(\)\-":] {2,}[\w.?!,\(\)\-":]' diff --git a/doc/.vale/gitlab/Substitutions.yml b/doc/.vale/gitlab/Substitutions.yml new file mode 100644 index 000000000..b32a03e17 --- /dev/null +++ b/doc/.vale/gitlab/Substitutions.yml @@ -0,0 +1,13 @@ +--- +# Checks for use of some of the top misused terms at GitLab. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: substitution +message: Use "%s" instead of "%s". +link: https://about.gitlab.com/handbook/communication/#top-misused-terms +level: error +ignorecase: true +swap: + GitLabber: GitLab team member + self hosted: self-managed + self-hosted: self-managed diff --git a/doc/README.md b/doc/README.md index 540562147..6a14d3fcf 100644 --- a/doc/README.md +++ b/doc/README.md @@ -33,9 +33,9 @@ This section describes the commonly used configuration settings. Check - [Installing GitLab](https://about.gitlab.com/install/) - [Manually downloading and installing a GitLab package](manual_install.md) -- [Setting up a domain name/URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab) for the GitLab Instance so that it can be accessed easily -- [Enabling HTTPS](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) -- [Enabling notification emails](https://docs.gitlab.com/omnibus/settings/smtp.html#smtp-settings) +- [Setting up a domain name/URL](settings/configuration.md#configuring-the-external-url-for-gitlab) for the GitLab Instance so that it can be accessed easily +- [Enabling HTTPS](settings/nginx.md#enable-https) +- [Enabling notification emails](settings/smtp.md#smtp-settings) - [Enabling replying via email](https://docs.gitlab.com/ee/administration/reply_by_email.html#set-it-up) - [Installing and configuring postfix](https://docs.gitlab.com/ee/administration/reply_by_email_postfix_setup.html) - [Enabling container registry on GitLab](https://docs.gitlab.com/ee/administration/packages/container_registry.html#container-registry-domain-configuration) @@ -74,8 +74,8 @@ to work best with the available resources. Check out the [documentation](setting - [Changing the name of the Git user group](settings/configuration.md#changing-the-name-of-the-git-user--group) - [Specify numeric user and group identifiers](settings/configuration.md#specify-numeric-user-and-group-identifiers) - [Only start Omnibus GitLab services after a given filesystem is mounted](settings/configuration.md#only-start-omnibus-gitlab-services-after-a-given-filesystem-is-mounted) -- [Disable user and group account management](settings/configuration.html#disable-user-and-group-account-management) -- [Disable storage directory management](settings/configuration.html#disable-storage-directories-management) +- [Disable user and group account management](settings/configuration.md#disable-user-and-group-account-management) +- [Disable storage directory management](settings/configuration.md#disable-storage-directories-management) - [Configuring Rack attack](settings/configuration.md#configuring-rack-attack) - [SMTP](settings/smtp.md) - [NGINX](settings/nginx.md) diff --git a/doc/architecture/README.md b/doc/architecture/README.md index 4e837bfd6..a438c68e9 100644 --- a/doc/architecture/README.md +++ b/doc/architecture/README.md @@ -161,7 +161,7 @@ The cache mechanism can be summarised as follows: 1. If cache has been dirtied, break the loop. 1. Else, checkout the snapshot. 1. If there are remaining dependencies: - 1. For each remaining dependency: + 1. For each remaining dependency: 1. Build the dependency. 1. Create a snapshot and commit it. 1. Push back the new build cache to CI cache. diff --git a/doc/common_installation_problems/README.md b/doc/common_installation_problems/README.md index ad145aa25..e55327a16 100644 --- a/doc/common_installation_problems/README.md +++ b/doc/common_installation_problems/README.md @@ -222,7 +222,7 @@ Keep in mind that the Git user must have access to the system so please review your security settings at `/etc/security/access.conf` and make sure the Git user is not blocked. -## Postgres error 'FATAL: could not create shared memory segment: Cannot allocate memory' +## Postgres error `FATAL: could not create shared memory segment: Cannot allocate memory` The packaged Postgres instance will try to allocate 25% of total memory as shared memory. On some Linux (virtual) servers, there is less shared memory @@ -245,7 +245,7 @@ postgresql['shared_buffers'] = "100MB" Run `sudo gitlab-ctl reconfigure` for the change to take effect. -## Postgres error 'FATAL: could not open shared memory segment "/PostgreSQL.XXXXXXXXXX": Permission denied' +## Postgres error `FATAL: could not open shared memory segment "/PostgreSQL.XXXXXXXXXX": Permission denied` By default, Postgres will try to detect the shared memory type to use. If you don't have shared memory enabled, you might see this error in `/var/log/gitlab/postgresql/current`. @@ -380,7 +380,7 @@ Redis, Mattermost) are isolated from each other using Unix user accounts. Creating and managing these user accounts requires root access. By default, Omnibus GitLab will create the required Unix accounts during `gitlab-ctl reconfigure` but that behavior can be -[disabled](../settings/configuration.html#disable-user-and-group-account-management). +[disabled](../settings/configuration.md#disable-user-and-group-account-management). In principle Omnibus GitLab could do with only 2 user accounts (one for GitLab and one for Mattermost) if we give each application its own @@ -618,7 +618,7 @@ will need to switch to using `no_root_squash` in your NFS exports on the NFS ser This applies to operating systems using systemd (e.g. Ubuntu 16.04+, CentOS, etc.). Since GitLab 11.2, the `gitlab-runsvdir` starts during the `multi-user.target` -instead of `basic.target`. If you are having trouble starting this service +instead of `basic.target`. If you are having trouble starting this service after upgrading GitLab, you may need to check that your system has properly booted all the required services for `multi-user.target` via the command: diff --git a/doc/development/new-services.md b/doc/development/new-services.md index df4e1dd19..d9eef460f 100644 --- a/doc/development/new-services.md +++ b/doc/development/new-services.md @@ -56,7 +56,7 @@ In `files/gitlab-cookbooks/package/libraries/config/gitlab.rb` you will find the `attribute` methods. If your service exists within the attributes for the GitLab cookbook, you should -add it within the `attribute_block('gitlab')` block. Otherwise, if your service +add it within the `attribute_block('gitlab')` block. Otherwise, if your service has its own cookbook, add it above. Add your service as an attribute, using an underscore to separate words, **even if you diff --git a/doc/development/new-software-definition.md b/doc/development/new-software-definition.md index c9e060659..60ae3d16e 100644 --- a/doc/development/new-software-definition.md +++ b/doc/development/new-software-definition.md @@ -17,7 +17,7 @@ repositories of the local mirror and upstream should be added to `/.custom_sources.yml`. The local mirror should be created in the -project by a member of the Distribution team. It should have the +project by a member of the Distribution team. It should have the `omnibus-builder deploy key` enabled. See other Software services in the directory for examples on how to include your diff --git a/doc/manual_install.md b/doc/manual_install.md index d4b3b330b..1e28fdb4c 100644 --- a/doc/manual_install.md +++ b/doc/manual_install.md @@ -33,10 +33,10 @@ With the desired package downloaded, use your systems package management tool to Change `http://gitlab.example.com` to the URL at which you want to access your GitLab instance. Installation will automatically configure and start GitLab at that URL. -> **Note:** Enabling HTTPS will require [additional configuration](settings/nginx.html#enable-https) to specify the certificates. +> **Note:** Enabling HTTPS will require [additional configuration](settings/nginx.md#enable-https) to specify the certificates. ## Browse to the hostname and login On your first visit, you'll be redirected to a password reset screen. Provide the password for the initial administrator account and you will be redirected back to the login screen. Use the default account's username `root` to login. -See our [documentation for detailed instructions on installing and configuration](https://docs.gitlab.com/omnibus/README.html#installation-and-configuration-using-omnibus-package). +See our [documentation for detailed instructions on installing and configuration](README.md#installation-and-configuration-using-omnibus-package). diff --git a/doc/package-information/README.md b/doc/package-information/README.md index cf5bcb4c0..f537b0fa2 100644 --- a/doc/package-information/README.md +++ b/doc/package-information/README.md @@ -20,7 +20,7 @@ These defauts are noted in the package [defaults document](defaults.md). ## Checking the versions of bundled software Once the Omnibus GitLab package is installed, all versions of the bundled -libraries are located in `/opt/gitlab/version-manifest.txt`. +libraries are located in `/opt/gitlab/version-manifest.txt`. If you don't have the package installed, you can always check the Omnibus GitLab [source repository], specifically the [config directory]. diff --git a/doc/settings/backups.md b/doc/settings/backups.md index 636673f27..ed2b55cfe 100644 --- a/doc/settings/backups.md +++ b/doc/settings/backups.md @@ -32,7 +32,7 @@ sudo crontab -e -u root The cron table will appear in an editor. Enter the command to create a compressed tar file containing the contents of -`/etc/gitlab/`. For example, schedule the backup to run every morning after a +`/etc/gitlab/`. For example, schedule the backup to run every morning after a weekday, Tuesday (day 2) through Saturday (day 6): ``` diff --git a/doc/settings/configuration.md b/doc/settings/configuration.md index 2d09ba17d..136bdd747 100644 --- a/doc/settings/configuration.md +++ b/doc/settings/configuration.md @@ -649,7 +649,7 @@ details. GitLab 12.2 added support for [CSP and nonces with inline JavaScript](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src). It is [not configured on by default -yet](https://gitlab.com/gitlab-org/gitlab/issues/30720). An example +yet](https://gitlab.com/gitlab-org/gitlab/issues/30720). An example configuration that will work for most installations of GitLab is below: ```ruby diff --git a/doc/settings/environment-variables.md b/doc/settings/environment-variables.md index 874265bb9..539bca660 100644 --- a/doc/settings/environment-variables.md +++ b/doc/settings/environment-variables.md @@ -1,9 +1,9 @@ # Setting custom environment variables If necessary you can set custom environment variables to be used by Unicorn, -Sidekiq, Rails and Rake via `/etc/gitlab/gitlab.rb`. This can be useful in +Sidekiq, Rails and Rake via `/etc/gitlab/gitlab.rb`. This can be useful in situations where you need to use a proxy to access the internet and need to -clone externally hosted repositories directly into GitLab. In +clone externally hosted repositories directly into GitLab. In `/etc/gitlab/gitlab.rb` supply a `gitlab_rails['env']` with a hash value. For example: diff --git a/doc/settings/nginx.md b/doc/settings/nginx.md index 78a9a7612..3fe7bd3f6 100644 --- a/doc/settings/nginx.md +++ b/doc/settings/nginx.md @@ -327,7 +327,7 @@ nginx['listen_addresses'] = ["0.0.0.0", "[::]"] # listen on all IPv4 and IPv6 ad By default NGINX will listen on the port specified in `external_url` or implicitly use the right port (80 for HTTP, 443 for HTTPS). If you are running GitLab behind a reverse proxy, you may want to override the listen port to -something else. For example, to use port 8081: +something else. For example, to use port 8081: ```ruby nginx['listen_port'] = 8081 @@ -336,7 +336,7 @@ nginx['listen_port'] = 8081 ## Supporting proxied SSL By default NGINX will auto-detect whether to use SSL if `external_url` -contains `https://`. If you are running GitLab behind a reverse proxy, you +contains `https://`. If you are running GitLab behind a reverse proxy, you may wish to terminate SSL at another proxy server or load balancer. To do this, be sure the `external_url` contains `https://` and apply the following configuration to `gitlab.rb`: @@ -782,9 +782,9 @@ systems `sudo service nginx restart`). Make sure you don't have the `proxy_set_header` configuration in `nginx['custom_gitlab_server_config']` settings and instead use the -['proxy_set_headers'](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) configuration in your `gitlab.rb` file. +['proxy_set_headers'](#supporting-proxied-ssl) configuration in your `gitlab.rb` file. -### javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure +### `javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure` Starting with GitLab 10, the Omnibus GitLab package no longer supports TLSv1 protocol by default. This can cause connection issues with some older Java based IDE clients when interacting with diff --git a/doc/settings/ssl.md b/doc/settings/ssl.md index d5aaeb393..39ed1d7bc 100644 --- a/doc/settings/ssl.md +++ b/doc/settings/ssl.md @@ -15,7 +15,7 @@ Administrators can enable secure http using any method supported by a GitLab ser |-|-|-| | Primary GitLab Instance Domain | [Yes](nginx.md#manually-configuring-https) | [Yes](#lets-encrypt-integration) | | Container Registry | [Yes](https://docs.gitlab.com/ee/administration/packages/container_registry.html#configure-container-registry-under-its-own-domain) | [Yes](#lets-encrypt-integration) | -| Mattermost | [Yes](https://docs.gitlab.com/omnibus/gitlab-mattermost/README.html#running-gitlab-mattermost-with-https) | [Yes](#lets-encrypt-integration) | +| Mattermost | [Yes](../gitlab-mattermost/README.md#running-gitlab-mattermost-with-https) | [Yes](#lets-encrypt-integration) | | GitLab Pages | [Yes](https://docs.gitlab.com/ee/administration/pages/#wildcard-domains-with-tls-support) | No | ### Let's Encrypt Integration diff --git a/doc/update/README.md b/doc/update/README.md index 9f84b538a..152b245ec 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -284,7 +284,7 @@ you've completed these steps. #### Using PostgreSQL HA -Pick a node to be the `Deploy Node`. It can be any node, but it must be the same +Pick a node to be the `Deploy Node`. It can be any node, but it must be the same node throughout the process. **Deploy node** diff --git a/doc/update/convert_to_omnibus.md b/doc/update/convert_to_omnibus.md index 471d05bbe..fcff52d5e 100644 --- a/doc/update/convert_to_omnibus.md +++ b/doc/update/convert_to_omnibus.md @@ -32,8 +32,8 @@ This assumes that `gitlab-shell` is located in `/home/git`. ## Upgrading from non-Omnibus PostgreSQL to an Omnibus installation in-place It is also possible to upgrade a source GitLab installation to Omnibus GitLab -in-place. Below we assume you are using PostgreSQL on Ubuntu, and that you -have an Omnibus GitLab package matching your current GitLab version. We also +in-place. Below we assume you are using PostgreSQL on Ubuntu, and that you +have an Omnibus GitLab package matching your current GitLab version. We also assume that your source installation of GitLab uses all the default paths and users. diff --git a/doc/update/gitlab_10_changes.md b/doc/update/gitlab_10_changes.md index 3eb4866ab..7200c6aea 100644 --- a/doc/update/gitlab_10_changes.md +++ b/doc/update/gitlab_10_changes.md @@ -3,7 +3,7 @@ From version 10.0 GitLab requires the version of PostgreSQL to be 9.6 or higher. -Check out [docs on upgrading packaged PostgreSQL server](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server) +Check out [docs on upgrading packaged PostgreSQL server](../settings/database.md#upgrade-packaged-postgresql-server) for details. - For users running versions below 8.15 and using PostgreSQL bundled with diff --git a/doc/update/gitlab_11_changes.md b/doc/update/gitlab_11_changes.md index c5769dc8f..0b478a599 100644 --- a/doc/update/gitlab_11_changes.md +++ b/doc/update/gitlab_11_changes.md @@ -45,14 +45,14 @@ been removed: 1. Mattermost related configurations - Support for most of the Mattermost related configuration have been removed, except for the essential ones that - are needed for GitLab-Mattermost integration. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/gitlab-mattermost/#upgrading-gitlab-mattermost-from-versions-prior-to-11-0) + are needed for GitLab-Mattermost integration. [Check out the official documentation for details](../gitlab-mattermost/README.md#upgrading-gitlab-mattermost-from-versions-prior-to-110) 1. Legacy `git_data_dir` configuration, which was used to set location of where data was to be stored. It has been now replaced with `git_data_dirs` - configuration. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory) + configuration. [Check out the official documentation for details](../settings/configuration.md#storing-git-data-in-an-alternative-directory) 1. Old format of `git_data_dirs` configuration has been replaced with a new - format, allowing much more fine grain control. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory) + format, allowing much more fine grain control. [Check out the official documentation for details](../settings/configuration.md#storing-git-data-in-an-alternative-directory) ## Changes introduced in minor versions @@ -72,7 +72,7 @@ Rack Attack is disabled by default. To continue using Rack Attack, you must [ena For users looking for preserving the Prometheus version 1 data, a command line tool is provided to upgrade their Prometheus service and migrate data to - the format supported by new Prometheus version. This tool can be invoked + the format supported by new Prometheus version. This tool can be invoked using the following command: ```bash @@ -81,7 +81,7 @@ Rack Attack is disabled by default. To continue using Rack Attack, you must [ena This tool will convert existing data to a format supported by the latest Prometheus version. Depending on the volume of data, this process can take - hours. If users do not want to migrate the data, but start with a clean + hours. If users do not want to migrate the data, but start with a clean database, they can pass `--skip-data-migration` flag to the above command. NOTE: **Note**: Prometheus service will be stopped during the migration process. diff --git a/doc/update/gitlab_12_changes.md b/doc/update/gitlab_12_changes.md index ace2a883f..b68ccd0a2 100644 --- a/doc/update/gitlab_12_changes.md +++ b/doc/update/gitlab_12_changes.md @@ -8,7 +8,7 @@ When upgrading to a new major version, remember to first [check for background m Prometheus 1.x was deprecated in GitLab 11.4, and Prometheus 2.8.1 was installed by default on new installations. Users updating from older versions of GitLab could manually upgrade Prometheus data using the -[`gitlab-ctl prometheus-upgrade`](https://docs.gitlab.com/omnibus/update/gitlab_11_changes.html#114) +[`gitlab-ctl prometheus-upgrade`](gitlab_11_changes.md#114) command provided. You can view current Prometheus version in use from the instances Prometheus `/status` page. @@ -16,7 +16,7 @@ With GitLab 12.0, support for Prometheus 1.x is completely removed, and as part of the upgrade process, Prometheus binaries will be updated to version 2.8.1. Existing data from Prometheus 1.x installation WILL NOT be migrated as part of this automatic upgrade, and users who wish to retain that data should -[manually upgrade Prometheus version](https://docs.gitlab.com/omnibus/update/gitlab_11_changes.html#114) +[manually upgrade Prometheus version](gitlab_11_changes.md#114) before upgrading to GitLab 12.0 For users who use `/etc/gitlab/skip-auto-reconfigure` file to skip automatic @@ -110,7 +110,7 @@ ones at the earliest. The Redis version packaged with Omnibus GitLab has been updated to Redis 5.0.7. You will need to restart Redis after the upgrade so that the new version will be active. To restart Redis, run `sudo gitlab-ctl restart redis`. If your instance -has Redis HA with Sentinel, follow the upgrade steps documented in [Updating GitLab installed with the Omnibus GitLab package](https://docs.gitlab.com/omnibus/update/README.html#using-redis-ha-using-sentinel) +has Redis HA with Sentinel, follow the upgrade steps documented in [Updating GitLab installed with the Omnibus GitLab package](README.md#using-redis-ha-using-sentinel) to avoid downtime. ### 12.8 diff --git a/gitlab-ci-config/gitlab-com.yml b/gitlab-ci-config/gitlab-com.yml index f83a91df6..00f176854 100644 --- a/gitlab-ci-config/gitlab-com.yml +++ b/gitlab-ci-config/gitlab-com.yml @@ -135,6 +135,8 @@ docs-lint: before_script: [] <<: *dedicated-runner script: + # Lint prose + - vale --minAlertLevel error doc # Lint Markdown - markdownlint --config .markdownlint.json 'doc/**/*.md' # Prepare docs for build