diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.vale/gitlab/ContractionsDiscard.yml | 32 | ||||
| -rw-r--r-- | doc/.vale/gitlab/ContractionsKeep.yml | 25 | ||||
| -rw-r--r-- | doc/administration/operations/puma.md | 7 | ||||
| -rw-r--r-- | doc/api/deployments.md | 34 | ||||
| -rw-r--r-- | doc/development/cicd/templates.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide.md | 41 | ||||
| -rw-r--r-- | doc/development/fe_guide/graphql.md | 168 | ||||
| -rw-r--r-- | doc/development/licensed_feature_availability.md | 4 | ||||
| -rw-r--r-- | doc/user/application_security/sast/index.md | 3 | ||||
| -rw-r--r-- | doc/user/project/code_owners.md | 64 | ||||
| -rw-r--r-- | doc/user/project/img/code_owners_invite_members_v13_4.png | bin | 0 -> 55189 bytes | |||
| -rw-r--r-- | doc/user/project/img/code_owners_members_v13_4.png | bin | 0 -> 46547 bytes |
12 files changed, 235 insertions, 145 deletions
diff --git a/doc/.vale/gitlab/ContractionsDiscard.yml b/doc/.vale/gitlab/ContractionsDiscard.yml deleted file mode 100644 index 698fda86b5b..00000000000 --- a/doc/.vale/gitlab/ContractionsDiscard.yml +++ /dev/null @@ -1,32 +0,0 @@ ---- -# Suggestion: gitlab.ContractionsDiscard -# -# Suggests a list of agreed-upon contractions to discard. -# -# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles -extends: substitution -message: 'Use "%s" instead of "%s", for a friendly, informal tone.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language -level: suggestion -nonword: false -ignorecase: true -swap: - - # Uncommon contractions are not ok - aren't: are not - couldn't: could not - didn't: did not - doesn't: does not - hasn't: has not - how's: how is - isn't: is not - shouldn't: should not - they're: they are - wasn't: was not - weren't: were not - we've: we have - what's: what is - when's: when is - where's: where is - who's: who is - why's: why is diff --git a/doc/.vale/gitlab/ContractionsKeep.yml b/doc/.vale/gitlab/ContractionsKeep.yml deleted file mode 100644 index eeaf65e0829..00000000000 --- a/doc/.vale/gitlab/ContractionsKeep.yml +++ /dev/null @@ -1,25 +0,0 @@ ---- -# Suggestion: gitlab.ContractionsKeep -# -# Suggests a list of agreed-upon contractions to keep. -# -# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles -extends: substitution -message: 'Use "%s" instead of "%s", for a friendly, informal tone.' -link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language -level: suggestion -nonword: false -ignorecase: true -swap: - - # Common contractions are ok - it is: it's - can not: can't - cannot: can't - do not: don't - have not: haven't - that is: that's - we are: we're - would not: wouldn't - you are: you're - you have: you've diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md index 1607515dcfc..f5b09d7a978 100644 --- a/doc/administration/operations/puma.md +++ b/doc/administration/operations/puma.md @@ -58,7 +58,6 @@ plays an important role in your deployment, we suggest you benchmark to find the optimal configuration: - The safest option is to start with single-threaded Puma. When working with -Rugged, single-threaded Puma does work the same as Unicorn. - -- To force Rugged auto detect with multi-threaded Puma, you can use [feature -flags](../../development/gitaly.md#legacy-rugged-code). + Rugged, single-threaded Puma works the same as Unicorn. +- To force Rugged to be used with multi-threaded Puma, you can use + [feature flags](../../development/gitaly.md#legacy-rugged-code). diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 426b3e10ecf..b0de972160b 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -15,15 +15,15 @@ Get a list of deployments in a project. GET /projects/:id/deployments ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `order_by`| string | no | Return deployments ordered by `id` or `iid` or `created_at` or `updated_at` or `ref` fields. Default is `id` | -| `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | -| `updated_after` | datetime | no | Return deployments updated after the specified date | -| `updated_before` | datetime | no | Return deployments updated before the specified date | -| `environment` | string | no | The name of the environment to filter deployments by | -| `status` | string | no | The status to filter deployments by | +| Attribute | Type | Required | Description | +|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `order_by` | string | no | Return deployments ordered by `id` or `iid` or `created_at` or `updated_at` or `ref` fields. Default is `id` | +| `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | +| `updated_after` | datetime | no | Return deployments updated after the specified date | +| `updated_before` | datetime | no | Return deployments updated before the specified date | +| `environment` | string | no | The [name of the environment](../ci/environments/index.md#defining-environments) to filter deployments by | +| `status` | string | no | The status to filter deployments by | The status attribute can be one of the following values: @@ -278,14 +278,14 @@ Example of response POST /projects/:id/deployments ``` -| Attribute | Type | Required | Description | -|------------------|----------------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `environment` | string | yes | The name of the environment to create the deployment for | -| `sha` | string | yes | The SHA of the commit that is deployed | -| `ref` | string | yes | The name of the branch or tag that is deployed | -| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (true) or not (false) | -| `status` | string | yes | The status of the deployment | +| Attribute | Type | Required | Description | +|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `environment` | string | yes | The [name of the environment](../ci/environments/index.md#defining-environments) to create the deployment for | +| `sha` | string | yes | The SHA of the commit that is deployed | +| `ref` | string | yes | The name of the branch or tag that is deployed | +| `tag` | boolean | yes | A boolean that indicates if the deployed ref is a tag (true) or not (false) | +| `status` | string | yes | The status of the deployment | The status can be one of the following values: diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index efcc7b363ff..891555d93fc 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -16,7 +16,7 @@ All template files reside in the `lib/gitlab/ci/templates` directory, and are ca | Sub-directory | Content | [Selectable in UI](#make-sure-the-new-template-can-be-selected-in-ui) | |----------------|--------------------------------------------------------------|-----------------------------------------------------------------------| | `/AWS/*` | Cloud Deployment (AWS) related jobs | No | -| `/Jobs/*` | Auto DevOps related jobs | Yes | +| `/Jobs/*` | Auto DevOps related jobs | No | | `/Pages/*` | Static site generators for GitLab Pages (for example Jekyll) | Yes | | `/Security/*` | Security related jobs | Yes | | `/Verify/*` | Verify/testing related jobs | Yes | diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index b099d589b0f..27ef0a595da 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -540,35 +540,10 @@ tenses, words, and phrases: ### Contractions -- Use common contractions when it helps create a friendly and informal tone, - especially in tutorials, instructional documentation, and - [user interfaces](https://design.gitlab.com/content/punctuation/#contractions). - (Tested in [`Contractions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Contractions.yml).) - - <!-- vale gitlab.ContractionsKeep = NO --> - <!-- vale gitlab.ContractionsDiscard = NO --> - <!-- vale gitlab.FutureTense = NO --> - | Do | Don't | - |----------|-----------| - | it's | it is | - | can't | cannot | - | wouldn't | would not | - | you're | you are | - | you've | you have | - | haven't | have not | - | don't | do not | - | we're | we are | - | that's | that is | - | won't | will not | - -- Avoid less common contractions: - - | Do | Don't | - |--------------|-------------| - | he would | he'd | - | it will | it'll | - | should have | should've | - | there would | there'd | +Contractions can create a friendly and informal tone, especially in tutorials, instructional +documentation, and [user interfaces](https://design.gitlab.com/content/punctuation/#contractions). + +Some contractions should be avoided: - Do not use contractions with a proper noun and a verb. For example: @@ -580,13 +555,13 @@ tenses, words, and phrases: | Do | Don't | |-----------------------------|----------------------------| - | Do *not* install X with Y | *Don't* install X with Y | + | Do **not** install X with Y | **Don't** install X with Y | - Do not use contractions in reference documentation. For example: | Do | Don't | |------------------------------------------|----------------------------------------| - | Do *not* set a limit greater than 1000 | *Don't* set a limit greater than 1000 | + | Do **not** set a limit greater than 1000 | **Don't** set a limit greater than 1000 | | For `parameter1`, the default is 10 | For `parameter1`, the default's 10 | - Avoid contractions in error messages. Examples: @@ -596,10 +571,6 @@ tenses, words, and phrases: | Requests to localhost are not allowed | Requests to localhost aren't allowed | | Specified URL cannot be used | Specified URL can't be used | - <!-- vale gitlab.ContractionsKeep = YES --> - <!-- vale gitlab.ContractionsDiscard = YES --> - <!-- vale gitlab.FutureTense = YES --> - ## Text - [Write in Markdown](#markdown). diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index f5e16d377f1..a63cb95fafd 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -602,6 +602,174 @@ it('calls mutation on submitting form ', () => { }); ``` +### Testing with mocked Apollo Client + +To test the logic of Apollo cache updates, we might want to mock an Apollo Client in our unit tests. To separate tests with mocked client from 'usual' unit tests, it's recommended to create an additional component factory. This way we only create Apollo Client instance when it's necessary: + +```javascript +function createComponent() {...} + +function createComponentWithApollo() {...} +``` + +We use [`mock-apollo-client`](https://www.npmjs.com/package/mock-apollo-client) library to mock Apollo client in tests. + +```javascript +import { createMockClient } from 'mock-apollo-client'; +``` + +Then we need to inject `VueApollo` to Vue local instance (`localVue.use()` can also be called within `createComponentWithApollo()`) + +```javascript +import VueApollo from 'vue-apollo'; +import { createLocalVue } from '@vue/test-utils'; + +const localVue = createLocalVue(); +localVue.use(VueApollo); +``` + +After this, on the global `describe`, we should create a variable for `fakeApollo`: + +```javascript +describe('Some component with Apollo mock', () => { + let wrapper; + let fakeApollo +}) +``` + +Within component factory, we need to define an array of _handlers_ for every query or mutation: + +```javascript +import getDesignListQuery from '~/design_management/graphql/queries/get_design_list.query.graphql'; +import permissionsQuery from '~/design_management/graphql/queries/design_permissions.query.graphql'; +import moveDesignMutation from '~/design_management/graphql/mutations/move_design.mutation.graphql'; + +describe('Some component with Apollo mock', () => { + let wrapper; + let fakeApollo; + + function createComponentWithApollo() { + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], + [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], + ]; + } +}) +``` + +After this, we need to create a mock Apollo Client instance using a helper: + +```javascript +import createMockApollo from 'jest/helpers/mock_apollo_helper'; + +describe('Some component with Apollo mock', () => { + let wrapper; + let fakeApollo; + + function createComponentWithApollo() { + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], + [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], + ]; + + fakeApollo = createMockApollo(requestHandlers); + wrapper = shallowMount(Index, { + localVue, + apolloProvider: fakeApollo, + }); + } +}) +``` + +NOTE: **Note:** +When mocking resolved values, make sure the structure of the response is the same as actual API response: i.e. root property should be `data` for example + +When testing queries, please keep in mind they are promises, so they need to be _resolved_ to render a result. Without resolving, we can check the `loading` state of the query: + +```javascript +it('renders a loading state', () => { + createComponentWithApollo(); + + expect(wrapper.find(LoadingSpinner).exists()).toBe(true) +}); + +it('renders designs list', async () => { + createComponentWithApollo(); + + jest.runOnlyPendingTimers(); + await wrapper.vm.$nextTick(); + + expect(findDesigns()).toHaveLength(3); +}); +``` + +If we need to test a query error, we need to mock a rejected value as request handler: + +```javascript +function createComponentWithApollo() { + ... + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockRejectedValue(new Error('GraphQL error')], + ]; + ... +} +... + +it('renders error if query fails', async () => { + createComponent() + + jest.runOnlyPendingTimers(); + await wrapper.vm.$nextTick(); + + expect(wrapper.find('.test-error').exists()).toBe(true) +}) +``` + +Request handlers can also be passed to component factory as a parameter. + +Mutations could be tested the same way with a few additional `nextTick`s to get the updated result: + +```javascript +function createComponentWithApollo({ + moveHandler = jest.fn().mockResolvedValue(moveDesignMutationResponse), +}) { + moveDesignHandler = moveHandler; + + const requestHandlers = [ + [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)], + [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)], + [moveDesignMutation, moveDesignHandler], + ]; + + fakeApollo = createMockApollo(requestHandlers); + wrapper = shallowMount(Index, { + localVue, + apolloProvider: fakeApollo, + }); +} +... +it('calls a mutation with correct parameters and reorders designs', async () => { + createComponentWithApollo({}); + + wrapper.find(VueDraggable).vm.$emit('change', { + moved: { + newIndex: 0, + element: designToMove, + }, + }); + + expect(moveDesignHandler).toHaveBeenCalled(); + + await wrapper.vm.$nextTick(); + + expect( + findDesigns() + .at(0) + .props('id'), + ).toBe('2'); +}); +``` + ## Handling errors GitLab's GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data). diff --git a/doc/development/licensed_feature_availability.md b/doc/development/licensed_feature_availability.md index cf479544eea..62f5bb7e029 100644 --- a/doc/development/licensed_feature_availability.md +++ b/doc/development/licensed_feature_availability.md @@ -35,7 +35,3 @@ the instance license. ```ruby License.feature_available?(:feature_symbol) ``` - -## Enabling promo features on GitLab.com - -A paid feature can be made available to everyone on GitLab.com by enabling the feature flag `"promo_#{feature}"`. diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index db5f0d1635d..d14efb3e6a5 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -106,6 +106,7 @@ as shown in the following table: | [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | | [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | | [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | +| [Configure SAST in the UI](#configure-sast-in-the-ui) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -142,7 +143,7 @@ The results are saved as a that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. -### Configure SAST in the UI +### Configure SAST in the UI **(ULTIMATE)** > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/232862) in GitLab Ultimate 13.4. diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md index 8c7de16a7d6..9b19de44026 100644 --- a/doc/user/project/code_owners.md +++ b/doc/user/project/code_owners.md @@ -9,7 +9,6 @@ type: reference > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. -> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) added in GitLab Starter 12.1. > - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9. ## Introduction @@ -108,40 +107,53 @@ in the `.gitignore` file followed by one or more of: - A user's `@username`. - A user's email address. - The `@name` of one or more groups that should be owners of the file. +- Lines starting with `#` are escaped. -Groups must be added as [members of the project](members/index.md), -or they will be ignored. +The order in which the paths are defined is significant: the last pattern that +matches a given path will be used to find the code owners. -Starting in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/32432), -you can additionally specify groups or subgroups from the project's upper group -hierarchy as potential code owners, without having to invite them specifically -to the project. Groups outside the project's hierarchy or children beneath the -hierarchy must still be explicitly invited to the project in order to show as -Code Owners. +### Groups as Code Owners -For example, consider the following hierarchy for the example project -`example_project`: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1. +> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0. -```plaintext -group >> sub-group >> sub-subgroup >> example_project >> file.md -``` +Groups and subgroups members are inherited as eligible Code Owners to a +project, as long as the hierarchy is respected. + +For example, consider a given group called "Group X" (slug `group-x`) and a +"Subgroup Y" (slug `group-x/subgroup-y`) that belongs to the Group X, and +suppose you have a project called "Project A" within the group and a +"Project B" within the subgroup. -Any of the following groups would be eligible to be specified as code owners: +The eligible Code Owners to Project B are both the members of the Group X and +the Subgroup Y. And the eligible Code Owners to the Project A are just the +members of the Group X, given that Project A doesn't belong to the Subgroup Y: -- `@group` -- `@group/sub-group` -- `@group/sub-group/sub-subgroup` + -In addition, any groups that have been invited to the project using the -**Members** tool will also be recognized as eligible code owners. +But you have the option to [invite](members/share_project_with_groups.md) +the Subgroup Y to the Project A so that their members also become eligible +Code Owners: -The order in which the paths are defined is significant: the last -pattern that matches a given path will be used to find the code -owners. + -Starting a line with a `#` indicates a comment. This needs to be -escaped using `\#` to address files for which the name starts with a -`#`. +Once invited, any member (`@user`) of the group or subgroup can be set +as Code Owner to files of the Project A or B, as well as the entire Group X +(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below: + +```plaintext +# A member of the group or subgroup as Code Owner to a file +file.md @user + +# All group members as Code Owners to a file +file.md @group-x + +# All subgroup members as Code Owners to a file +file.md @group-x/subgroup-y + +# All group and subgroup members as Code Owners to a file +file.md @group-x @group-x/subgroup-y +``` ### Code Owners Sections **(PREMIUM)** diff --git a/doc/user/project/img/code_owners_invite_members_v13_4.png b/doc/user/project/img/code_owners_invite_members_v13_4.png Binary files differnew file mode 100644 index 00000000000..852a5f68b36 --- /dev/null +++ b/doc/user/project/img/code_owners_invite_members_v13_4.png diff --git a/doc/user/project/img/code_owners_members_v13_4.png b/doc/user/project/img/code_owners_members_v13_4.png Binary files differnew file mode 100644 index 00000000000..e37fe72cd6e --- /dev/null +++ b/doc/user/project/img/code_owners_members_v13_4.png |
