Skip to content
Snippets Groups Projects
Verified Commit 1e5eb76a authored by Amy Qualls's avatar Amy Qualls :leopard: Committed by GitLab
Browse files

Style cleanups for Create docs

Handle more line-level cleanups on this documentation. Address
Vale-identified problems, and bring closer to our expected style.
parent c975e3ad
No related branches found
No related tags found
3 merge requests!181325Fix ambiguous `created_at` in project.rb,!181037Style cleanups for Create docs, part 3,!180727Resolve "Extend job archival mechanism to the whole pipeline"
...@@ -32,7 +32,7 @@ Not all discussion types are equally available in the API: ...@@ -32,7 +32,7 @@ Not all discussion types are equally available in the API:
- **Discussion**: A collection, often called a _thread_, of `DiscussionNotes` in - **Discussion**: A collection, often called a _thread_, of `DiscussionNotes` in
an issue, merge request, commit, or snippet. an issue, merge request, commit, or snippet.
- **DiscussionNote**: An individual item in a discussion on an issue, merge request, - **DiscussionNote**: An individual item in a discussion on an issue, merge request,
commit, or snippet. These are not returned as part of the Note API. commit, or snippet. Items of type `DiscussionNote` are not returned as part of the Note API.
Not available in the [Events API](events.md). Not available in the [Events API](events.md).
## Discussions pagination ## Discussions pagination
......
...@@ -13,11 +13,11 @@ DETAILS: ...@@ -13,11 +13,11 @@ DETAILS:
> - Flag `group_protected_branches` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116779) [flag](../administration/feature_flags.md) to `allow_protected_branches_for_group` GitLab 15.11. > - Flag `group_protected_branches` [renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116779) [flag](../administration/feature_flags.md) to `allow_protected_branches_for_group` GitLab 15.11.
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/500250) in GitLab 17.6. Feature flag `group_protected_branches` removed. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/500250) in GitLab 17.6. Feature flag `group_protected_branches` removed.
Use the Group-level protected branches API to manage protected branch rules. Use the protected branches API for groups to manage protected branch rules.
It provides endpoints to list, create, update, and delete protected branch rules that apply to projects within a group. It provides endpoints to list, create, update, and delete protected branch rules that apply to projects belonging to a group.
WARNING: WARNING:
Group-level protected branch settings are restricted to top-level groups only. Protected branch settings for groups are restricted to top-level groups only.
## Valid access levels ## Valid access levels
......
...@@ -300,7 +300,7 @@ response attributes: ...@@ -300,7 +300,7 @@ response attributes:
| `[].labels` | array | Labels of the merge request. | | `[].labels` | array | Labels of the merge request. |
| `[].merge_commit_sha` | string | SHA of the merge request commit. Returns `null` until merged. | | `[].merge_commit_sha` | string | SHA of the merge request commit. Returns `null` until merged. |
| `[].merge_status` | string | Status of the merge request. Can be `unchecked`, `checking`, `can_be_merged`, `cannot_be_merged`, or `cannot_be_merged_recheck`. Affects the `has_conflicts` property. For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6. Use `detailed_merge_status` instead. | | `[].merge_status` | string | Status of the merge request. Can be `unchecked`, `checking`, `can_be_merged`, `cannot_be_merged`, or `cannot_be_merged_recheck`. Affects the `has_conflicts` property. For important notes on response data, see [Single merge request response notes](#single-merge-request-response-notes). [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/3169#note_1162532204) in GitLab 15.6. Use `detailed_merge_status` instead. |
| `[].merge_user` | object | User who merged this merge request, the user who set it to auto-merge, or `null`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/349031) in GitLab 14.7. | | `[].merge_user` | object | User who merged this merge request, the user who set it to auto-merge, or `null`. |
| `[].merge_when_pipeline_succeeds` | boolean | Indicates if the merge has been set to merge when its pipeline succeeds. | | `[].merge_when_pipeline_succeeds` | boolean | Indicates if the merge has been set to merge when its pipeline succeeds. |
| `[].merged_at` | datetime | Timestamp of when the merge request was merged. | | `[].merged_at` | datetime | Timestamp of when the merge request was merged. |
| `[].merged_by` | object | User who merged this merge request or set it to auto-merge. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350534) in GitLab 14.7, and scheduled for removal in [API version 5](https://gitlab.com/groups/gitlab-org/-/epics/8115). Use `merge_user` instead. | | `[].merged_by` | object | User who merged this merge request or set it to auto-merge. [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350534) in GitLab 14.7, and scheduled for removal in [API version 5](https://gitlab.com/groups/gitlab-org/-/epics/8115). Use `merge_user` instead. |
...@@ -316,7 +316,7 @@ response attributes: ...@@ -316,7 +316,7 @@ response attributes:
| `[].source_project_id` | integer | ID of the merge request source project. Equal to `target_project_id`, unless the merge request originates from a fork. | | `[].source_project_id` | integer | ID of the merge request source project. Equal to `target_project_id`, unless the merge request originates from a fork. |
| `[].squash` | boolean | If `true`, squash all commits into a single commit on merge. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) might override this value. Use `squash_on_merge` instead to take project squash options into account. | | `[].squash` | boolean | If `true`, squash all commits into a single commit on merge. [Project settings](../user/project/merge_requests/squash_and_merge.md#configure-squash-options-for-a-project) might override this value. Use `squash_on_merge` instead to take project squash options into account. |
| `[].squash_commit_sha` | string | SHA of the squash commit. Empty until merged. | | `[].squash_commit_sha` | string | SHA of the squash commit. Empty until merged. |
| `[].squash_on_merge` | boolean | Indicates if the merge request will be squashed when merged. | | `[].squash_on_merge` | boolean | Indicates whether to squash the merge request when merging. |
| `[].state` | string | State of the merge request. Can be `opened`, `closed`, `merged`, `locked`. | | `[].state` | string | State of the merge request. Can be `opened`, `closed`, `merged`, `locked`. |
| `[].target_branch` | string | Target branch of the merge request. | | `[].target_branch` | string | Target branch of the merge request. |
| `[].target_project_id` | integer | ID of the merge request target project. | | `[].target_project_id` | integer | ID of the merge request target project. |
......
...@@ -22,7 +22,7 @@ It deprecates these endpoints, which are scheduled for removal in API version 5. ...@@ -22,7 +22,7 @@ It deprecates these endpoints, which are scheduled for removal in API version 5.
In addition to templates common to the entire instance, project-specific In addition to templates common to the entire instance, project-specific
templates are also available from this API endpoint. templates are also available from this API endpoint.
Support is also available for [group-level file templates](../user/group/manage.md#group-file-templates). Support is also available for [file templates for groups](../user/group/manage.md#group-file-templates).
## Get all templates of a particular type ## Get all templates of a particular type
......
...@@ -12,8 +12,6 @@ DETAILS: ...@@ -12,8 +12,6 @@ DETAILS:
## List repository tree ## List repository tree
> - Iterating pages of results with a number (`?page=2`) [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67509) in GitLab 14.3.
Get a list of repository files and directories in a project. This endpoint can Get a list of repository files and directories in a project. This endpoint can
be accessed without authentication if the repository is publicly accessible. be accessed without authentication if the repository is publicly accessible.
......
...@@ -9,7 +9,7 @@ DETAILS: ...@@ -9,7 +9,7 @@ DETAILS:
**Tier:** Free, Premium, Ultimate **Tier:** Free, Premium, Ultimate
**Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated **Offering:** GitLab.com, GitLab Self-Managed, GitLab Dedicated
GitLab provides an API endpoint for instance-level Dockerfile templates. GitLab provides an API endpoint for Dockerfile templates available to the entire instance.
Default templates are defined at Default templates are defined at
[`vendor/Dockerfile`](https://gitlab.com/gitlab-org/gitlab-foss/-/tree/master/vendor/Dockerfile) [`vendor/Dockerfile`](https://gitlab.com/gitlab-org/gitlab-foss/-/tree/master/vendor/Dockerfile)
in the GitLab repository. in the GitLab repository.
......
...@@ -98,7 +98,7 @@ three subgroups, like this: ...@@ -98,7 +98,7 @@ three subgroups, like this:
## Add users to the subgroups ## Add users to the subgroups
In the previous step, when you added your subgroups to the parent group (`engineering`), you limited In the previous step, when you added your subgroups to the parent group (`engineering`), you limited
members of the subgroups to the Maintainer role. This is the highest role they can inherit members of the subgroups to the Maintainer role. This role is the highest role they can inherit
for projects owned by `engineering`. As a result: for projects owned by `engineering`. As a result:
- User 1 is added to the `manager` subgroup with the Guest role, and receives - User 1 is added to the `manager` subgroup with the Guest role, and receives
......
...@@ -45,7 +45,7 @@ To review a merge request: ...@@ -45,7 +45,7 @@ To review a merge request:
## Understand the structure of merge requests ## Understand the structure of merge requests
Merge requests have a secondary menu with four options. You'll use these areas of a Merge requests have a secondary menu with four options. You use these areas of a
merge request at different times during your review: merge request at different times during your review:
![Screenshot of the top area of a merge request, with four main tabs](img/top_bar_v17_0.png) ![Screenshot of the top area of a merge request, with four main tabs](img/top_bar_v17_0.png)
...@@ -77,7 +77,7 @@ Start by looking at the description of the merge request. It should be the solut ...@@ -77,7 +77,7 @@ Start by looking at the description of the merge request. It should be the solut
to a problem or a feature request in an issue. to a problem or a feature request in an issue.
- **Who is the author?** Are you familiar with this person's work? If you're familiar with - **Who is the author?** Are you familiar with this person's work? If you're familiar with
this person, what part of the codebase do they normally work on? Later, your this person, what part of the codebase do they usually work on? Later, your
knowledge of the author helps you gauge how to scrutinize their changes. knowledge of the author helps you gauge how to scrutinize their changes.
- **What's the goal?** Read the description to understand the author's intent. - **What's the goal?** Read the description to understand the author's intent.
- **Is it a draft?** Drafts are often incomplete or theoretical solutions. A draft merge request might require - **Is it a draft?** Drafts are often incomplete or theoretical solutions. A draft merge request might require
...@@ -260,7 +260,7 @@ In this example, multiple jobs have failed: ...@@ -260,7 +260,7 @@ In this example, multiple jobs have failed:
Sometimes merge request reviews are not straightforward and require a back-and-forth between the assignee and reviewers. If you're re-reviewing work, go to Sometimes merge request reviews are not straightforward and require a back-and-forth between the assignee and reviewers. If you're re-reviewing work, go to
the **Commits** page for this merge request, and read the contents of the commits the **Commits** page for this merge request, and read the contents of the commits
added since your last review. added after your last review.
Do these commits address your concerns from your initial review? Do these commits address your concerns from your initial review?
...@@ -276,7 +276,7 @@ is trying to do, and how it's doing it. ...@@ -276,7 +276,7 @@ is trying to do, and how it's doing it.
ask yourself if the work should be simplified, or broken apart into multiple ask yourself if the work should be simplified, or broken apart into multiple
merge requests. Be honest about your own scope of knowledge, and your limitations. merge requests. Be honest about your own scope of knowledge, and your limitations.
- **Do you detect [code smells](https://martinfowler.com/bliki/CodeSmell.html)?** - **Do you detect [code smells](https://martinfowler.com/bliki/CodeSmell.html)?**
If something you see isn't quite a bug, but it points to future quality, maintainability, If something you see isn't a bug, but it points to future quality, maintainability,
or security problems, pay attention. Trust your instincts if something about the or security problems, pay attention. Trust your instincts if something about the
changes feels off, obfuscated, or poorly done. The code might be technically correct, changes feels off, obfuscated, or poorly done. The code might be technically correct,
but contain weaknesses that could cause problems in the future. but contain weaknesses that could cause problems in the future.
......
...@@ -43,12 +43,12 @@ You have two options: ...@@ -43,12 +43,12 @@ You have two options:
- The plain text editor, called the Web Editor, which you can use to edit a single file. - The plain text editor, called the Web Editor, which you can use to edit a single file.
- A more full-featured editor, called the Web IDE, which you can use to edit multiple files. - A more full-featured editor, called the Web IDE, which you can use to edit multiple files.
If you'd prefer to work locally, you can use Git to clone the repository to your computer Prefer to work locally? Use Git to clone the repository to your computer,
and develop in the IDE of your choice. and develop in the IDE of your choice.
Then you can use one of the GitLab editor extensions to assist in interacting with GitLab. Then you can use one of the GitLab editor extensions to assist in interacting with GitLab.
And finally, if you don't want to use either of the first two options, Don't want to use either of the first two options?
you can launch a remote development environment and work from the cloud. Launch a remote development environment, and work from the cloud.
You can further split your development environment by creating separate workspaces. You can further split your development environment by creating separate workspaces.
Workspaces are separate development environments you use to ensure different projects Workspaces are separate development environments you use to ensure different projects
...@@ -108,8 +108,10 @@ For details, see: ...@@ -108,8 +108,10 @@ For details, see:
Before your changes can be merged, the merge request usually needs to be approved by other people, Before your changes can be merged, the merge request usually needs to be approved by other people,
and to have a passing CI/CD pipeline. The requirements are custom to your organization, but and to have a passing CI/CD pipeline. The requirements are custom to your organization, but
usually they include ensuring the code changes adhere to your organization's guidelines and usually they include ensuring:
that the commit message is clear and links to related issues.
- The code changes adhere to your organization's guidelines.
- The commit messages are clear, and link to related issues.
Merge conflicts can occur if someone else edits a file after you created your branch, Merge conflicts can occur if someone else edits a file after you created your branch,
but before you merged it into the target branch. You must resolve any conflicts before you can merge. but before you merged it into the target branch. You must resolve any conflicts before you can merge.
......
...@@ -13,10 +13,10 @@ DETAILS: ...@@ -13,10 +13,10 @@ DETAILS:
> - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113232) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. Enabled for GitLab team members only. > - User interface [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/113232) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `saved_replies`. Disabled by default. Enabled for GitLab team members only.
> - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119468) in GitLab 16.0. > - [Enabled on GitLab.com and GitLab Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119468) in GitLab 16.0.
> - [Feature flag `saved_replies` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123363) in GitLab 16.6. > - [Feature flag `saved_replies` removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123363) in GitLab 16.6.
> - Group-level saved replies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `group_saved_replies_flag`. Disabled by default. > - Saved replies for groups [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 16.11 [with a flag](../../administration/feature_flags.md) named `group_saved_replies_flag`. Disabled by default.
> - Group-level saved replies [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/440817) on GitLab.com and GitLab Self-Managed in GitLab 16.11. > - Saved replies for groups [enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/440817) on GitLab.com and GitLab Self-Managed in GitLab 16.11.
> - Group-level saved replies [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `group_saved_replies_flag` removed. > - Saved replies for groups [generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `group_saved_replies_flag` removed.
> - Project-level saved replies [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `project_saved_replies_flag`. Enabled by default. > - Saved replies for projects [introduced](https://gitlab.com/groups/gitlab-org/-/epics/12669) in GitLab 17.0 [with a flag](../../administration/feature_flags.md) named `project_saved_replies_flag`. Enabled by default.
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `project_saved_replies_flag` removed. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/504028) in GitLab 17.8. Feature flag `project_saved_replies_flag` removed.
With comment templates, create and reuse text for any text area in: With comment templates, create and reuse text for any text area in:
......
...@@ -102,9 +102,10 @@ You might get an HTTP `500` error. ...@@ -102,9 +102,10 @@ You might get an HTTP `500` error.
This issue occurs for when requests time out for commits with a lot of changed files. This issue occurs for when requests time out for commits with a lot of changed files.
If this happens with a commit with more than 50 files changed, If this issue happens when you change more than 50 files in a commit:
the workaround is to break down your changes into smaller commits and push
them one by one. 1. Split your changes into smaller commits.
1. Push the smaller commits one by one.
### Error: `Filename: ensure this value has at most 256 characters` ### Error: `Filename: ensure this value has at most 256 characters`
......
...@@ -23,7 +23,7 @@ You can define approval rules: ...@@ -23,7 +23,7 @@ You can define approval rules:
You can configure approval rules: You can configure approval rules:
- [At the instance level](../../../../administration/merge_requests_approvals.md). - [For the entire instance](../../../../administration/merge_requests_approvals.md).
If you don't define a [default approval rule](#add-an-approval-rule), If you don't define a [default approval rule](#add-an-approval-rule),
any user can approve a merge request. Even if you don't define a rule, you can still any user can approve a merge request. Even if you don't define a rule, you can still
...@@ -312,7 +312,7 @@ These policies are both created and edited in the [security policy editor](../.. ...@@ -312,7 +312,7 @@ These policies are both created and edited in the [security policy editor](../..
As a workaround for this validation error, you can delete the approval rule through As a workaround for this validation error, you can delete the approval rule through
the API. the API.
1. [GET a project-level rule](../../../../api/merge_request_approvals.md#get-a-single-project-level-rule). 1. [GET a rule set for a project](../../../../api/merge_request_approvals.md#get-a-single-project-level-rule).
1. [DELETE the rule](../../../../api/merge_request_approvals.md#delete-project-level-rule). 1. [DELETE the rule](../../../../api/merge_request_approvals.md#delete-project-level-rule).
For more information about this validation error, read For more information about this validation error, read
...@@ -330,8 +330,8 @@ In the group structure below, project 1 belongs to subgroup 1 and subgroup 4 has ...@@ -330,8 +330,8 @@ In the group structure below, project 1 belongs to subgroup 1 and subgroup 4 has
![Example scenario - project and group hierarchy](img/group_access_example_01_v16_8.png) ![Example scenario - project and group hierarchy](img/group_access_example_01_v16_8.png)
Project 1 has a project level approval rule which assigns subgroup 4 as approvers. Project 1 has configured an approval rule for the project, which assigns subgroup 4 as approvers.
When a merge request is created approvers from subgroup 4 appear in the eligible approvers list. When a merge request is created, approvers from subgroup 4 appear in the eligible approvers list.
However, as users from subgroup 4 do not have permission to view the merge request, the `404` error is returned. However, as users from subgroup 4 do not have permission to view the merge request, the `404` error is returned.
To grant membership, the group must be invited as a project member. It is now possible for users from subgroup 4 to approve. To grant membership, the group must be invited as a project member. It is now possible for users from subgroup 4 to approve.
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment