diff options
| -rw-r--r-- | .gitpod.yml | 3 | ||||
| -rw-r--r-- | Gemfile | 2 | ||||
| -rw-r--r-- | Gemfile.lock | 4 | ||||
| -rw-r--r-- | app/assets/javascripts/boards/components/modal/empty_state.vue | 21 | ||||
| -rw-r--r-- | app/assets/javascripts/vue_shared/components/gl_mentions.vue | 16 | ||||
| -rw-r--r-- | app/assets/javascripts/vue_shared/components/markdown/field.vue | 2 | ||||
| -rw-r--r-- | changelogs/unreleased/Fix-bad-escape-in-empty_state-vue.yml | 5 | ||||
| -rw-r--r-- | changelogs/unreleased/sh-update-rack-2-2-3.yml | 5 | ||||
| -rw-r--r-- | doc/ci/variables/predefined_variables.md | 8 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 282 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 4 | ||||
| -rw-r--r-- | doc/development/documentation/testing.md | 292 | ||||
| -rw-r--r-- | locale/gitlab.pot | 8 | ||||
| -rw-r--r-- | spec/features/boards/add_issues_modal_spec.rb | 7 | ||||
| -rw-r--r-- | spec/features/issues/gfm_autocomplete_spec.rb | 28 |
15 files changed, 380 insertions, 307 deletions
diff --git a/.gitpod.yml b/.gitpod.yml index 2c6aa2a962d..6a771e77769 100644 --- a/.gitpod.yml +++ b/.gitpod.yml @@ -49,6 +49,9 @@ tasks: if [ "$GITLAB_RUN_DB_MIGRATIONS" == true ]; then make gitlab-db-migrate fi + cd ../gitlab + git checkout db/structure.sql + cd ../gitlab-development-kit # Waiting for GitLab ... gp await-port 3000 printf "Waiting for GitLab at $(gp url 3000) ..." @@ -173,7 +173,7 @@ gem 'diffy', '~> 3.3' gem 'diff_match_patch', '~> 0.1.0' # Application server -gem 'rack', '~> 2.1.4' +gem 'rack', '~> 2.2.3' # https://github.com/sharpstone/rack-timeout/blob/master/README.md#rails-apps-manually gem 'rack-timeout', '~> 0.5.1', require: 'rack/timeout/base' diff --git a/Gemfile.lock b/Gemfile.lock index 271c1950ca1..579fd2c8e88 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -867,7 +867,7 @@ GEM public_suffix (4.0.6) pyu-ruby-sasl (0.0.3.3) raabro (1.1.6) - rack (2.1.4) + rack (2.2.3) rack-accept (0.4.5) rack (>= 0.4) rack-attack (6.3.0) @@ -1446,7 +1446,7 @@ DEPENDENCIES prometheus-client-mmap (~> 0.12.0) pry-byebug (~> 3.9.0) pry-rails (~> 0.3.9) - rack (~> 2.1.4) + rack (~> 2.2.3) rack-attack (~> 6.3.0) rack-cors (~> 1.0.6) rack-oauth2 (~> 1.9.3) diff --git a/app/assets/javascripts/boards/components/modal/empty_state.vue b/app/assets/javascripts/boards/components/modal/empty_state.vue index cd4512f320f..eb2db260717 100644 --- a/app/assets/javascripts/boards/components/modal/empty_state.vue +++ b/app/assets/javascripts/boards/components/modal/empty_state.vue @@ -1,13 +1,13 @@ <script> -/* eslint-disable vue/no-v-html */ -import { GlButton } from '@gitlab/ui'; -import { __, sprintf } from '~/locale'; +import { GlButton, GlSprintf } from '@gitlab/ui'; +import { __ } from '~/locale'; import ModalStore from '../../stores/modal_store'; import modalMixin from '../../mixins/modal_mixins'; export default { components: { GlButton, + GlSprintf, }, mixins: [modalMixin], props: { @@ -34,11 +34,8 @@ export default { if (this.activeTab === 'selected') { obj.title = __("You haven't selected any issues yet"); - obj.content = sprintf( - __( - 'Go back to %{startTag}Open issues%{endTag} and select some issues to add to your board.', - ), - { startTag: '<strong>', endTag: '</strong>' }, + obj.content = __( + 'Go back to %{tagStart}Open issues%{tagEnd} and select some issues to add to your board.', ); } @@ -57,7 +54,13 @@ export default { <div class="col-12 col-md-6 order-md-first"> <div class="text-content"> <h4>{{ contents.title }}</h4> - <p v-html="contents.content"></p> + <p> + <gl-sprintf :message="contents.content"> + <template #tag="{ content }"> + <strong>{{ content }}</strong> + </template> + </gl-sprintf> + </p> <gl-button v-if="activeTab === 'all'" :href="newIssuePath" diff --git a/app/assets/javascripts/vue_shared/components/gl_mentions.vue b/app/assets/javascripts/vue_shared/components/gl_mentions.vue index 6d07eaa9c2f..dde7e3ebe13 100644 --- a/app/assets/javascripts/vue_shared/components/gl_mentions.vue +++ b/app/assets/javascripts/vue_shared/components/gl_mentions.vue @@ -11,6 +11,7 @@ const AutoComplete = { Members: 'members', MergeRequests: 'mergeRequests', Milestones: 'milestones', + Snippets: 'snippets', }; const groupType = 'Group'; // eslint-disable-line @gitlab/require-i18n-strings @@ -129,6 +130,14 @@ const autoCompleteMap = { return escape(original.title); }, }, + [AutoComplete.Snippets]: { + filterValues() { + return this[AutoComplete.Snippets]; + }, + menuItemTemplate({ original }) { + return `<small>${original.id}</small> ${escape(original.title)}`; + }, + }, }; export default { @@ -184,6 +193,13 @@ export default { selectTemplate: ({ original }) => `%"${escape(original.title)}"`, values: this.getValues(AutoComplete.Milestones), }, + { + trigger: '$', + fillAttr: 'id', + lookup: value => value.id + value.title, + menuItemTemplate: autoCompleteMap[AutoComplete.Snippets].menuItemTemplate, + values: this.getValues(AutoComplete.Snippets), + }, ], }); diff --git a/app/assets/javascripts/vue_shared/components/markdown/field.vue b/app/assets/javascripts/vue_shared/components/markdown/field.vue index 6a36ca162dd..1808e4d6ad4 100644 --- a/app/assets/javascripts/vue_shared/components/markdown/field.vue +++ b/app/assets/javascripts/vue_shared/components/markdown/field.vue @@ -177,7 +177,7 @@ export default { epics: this.enableAutocomplete, milestones: this.enableAutocomplete && !this.glFeatures.tributeAutocomplete, labels: this.enableAutocomplete && !this.glFeatures.tributeAutocomplete, - snippets: this.enableAutocomplete, + snippets: this.enableAutocomplete && !this.glFeatures.tributeAutocomplete, }, true, ); diff --git a/changelogs/unreleased/Fix-bad-escape-in-empty_state-vue.yml b/changelogs/unreleased/Fix-bad-escape-in-empty_state-vue.yml new file mode 100644 index 00000000000..68b65df96d9 --- /dev/null +++ b/changelogs/unreleased/Fix-bad-escape-in-empty_state-vue.yml @@ -0,0 +1,5 @@ +--- +title: Fix Bad Escape in Issue Board Empty State +merge_request: 45465 +author: Kev @KevSlashNull +type: fixed diff --git a/changelogs/unreleased/sh-update-rack-2-2-3.yml b/changelogs/unreleased/sh-update-rack-2-2-3.yml new file mode 100644 index 00000000000..e4d44b1c72f --- /dev/null +++ b/changelogs/unreleased/sh-update-rack-2-2-3.yml @@ -0,0 +1,5 @@ +--- +title: Update Rack to v2.2.3 +merge_request: 45183 +author: +type: changed diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 08aaacd2620..7ee602c6799 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -75,8 +75,8 @@ Kubernetes-specific environment variables are detailed in the | `CI_JOB_URL` | 11.1 | 0.5 | Job details URL | | `CI_KUBERNETES_ACTIVE` | 13.0 | all | Included with the value `true` only if the pipeline has a Kubernetes cluster available for deployments. Not included if no cluster is available. Can be used as an alternative to [`only:kubernetes`/`except:kubernetes`](../yaml/README.md#onlykubernetesexceptkubernetes) with [`rules:if`](../yaml/README.md#rulesif) | | `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | -| `CI_MERGE_REQUEST_ID` | 11.6 | all | The instance-level ID of the merge request. Only available if [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. | -| `CI_MERGE_REQUEST_IID` | 11.6 | all | The project-level IID (internal ID) of the merge request. Only available If [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. | +| `CI_MERGE_REQUEST_ID` | 11.6 | all | The instance-level ID of the merge request. Only available if [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. This is a unique ID across all projects on GitLab. | +| `CI_MERGE_REQUEST_IID` | 11.6 | all | The project-level IID (internal ID) of the merge request. Only available If [the pipelines are for merge requests](../merge_request_pipelines/index.md) and the merge request is created. This ID is unique for the current project. | | `CI_MERGE_REQUEST_LABELS` | 11.9 | all | Comma-separated label names of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | | `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | | `CI_MERGE_REQUEST_PROJECT_ID` | 11.6 | all | The ID of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created. | @@ -96,8 +96,8 @@ Kubernetes-specific environment variables are detailed in the | `CI_NODE_TOTAL` | 11.5 | all | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. | | `CI_PAGES_DOMAIN` | 11.8 | all | The configured domain that hosts GitLab Pages. | | `CI_PAGES_URL` | 11.8 | all | URL to GitLab Pages-built pages. Always belongs to a subdomain of `CI_PAGES_DOMAIN`. | -| `CI_PIPELINE_ID` | 8.10 | all | The instance-level ID of the current pipeline. | -| `CI_PIPELINE_IID` | 11.0 | all | The project-level IID (internal ID) of the current pipeline. | +| `CI_PIPELINE_ID` | 8.10 | all | The instance-level ID of the current pipeline. This is a unique ID across all projects on GitLab. | +| `CI_PIPELINE_IID` | 11.0 | all | The project-level IID (internal ID) of the current pipeline. This ID is unique for the current project. | | `CI_PIPELINE_SOURCE` | 10.0 | all | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `schedule`, `api`, `external`, `chat`, `webide`, `merge_request_event`, `external_pull_request_event`, `parent_pipeline`, [`trigger`, or `pipeline`](../triggers/README.md#authentication-tokens) (renamed to `cross_project_pipeline` since 13.0). For pipelines created before GitLab 9.5, this is displayed as `unknown`. | | `CI_PIPELINE_TRIGGERED` | all | all | The flag to indicate that job was [triggered](../triggers/README.md) | | `CI_PIPELINE_URL` | 11.1 | 0.5 | Pipeline details URL | diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 864dfdf3484..15fd21ac32e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -472,287 +472,7 @@ The following GitLab features are used among others: ## Testing -We treat documentation as code, and so use tests in our CI pipeline to maintain the -standards and quality of the docs. The current tests, which run in CI jobs when a -merge request with new or changed docs is submitted, are: - -- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L41): - Runs several tests on the content of the docs themselves: - - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) - runs the following checks and linters: - - All cURL examples use the long flags (ex: `--header`, not `-H`). - - The `CHANGELOG.md` does not contain duplicate versions. - - No files in `doc/` are executable. - - No new `README.md` was added. - - [markdownlint](#markdownlint). - - [Vale](#vale). - - Nanoc tests: - - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L58) - checks that all internal links (ex: `[link](../index.md)`) are valid. - - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L60) - checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) - are valid. - - [`ui-docs-links lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L62) - checks that all links to docs from UI elements (`app/views` files, for example) - are linking to valid docs and anchors. - -### Run tests locally - -Apart from [previewing your changes locally](#previewing-the-changes-live), you can also run all lint checks -and Nanoc tests locally. - -#### Lint checks - -Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) -script and can be executed as follows: - -1. Navigate to the `gitlab` directory. -1. Run: - - ```shell - MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh - ``` - -Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. -If you omit it completely, it will default to the `doc/` directory. -The output should be similar to: - -```plaintext -=> Linting documents at path /path/to/gitlab as <user>... -=> Checking for cURL short options... -=> Checking for CHANGELOG.md duplicate entries... -=> Checking /path/to/gitlab/doc for executable permissions... -=> Checking for new README.md files... -=> Linting markdown style... -=> Linting prose... -✔ 0 errors, 0 warnings and 0 suggestions in 1 file. -✔ Linting passed -``` - -Note that this requires you to either have the required lint tools installed on your machine, -or a working Docker installation, in which case an image with these tools pre-installed will be used. - -#### Nanoc tests - -To execute Nanoc tests locally: - -1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. -1. Run: - - ```shell - # Check for broken internal links - bundle exec nanoc check internal_links - - # Check for broken external links (might take a lot of time to complete). - # This test is set to be allowed to fail and is run only in the gitlab-docs project CI - bundle exec nanoc check internal_anchors - ``` - -#### `ui-docs-links` test - -The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from -UI elements (`app/views` files, for example) are linking to valid docs and anchors. - -To run the `ui-docs-links` test locally: - -1. Open the `gitlab` directory in a terminal window. -1. Run: - - ```shell - bundle exec haml-lint -i DocumentationLinks - ``` - -If you receive an error the first time you run this test, run `bundle install`, which -installs GitLab's dependencies, and try again. - -If you don't want to install all of GitLab's dependencies to test the links, you can: - -1. Open the `gitlab` directory in a terminal window. -1. Install `haml-lint`: - - ```shell - gem install haml_lint - ``` - -1. Run: - - ```shell - haml-lint -i DocumentationLinks - ``` - -If you manually install `haml-lint` with this process, it will not update automatically -and you should make sure your version matches the version used by GitLab. - -### Local linters - -To help adhere to the [documentation style guidelines](styleguide.md), and improve the content -added to documentation, [install documentation linters](#install-linters) and -[integrate them with your code editor](#configure-editors). - -At GitLab, we mostly use: - -- [markdownlint](#markdownlint) -- [Vale](#vale) - -#### markdownlint - -[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows -[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is -used by the [`docs-lint` test](#testing). - -Our [Documentation Style Guide](styleguide.md#markdown) and -[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must -be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations -from those guidelines. - -markdownlint configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) - -This configuration is also used within build pipelines. - -You can use markdownlint: - -- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). - -#### Vale - -[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the -English language. Vale's configuration is stored in the -[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root -directory of projects. - -Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of -several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the -documentation directory of projects. - -Vale configuration is found in the following projects: - -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) - -This configuration is also used within build pipelines. - -You can use Vale: - -- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). -- [Within a code editor](#configure-editors). -- [In a `pre-commit` hook](#configure-pre-commit-hooks). Vale only reports errors in the - `pre-commit` hook (the same configuration as the CI/CD pipelines), and does not report suggestions - or warnings. - -#### Install linters - -At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in -build pipelines: - -1. Install `markdownlint-cli`, using either: - - - `npm`: - - ```shell - npm install -g markdownlint-cli - ``` - - - `yarn`: - - ```shell - yarn global add markdownlint-cli - ``` - - We recommend installing the version of `markdownlint-cli` currently used in the documentation - linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). - -1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using - `brew` for macOS, run: - - ```shell - brew install vale - ``` - - We recommend installing the version of Vale currently used in the documentation linting - [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). - -In addition to using markdownlint and Vale at the command line, these tools can be -[integrated with your code editor](#configure-editors). - -#### Configure editors - -To configure markdownlint within your editor, install one of the following as appropriate: - -- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) -- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [Atom](https://atom.io/packages/linter-node-markdownlint) -- [Vim](https://github.com/dense-analysis/ale) - -To configure Vale within your editor, install one of the following as appropriate: - -- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). -- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). - You don't need Vale Server to use the plugin. You can configure the plugin to - [display only a subset of alerts](#show-subset-of-vale-alerts). -- [Vim](https://github.com/dense-analysis/ale). - -We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). - -#### Configure pre-commit hooks - -Git [pre-commit hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to -run tests or other processes before committing to a branch, with the ability to not commit to the branch if -failures occur with these tests. - -[`lefthook`](https://github.com/Arkweid/lefthook) is a Git hooks manager, making configuring, -installing, and removing Git hooks easy. - -Configuration for `left` is available in the [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml) -file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. - -To set up `lefthook` for documentation linting, see -[Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis). - -#### Show subset of Vale alerts - -You can set Visual Studio Code to display only a subset of Vale alerts when viewing files: - -1. Go to **Preferences > Settings > Extensions > Vale**. -1. In **Vale CLI: Min Alert Level**, select the minimum alert level you want displayed in files. - -To display only a subset of Vale alerts when running Vale from the command line, use -the `--minAlertLevel` flag, which accepts `error`, `warning`, or `suggestion`. Combine it with `--config` -to point to the configuration file within the project, if needed: - -```shell -vale --config .vale.ini --minAlertLevel error doc/**/*.md -``` - -Omit the flag to display all alerts, including `suggestion` level alerts. - -#### Disable Vale tests - -You can disable a specific Vale linting rule or all Vale linting rules for any portion of a -document: - -- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a - `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename - of a test in the - [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) - directory. -- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a - `<!-- vale on -->` tag after the text. - -Whenever possible, exclude only the problematic rule and line(s). - -For more information, see -[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). +For more information on documentation testing, see [Documentation testing](testing.md) ## Danger Bot diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index e6cea6bad1c..38d7b2bcfb7 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -181,8 +181,8 @@ have `/help`. HTML is permitted if: ### Markdown Rules GitLab ensures that the Markdown used across all documentation is consistent, as -well as easy to review and maintain, by [testing documentation changes](index.md#testing) -with [markdownlint](index.md#markdownlint). This lint test fails when any +well as easy to review and maintain, by [testing documentation changes](testing.md) +with [markdownlint](testing.md#markdownlint). This lint test fails when any document has an issue with Markdown formatting that may cause the page to render incorrectly within GitLab. It will also fail when a document is using non-standard Markdown (which may render correctly, but is not the current diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md new file mode 100644 index 00000000000..8894d7f9ca8 --- /dev/null +++ b/doc/development/documentation/testing.md @@ -0,0 +1,292 @@ +--- +stage: none +group: Documentation Guidelines +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +description: Learn how to contribute to GitLab Documentation. +--- + +# Documentation testing + +We treat documentation as code, and so use tests in our CI pipeline to maintain the +standards and quality of the docs. The current tests, which run in CI jobs when a +merge request with new or changed docs is submitted, are: + +- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L41): + Runs several tests on the content of the docs themselves: + - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) + runs the following checks and linters: + - All cURL examples use the long flags (ex: `--header`, not `-H`). + - The `CHANGELOG.md` does not contain duplicate versions. + - No files in `doc/` are executable. + - No new `README.md` was added. + - [markdownlint](#markdownlint). + - [Vale](#vale). + - Nanoc tests: + - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L58) + checks that all internal links (ex: `[link](../index.md)`) are valid. + - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L60) + checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`) + are valid. + - [`ui-docs-links lint`](https://gitlab.com/gitlab-org/gitlab/-/blob/0b562014f7b71f98540e682c8d662275f0011f2f/.gitlab/ci/docs.gitlab-ci.yml#L62) + checks that all links to docs from UI elements (`app/views` files, for example) + are linking to valid docs and anchors. + +## Run tests locally + +Apart from [previewing your changes locally](index.md#previewing-the-changes-live), you can also run all lint checks +and Nanoc tests locally. + +### Lint checks + +Lint checks are performed by the [`lint-doc.sh`](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh) +script and can be executed as follows: + +1. Navigate to the `gitlab` directory. +1. Run: + + ```shell + MD_DOC_PATH=path/to/my_doc.md scripts/lint-doc.sh + ``` + +Where `MD_DOC_PATH` points to the file or directory you would like to run lint checks for. +If you omit it completely, it defaults to the `doc/` directory. +The output should be similar to: + +```plaintext +=> Linting documents at path /path/to/gitlab as <user>... +=> Checking for cURL short options... +=> Checking for CHANGELOG.md duplicate entries... +=> Checking /path/to/gitlab/doc for executable permissions... +=> Checking for new README.md files... +=> Linting markdown style... +=> Linting prose... +✔ 0 errors, 0 warnings and 0 suggestions in 1 file. +✔ Linting passed +``` + +This requires you to either: + +- Have the required lint tools installed on your machine. +- A working Docker installation, in which case an image with these tools pre-installed is used. + +### Nanoc tests + +To execute Nanoc tests locally: + +1. Navigate to the [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. +1. Run: + + ```shell + # Check for broken internal links + bundle exec nanoc check internal_links + + # Check for broken external links (might take a lot of time to complete). + # This test is set to be allowed to fail and is run only in the gitlab-docs project CI + bundle exec nanoc check internal_anchors + ``` + +### `ui-docs-links` test + +The `ui-docs-links lint` job uses `haml-lint` to test that all links to docs from +UI elements (`app/views` files, for example) are linking to valid docs and anchors. + +To run the `ui-docs-links` test locally: + +1. Open the `gitlab` directory in a terminal window. +1. Run: + + ```shell + bundle exec haml-lint -i DocumentationLinks + ``` + +If you receive an error the first time you run this test, run `bundle install`, which +installs GitLab's dependencies, and try again. + +If you don't want to install all of GitLab's dependencies to test the links, you can: + +1. Open the `gitlab` directory in a terminal window. +1. Install `haml-lint`: + + ```shell + gem install haml_lint + ``` + +1. Run: + + ```shell + haml-lint -i DocumentationLinks + ``` + +If you manually install `haml-lint` with this process, it does not update automatically +and you should make sure your version matches the version used by GitLab. + +## Local linters + +To help adhere to the [documentation style guidelines](styleguide.md), and improve the content +added to documentation, [install documentation linters](#install-linters) and +[integrate them with your code editor](#configure-editors). + +At GitLab, we mostly use: + +- [markdownlint](#markdownlint) +- [Vale](#vale) + +### markdownlint + +[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown syntax follows +[certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules), and is +used by the `docs-lint` test. + +Our [Documentation Style Guide](styleguide.md#markdown) and +[Markdown Guide](https://about.gitlab.com/handbook/markdown-guide/) elaborate on which choices must +be made when selecting Markdown syntax for GitLab documentation. This tool helps catch deviations +from those guidelines. + +markdownlint configuration is found in the following projects: + +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) + +This configuration is also used within build pipelines. + +You can use markdownlint: + +- [On the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--). +- [Within a code editor](#configure-editors). +- [In a `pre-push` hook](#configure-pre-push-hooks). + +### Vale + +[Vale](https://errata-ai.gitbook.io/vale/) is a grammar, style, and word usage linter for the +English language. Vale's configuration is stored in the +[`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/blob/master/.vale.ini) file located in the root +directory of projects. + +Vale supports creating [custom tests](https://errata-ai.github.io/vale/styles/) that extend any of +several types of checks, which we store in the `.linting/vale/styles/gitlab` directory within the +documentation directory of projects. + +Vale configuration is found in the following projects: + +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/master/docs/.vale/gitlab) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/-/tree/master/doc/.vale/gitlab) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/.vale/gitlab) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/master/doc/.vale/gitlab) + +This configuration is also used within build pipelines. + +You can use Vale: + +- [On the command line](https://errata-ai.gitbook.io/vale/getting-started/usage). +- [Within a code editor](#configure-editors). +- [In a Git hook](#configure-pre-push-hooks). Vale only reports errors in the Git hook (the same + configuration as the CI/CD pipelines), and does not report suggestions or warnings. + +### Install linters + +At a minimum, install [markdownlint](#markdownlint) and [Vale](#vale) to match the checks run in +build pipelines: + +1. Install `markdownlint-cli`, using either: + + - `npm`: + + ```shell + npm install -g markdownlint-cli + ``` + + - `yarn`: + + ```shell + yarn global add markdownlint-cli + ``` + + We recommend installing the version of `markdownlint-cli` currently used in the documentation + linting [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L420). + +1. Install [`vale`](https://github.com/errata-ai/vale/releases). For example, to install using + `brew` for macOS, run: + + ```shell + brew install vale + ``` + + We recommend installing the version of Vale currently used in the documentation linting + [Docker image](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/.gitlab-ci.yml#L419). + +In addition to using markdownlint and Vale at the command line, these tools can be +[integrated with your code editor](#configure-editors). + +### Configure editors + +To configure markdownlint within your editor, install one of the following as appropriate: + +- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint) +- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [Atom](https://atom.io/packages/linter-node-markdownlint) +- [Vim](https://github.com/dense-analysis/ale) + +To configure Vale within your editor, install one of the following as appropriate: + +- The Sublime Text [`SublimeLinter-contrib-vale` plugin](https://packagecontrol.io/packages/SublimeLinter-contrib-vale). +- The Visual Studio Code [`errata-ai.vale-server` extension](https://marketplace.visualstudio.com/items?itemName=errata-ai.vale-server). + You don't need Vale Server to use the plugin. You can configure the plugin to + [display only a subset of alerts](#show-subset-of-vale-alerts). +- [Vim](https://github.com/dense-analysis/ale). + +We don't use [Vale Server](https://errata-ai.github.io/vale/#using-vale-with-a-text-editor-or-another-third-party-application). + +### Configure pre-push hooks + +Git [pre-push hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) allow Git users to: + +- Run tests or other processes before pushing a branch. +- Avoid pushing a branch if failures occur with these tests. + +[`lefthook`](https://github.com/Arkweid/lefthook) is a Git hooks manager, making configuring, +installing, and removing Git hooks easy. + +Configuration for `lefthook` is available in the [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml) +file for the [`gitlab`](https://gitlab.com/gitlab-org/gitlab) project. + +To set up `lefthook` for documentation linting, see +[Pre-push static analysis](../contributing/style_guides.md#pre-push-static-analysis). + +### Show subset of Vale alerts + +You can set Visual Studio Code to display only a subset of Vale alerts when viewing files: + +1. Go to **Preferences > Settings > Extensions > Vale**. +1. In **Vale CLI: Min Alert Level**, select the minimum alert level you want displayed in files. + +To display only a subset of Vale alerts when running Vale from the command line, use +the `--minAlertLevel` flag, which accepts `error`, `warning`, or `suggestion`. Combine it with `--config` +to point to the configuration file within the project, if needed: + +```shell +vale --config .vale.ini --minAlertLevel error doc/**/*.md +``` + +Omit the flag to display all alerts, including `suggestion` level alerts. + +### Disable Vale tests + +You can disable a specific Vale linting rule or all Vale linting rules for any portion of a +document: + +- To disable a specific rule, add a `<!-- vale gitlab.rulename = NO -->` tag before the text, and a + `<!-- vale gitlab.rulename = YES -->` tag after the text, replacing `rulename` with the filename + of a test in the + [GitLab styles](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.linting/vale/styles/gitlab) + directory. +- To disable all Vale linting rules, add a `<!-- vale off -->` tag before the text, and a + `<!-- vale on -->` tag after the text. + +Whenever possible, exclude only the problematic rule and line(s). + +For more information, see +[Vale's documentation](https://errata-ai.gitbook.io/vale/getting-started/markup#markup-based-configuration). diff --git a/locale/gitlab.pot b/locale/gitlab.pot index 675c700c3e7..60a987778d5 100644 --- a/locale/gitlab.pot +++ b/locale/gitlab.pot @@ -7129,6 +7129,9 @@ msgstr "" msgid "Consistency guarantee method" msgstr "" +msgid "Contact Sales to upgrade" +msgstr "" + msgid "Contact sales to upgrade" msgstr "" @@ -12801,7 +12804,7 @@ msgstr "" msgid "Go back (while searching for files)" msgstr "" -msgid "Go back to %{startTag}Open issues%{endTag} and select some issues to add to your board." +msgid "Go back to %{tagStart}Open issues%{tagEnd} and select some issues to add to your board." msgstr "" msgid "Go full screen" @@ -13789,9 +13792,6 @@ msgstr "" msgid "How many users will be evaluating the trial?" msgstr "" -msgid "How to upgrade" -msgstr "" - msgid "However, you are already a member of this %{member_source}. Sign in using a different account to accept the invitation." msgstr "" diff --git a/spec/features/boards/add_issues_modal_spec.rb b/spec/features/boards/add_issues_modal_spec.rb index 00efca5d3a8..f941adca233 100644 --- a/spec/features/boards/add_issues_modal_spec.rb +++ b/spec/features/boards/add_issues_modal_spec.rb @@ -87,11 +87,12 @@ RSpec.describe 'Issue Boards add issue modal', :js do end end - it 'shows selected issues' do + it 'shows selected issues tab and empty state message' do page.within('.add-issues-modal') do click_link 'Selected issues' expect(page).not_to have_selector('.board-card') + expect(page).to have_content("Go back to Open issues and select some issues to add to your board.") end end @@ -147,7 +148,7 @@ RSpec.describe 'Issue Boards add issue modal', :js do end end - context 'selecing issues' do + context 'selecting issues' do it 'selects single issue' do page.within('.add-issues-modal') do first('.board-card .board-card-number').click @@ -206,7 +207,7 @@ RSpec.describe 'Issue Boards add issue modal', :js do end end - it 'selects all that arent already selected' do + it "selects all that aren't already selected" do page.within('.add-issues-modal') do first('.board-card .board-card-number').click diff --git a/spec/features/issues/gfm_autocomplete_spec.rb b/spec/features/issues/gfm_autocomplete_spec.rb index 3b81f199267..06f79f94e8d 100644 --- a/spec/features/issues/gfm_autocomplete_spec.rb +++ b/spec/features/issues/gfm_autocomplete_spec.rb @@ -814,6 +814,13 @@ RSpec.describe 'GFM autocomplete', :js do end end + context 'issues' do + let(:object) { issue } + let(:expected_body) { object.to_reference } + + it_behaves_like 'autocomplete suggestions' + end + context 'merge requests' do let(:object) { create(:merge_request, source_project: project) } let(:expected_body) { object.to_reference } @@ -821,6 +828,27 @@ RSpec.describe 'GFM autocomplete', :js do it_behaves_like 'autocomplete suggestions' end + context 'project snippets' do + let!(:object) { create(:project_snippet, project: project, title: 'code snippet') } + let(:expected_body) { object.to_reference } + + it_behaves_like 'autocomplete suggestions' + end + + context 'label' do + let!(:object) { label } + let(:expected_body) { object.title } + + it_behaves_like 'autocomplete suggestions' + end + + context 'milestone' do + let!(:object) { create(:milestone, project: project) } + let(:expected_body) { object.to_reference } + + it_behaves_like 'autocomplete suggestions' + end + context 'when other notes are destroyed' do let!(:discussion) { create(:discussion_note_on_issue, noteable: issue, project: issue.project) } |