diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/merge_requests.md | 4 | ||||
| -rw-r--r-- | doc/api/projects.md | 3 | ||||
| -rw-r--r-- | doc/ci/quick_start/README.md | 2 | ||||
| -rw-r--r-- | doc/ci/yaml/README.md | 74 | ||||
| -rw-r--r-- | doc/development/feature_flags.md | 11 | ||||
| -rw-r--r-- | doc/install/kubernetes/gitlab_chart.md | 1 | ||||
| -rw-r--r-- | doc/user/admin_area/settings/usage_statistics.md | 6 | ||||
| -rw-r--r-- | doc/user/instance_statistics/index.md | 3 | ||||
| -rw-r--r-- | doc/user/markdown.md | 46 | ||||
| -rw-r--r-- | doc/user/project/integrations/webhooks.md | 4 |
10 files changed, 135 insertions, 19 deletions
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 58d05a70d05..9e6676d62fe 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -352,6 +352,7 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request - `render_html` (optional) - If `true` response includes rendered HTML for title and description +- `include_diverged_commits_count` (optional) - If `true` response includes the commits behind the target branch ```json { @@ -435,7 +436,8 @@ Parameters: "username" : "root", "id" : 1, "name" : "Administrator" - } + }, + "diverged_commits_count": 2 } ``` diff --git a/doc/api/projects.md b/doc/api/projects.md index 86acb96357d..7e8b7c4b502 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1334,6 +1334,7 @@ GET /projects/:id/hooks/:hook_id "url": "http://example.com/hook", "project_id": 3, "push_events": true, + "push_events_branch_filter": "", "issues_events": true, "confidential_issues_events": true, "merge_requests_events": true, @@ -1360,6 +1361,7 @@ POST /projects/:id/hooks | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | +| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | | `issues_events` | boolean | no | Trigger hook on issues events | | `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | @@ -1385,6 +1387,7 @@ PUT /projects/:id/hooks/:hook_id | `hook_id` | integer | yes | The ID of the project hook | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | +| `push_events_branch_filter` | string | no | Trigger hook on push events for matching branches only | | `issues_events` | boolean | no | Trigger hook on issues events | | `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | | `merge_requests_events` | boolean | no | Trigger hook on merge requests events | diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 47e658f610e..636117536a2 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -7,7 +7,7 @@ projects. GitLab offers a [continuous integration][ci] service. If you [add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository, and configure your GitLab project to use a [Runner], then each commit or -push, triggers your CI [pipeline]. +push triggers your CI [pipeline]. The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it runs a pipeline with three [stages]: `build`, `test`, and `deploy`. You don't need to diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index e93060fec85..c1ebe39e076 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -56,6 +56,7 @@ A job is defined by a list of parameters that define the job behavior. | Keyword | Required | Description | |---------------|----------|-------------| | script | yes | Defines a shell script which is executed by Runner | +| extends | no | Defines a configuration entry that this job is going to inherit from | | image | no | Use docker image, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | | services | no | Use docker services, covered in [Using Docker Images](../docker/using_docker_images.md#define-image-and-services-from-gitlab-ciyml) | | stage | no | Defines a job stage (default: `test`) | @@ -75,6 +76,79 @@ A job is defined by a list of parameters that define the job behavior. | coverage | no | Define code coverage settings for a given job | | retry | no | Define how many times a job can be auto-retried in case of a failure | +### `extends` + +> Introduced in GitLab 11.3 + +`extends` defines an entry name that a job, that uses `extends` is going to +inherit from. + +`extends` in an alternative to using [YAML anchors](#anchors) that is a little +more flexible and readable. + +```yaml +.tests: + only: + refs: + - branches + +rspec: + extends: .tests + script: rake rspec + stage: test + only: + variables: + - $RSPEC +``` + +In the example above the `rspec` job is going to inherit from `.tests` +template. GitLab will perform a reverse deep merge, what means that it will +merge `rspec` contents into `.tests` recursively, and it is going to result in +following configuration of the `rspec` job: + +```yaml +rspec: + script: rake rspec + stage: test + only: + refs: + - branches + variables: + - $RSPEC +``` + +`.tests` in this example is a [hidden key](#hidden-keys-jobs), but it is +possible to inherit from regular jobs as well. + +`extends` supports multi-level inheritance, however it is not recommended to +use more than three levels of inheritance. Maximum nesting level supported is +10 levels. + + +```yaml +.tests: + only: + - pushes + +.rspec: + extends: .tests + script: rake rspec + +rspec 1: + variables: + RSPEC_SUITE: '1' + extends: .rspec + +rspec 2: + variables: + RSPEC_SUITE: '2' + extends: .rspec + +spinach: + extends: .tests + script: rake spinach +``` + ### `pages` `pages` is a special job that is used to upload static content to GitLab that diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 702caacc74f..6f757f1ce7b 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -58,13 +58,20 @@ Features that are developed and are intended to be merged behind a feature flag should not include a changelog entry. The entry should be added in the merge request removing the feature flags. +In the rare case that you need the feature flag to be on automatically, use +`default_enabled: true` when checking: + +```ruby +Feature.enabled?(:feature_flag, project, default_enabled: true) +``` + ### Specs In the test environment `Feature.enabled?` is stubbed to always respond to `true`, so we make sure behavior under feature flag doesn't go untested in some non-specific contexts. - -If you need to test the feature flag in a different state, you need to stub it with: + +If you need to test the feature flag in a different state, you need to stub it with: ```ruby stub_feature_flags(my_feature_flag: false) diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md index 8852570b254..cd380b1dd01 100644 --- a/doc/install/kubernetes/gitlab_chart.md +++ b/doc/install/kubernetes/gitlab_chart.md @@ -133,6 +133,7 @@ Once your GitLab Chart is installed, configuration changes and chart updates should be done using `helm upgrade`: ```sh +helm repo update helm upgrade --reuse-values gitlab gitlab/gitlab ``` diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index b7427592e10..35a9d7adb28 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -23,7 +23,7 @@ GitLab Inc. collects your instance's version and hostname (through the HTTP referer) as part of the version check. No other information is collected. This information is used, among other things, to identify to which versions -patches will need to be back ported, making sure active GitLab instances remain +patches will need to be backported, making sure active GitLab instances remain secure. If you disable version check, this information will not be collected. Enable or @@ -33,7 +33,8 @@ disable the version check at **Admin area > Settings > Usage statistics**. > [Introduced][ee-557] in GitLab Enterprise Edition 8.10. More statistics [were added][ee-735] in GitLab Enterprise Edition -8.12. [Moved to GitLab Community Edition][ce-23361] in 9.1. +8.12. [Moved to GitLab Core][ce-23361] in 9.1. More statistics +[were added][ee-6602] in GitLab Ultimate 11.2. GitLab sends a weekly payload containing usage data to GitLab Inc. The usage ping uses high-level data to help our product, support, and sales teams. It does @@ -79,3 +80,4 @@ Statistics visibility section under **Admin area > Settings > Usage statistics** [ee-557]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/557 [ee-735]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/735 [ce-23361]: https://gitlab.com/gitlab-org/gitlab-ce/issues/23361 +[ee-6602]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6602 diff --git a/doc/user/instance_statistics/index.md b/doc/user/instance_statistics/index.md index a4eca89b7fe..22f76f728e3 100644 --- a/doc/user/instance_statistics/index.md +++ b/doc/user/instance_statistics/index.md @@ -10,9 +10,6 @@ and can be accessed via the top bar.  -For the statistics to show up, [usage ping must be enabled](../admin_area/settings/usage_statistics.md#usage-ping) -by an admin in the admin settings area. - There are two kinds of statistics: - [Conversational Development (ConvDev) Index](convdev.md): Provides an overview of your entire instance's feature usage. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 6203561265b..e9c8980a3e6 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -7,13 +7,13 @@ > this document currently work on our documentation website. > > For the best result, we encourage you to check this document out as rendered -by GitLab: [markdown.md] +> by GitLab: [markdown.md] -_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. Previous content, wiki pages and Markdown files (`.md`) in the repositories are still processed using the [Redcarpet Ruby library][redcarpet]._ +_GitLab uses (as of 11.1) the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]._ _Where there are significant differences, we will try to call them out in this document._ -GitLab uses "GitLab Flavored Markdown" (GFM). It extends the standard Markdown in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). +GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specification][commonmark-spec] (which is based on standard Markdown) in a few significant ways to add some useful functionality. It was inspired by [GitHub Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). You can use GFM in the following areas: @@ -22,18 +22,46 @@ You can use GFM in the following areas: - merge requests - milestones - snippets (the snippet must be named with a `.md` extension) -- wiki pages (currently only rendered by Redcarpet) -- markdown documents inside the repository (currently only rendered by Redcarpet) +- wiki pages +- markdown documents inside the repository You can also use other rich text files in GitLab. You might have to install a dependency to do so. Please see the [github-markup gem readme](https://github.com/gitlabhq/markup#markups) for more information. +### Transitioning to CommonMark + +You may have Markdown documents in your repository that were written using some of the nuances of RedCarpet's version of Markdown. Since CommonMark uses a slightly stricter syntax, these documents may now display a little strangely since we've transitioned to CommonMark. Numbered lists with nested lists in particular can be displayed incorrectly. + +It is usually quite easy to fix. In the case of a nested list such as this: + +```markdown +1. Chocolate + - dark + - milk +``` + +simply add a space to each nested item: + +```markdown +1. Chocolate + - dark + - milk +``` + +In the documentation below, we try to highlight some of the differences. + +If you have a need to view a document using RedCarpet, you can add the token `legacy_render=1` to the end of the url, like this: + +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md?legacy_render=1 + +If you have a large volume of Markdown files, it can be tedious to determine if they will be displayed correctly or not. You can use the [diff_redcarpet_cmark](https://gitlab.com/digitalmoksha/diff_redcarpet_cmark) tool (not an officially supported product) to generate a list of files and differences between how RedCarpet and CommonMark render the files. It can give you a great idea if anything needs to be changed - many times nothing will need to changed. + ### Newlines > If this is not rendered correctly, see https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines -GFM honors the markdown specification in how [paragraphs and line breaks are handled](https://daringfireball.net/projects/markdown/syntax#p). +GFM honors the markdown specification in how [paragraphs and line breaks are handled][commonmark-spec]. A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. Line-breaks, or soft returns, are rendered if you end a line with two or more spaces: @@ -979,8 +1007,9 @@ A link starting with a `/` is relative to the wiki root. ## References - This document leveraged heavily from the [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). -- The [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. -- [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown. +- The original [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. +- The detailed specification for CommonMark can be found in the [CommonMark Spec][commonmark-spec] +- The [CommonMark Dingus](http://try.commonmark.org) is a handy tool for testing CommonMark syntax. [^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com [^2]: This is my awesome footnote. @@ -993,3 +1022,4 @@ A link starting with a `/` is relative to the wiki root. [katex-subset]: https://github.com/Khan/KaTeX/wiki/Function-Support-in-KaTeX "Macros supported by KaTeX" [asciidoctor-manual]: http://asciidoctor.org/docs/user-manual/#activating-stem-support "Asciidoctor user manual" [commonmarker]: https://github.com/gjtorikian/commonmarker +[commonmark-spec]: https://spec.commonmark.org/current/ diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 770b1810da1..a64e080d6b7 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -65,8 +65,8 @@ Below are described the supported events. Triggered when you push to the repository except when pushing tags. -> **Note:** When more than 20 commits are pushed at once, the `commits` web hook - attribute will only contain the first 20 for performance reasons. Loading +> **Note:** When more than 20 commits are pushed at once, the `commits` web hook + attribute will only contain the first 20 for performance reasons. Loading detailed commit data is expensive. Note that despite only 20 commits being present in the `commits` attribute, the `total_commits_count` attribute will contain the actual total. |