diff options
Diffstat (limited to 'doc/user/project/issues')
| -rw-r--r-- | doc/user/project/issues/confidential_issues.md | 47 | ||||
| -rw-r--r-- | doc/user/project/issues/crosslinking_issues.md | 11 | ||||
| -rw-r--r-- | doc/user/project/issues/csv_export.md | 2 | ||||
| -rw-r--r-- | doc/user/project/issues/due_dates.md | 23 | ||||
| -rw-r--r-- | doc/user/project/issues/img/due_dates_issues_index_page.png | bin | 19302 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/issues/index.md | 51 | ||||
| -rw-r--r-- | doc/user/project/issues/issue_data_and_actions.md | 8 | ||||
| -rw-r--r-- | doc/user/project/issues/managing_issues.md | 75 |
8 files changed, 114 insertions, 103 deletions
diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 02cb0313a74..d4fbc4fb10b 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -29,8 +29,8 @@ confidential checkbox and hit **Save changes**. There are two ways to change an issue's confidentiality. -The first way is to edit the issue and mark/unmark the confidential checkbox. -Once you save the issue, it will change the confidentiality of the issue. +The first way is to edit the issue and toggle the confidentiality checkbox. +After you save the issue, the confidentiality of the issue is updated. The second way is to locate the Confidentiality section in the sidebar and click **Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. @@ -46,20 +46,19 @@ system note in the issue's comments. ## Indications of a confidential issue -NOTE: -If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), -you won't be able to see the confidential issues at all. - There are a few things that visually separate a confidential issue from a regular one. In the issues index page view, you can see the eye-slash icon next to the issues that are marked as confidential.  +If you don't have [enough permissions](#permissions-and-access-to-confidential-issues), +you cannot see confidential issues at all. + --- Likewise, while inside the issue, you can see the eye-slash icon right next to -the issue number, but there is also an indicator in the comment area that the +the issue number. There is also an indicator in the comment area that the issue you are commenting on is confidential.  @@ -83,7 +82,7 @@ project's search results respectively. | Maintainer access | Guest access | | :-----------: | :----------: | -|  |  | +|  |  | ## Merge Requests for Confidential Issues @@ -93,24 +92,24 @@ To help prevent confidential information being leaked from a public project in the process of resolving a confidential issue, confidential issues can be resolved by creating a merge request from a private fork. -The merge request created will target the default branch of the private fork, +The created merge request targets the default branch of the private fork, not the default branch of the public upstream project. This prevents the merge request, branch, and commits entering the public repository, and revealing -confidential information prematurely. When the confidential commits are ready -to be made public, this can be done by opening a merge request from the private -fork to the public upstream project. +confidential information prematurely. To make a confidential commit public, +open a merge request from the private fork to the public upstream project. -NOTE: -If you create a long-lived private fork in the same group or in a sub-group of -the original upstream, all the users with Developer membership to the public -project will also have the same permissions in the private project. This way, -all the Developers, who have access to view confidential issues, will have a -streamlined workflow for fixing them. +Permissions are inherited from parent groups. Developers have the same permissions +for private forks created in the same group or in a sub-group of the original +Permissions are inherited from parent groups. When private forks are created +in the same group or sub-group as the original upstream repository, users +receive the same permissions in both projects. This inheritance ensures +Developer users have the needed permissions to both view confidential issues and +resolve them. ### How it works On a confidential issue, a **Create confidential merge request** button is -available. Clicking on it will open a dropdown where you can choose to +available. Clicking on it opens a dropdown where you can choose to **Create confidential merge request and branch** or **Create branch**: | Create confidential merge request | Create branch | @@ -121,12 +120,12 @@ The **Project** dropdown includes the list of private forks the user is a member of as at least a Developer and merge requests are enabled. Whenever the **Branch name** and **Source (branch or tag)** fields change, the -availability of the target or source branch will be checked. Both branches should -be available in the private fork selected. +availability of the target and source branch are checked. Both branches should +be available in the selected private fork. -By clicking the **Create confidential merge request** button, GitLab will create +By clicking the **Create confidential merge request** button, GitLab creates the branch and merge request in the private fork. When you choose -**Create branch**, GitLab will only create the branch. +**Create branch**, GitLab creates only the branch. -Once the branch is created in the private fork, developers can now push code to +After the branch is created in the private fork, developers can push code to that branch to fix the confidential issue. diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index b5d3b71e679..250fa618dd8 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -31,10 +31,9 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -NOTE: -Linking your first commit to your issue is going to be relevant +Linking your first commit to your issue is relevant for tracking your process with [GitLab Value Stream Analytics](https://about.gitlab.com/stages-devops-lifecycle/value-stream-analytics/). -It will measure the time taken for planning the implementation of that issue, +It measures the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. ## From Related Issues @@ -45,7 +44,7 @@ issues regarding the same topic. You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages). -When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification +When mentioning issue `#111` in issue `#222`, issue `#111` also displays a notification in its tracker. That is, you only need to mention the relationship once for it to display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests). @@ -56,8 +55,8 @@ display in both issues. The same is valid when mentioning issues in [merge reque Mentioning issues in merge request comments works exactly the same way as they do for [related issues](#from-related-issues). -When you mention an issue in a merge request description, it will simply -[link the issue and merge request together](#from-related-issues). Additionally, +When you mention an issue in a merge request description, it +[links the issue and merge request together](#from-related-issues). Additionally, you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically) as soon as the merge request is merged. diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index 023a8ee57bc..e7cd1377603 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -53,7 +53,7 @@ Exported issues are always sorted by `Issue ID`. > > **Weight** and **Locked** columns were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/5300) in GitLab Starter 10.8. -Data wis encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: +Data is encoded with a comma as the column delimiter, with `"` used to quote fields if needed, and newlines to separate rows. The first row contains the headers, which are listed in the following table along with a description of the values: | Column | Description | |---------|-------------| diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 63cd784333a..34e9340067c 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -11,14 +11,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. Due dates can be used in issues to keep track of deadlines and make sure features are -shipped on time. Users must have at least [Reporter permissions](../../permissions.md) -to be able to edit them, but they can be seen by everybody with permission to view -the issue. +shipped on time. Users need at least [Reporter permissions](../../permissions.md) +to be able to edit the due date. All users with permission to view +the issue can view the due date. ## Setting a due date -When creating or editing an issue, you can click in the **due date** field and a calendar -will appear to help you choose the date you want. To remove the date, select the date +When creating an issue, select the **Due date** field to make a calendar +appear for choosing the date. To remove the date, select the date text and delete it. The date is related to the server's timezone, not the timezone of the user setting the due date. @@ -37,18 +37,17 @@ The last way to set a due date is by using [quick actions](../quick_actions.md), ## Making use of due dates -Issues that have a due date can be easily seen in the issue tracker, -displaying a date next to them. Issues where the date is overdue will have -the icon and the date colored red. You can sort issues by those that are -`Due soon` or `Due later` from the dropdown menu on the right. - - +You can see issues with their due dates in the [issues list](index.md#issues-list). +Overdue issues have their icon and date colored red. +To sort issues by their due dates, select **Due date** from the dropdown menu on the right. +Issues are then sorted from the earliest due date to the latest. +To display isses with the latest due dates at the top, select **Sort direction** (**{sort-lowest}**). Due dates also appear in your [to-do list](../../todos.md).  -The day before an open issue is due, an email will be sent to all participants +The day before an open issue is due, an email is sent to all participants of the issue. Like the due date, the "day before the due date" is determined by the server's timezone. diff --git a/doc/user/project/issues/img/due_dates_issues_index_page.png b/doc/user/project/issues/img/due_dates_issues_index_page.png Binary files differdeleted file mode 100644 index 94679436b32..00000000000 --- a/doc/user/project/issues/img/due_dates_issues_index_page.png +++ /dev/null diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 05e7eb3021a..74311eefd83 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -22,8 +22,8 @@ their implementation between: They can also be used for a variety of other purposes, customized to your needs and workflow. -Issues are always associated with a specific project, but if you have multiple projects in a group, -you can also view all the issues collectively at the group level. +Issues are always associated with a specific project. If you have multiple projects in a group, +you can view all of the issues collectively at the group level. **Common use cases include:** @@ -91,9 +91,13 @@ must be set. ## Viewing and managing issues -While you can view and manage the full details of an issue on the [issue page](#issue-page), -you can also work with multiple issues at a time using the [Issues List](#issues-list), -[Issue Boards](#issue-boards), Issue references, and [Epics](#epics). **(PREMIUM)** +While you can view and manage details of an issue on the [issue page](#issue-page), +you can also work with multiple issues at a time using: + +- [Issues List](#issues-list). +- [Issue Boards](#issue-boards). +- Issue references. +- [Epics](#epics) **(PREMIUM)**. Key actions for issues include: @@ -117,14 +121,17 @@ and modify them if you have the necessary [permissions](../../permissions.md). Assignees in the sidebar are updated in real time. This feature is **disabled by default**. To enable, you need to enable [ActionCable in-app mode](https://docs.gitlab.com/omnibus/settings/actioncable.html). -### Issues list +### Issues List + + + +On the Issues List, you can: - +- View all issues in a project when opening the Issues List from a project context. +- View all issues in a groups's projects when opening the Issues List from a group context. -On the Issues List, you can view all issues in the current project, or from multiple -projects when opening the Issues List from the higher-level group context. Filter the -issue list with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), -including specific metadata, such as label(s), assignees(s), status, and more. From this +You can filter the Issues List with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), +including specific metadata, such as labels, assignees, status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page @@ -140,21 +147,21 @@ You can sort a list of issues in several ways, for example by issue creation dat labels or their assignees**(PREMIUM)**. They offer the flexibility to manage issues using highly customizable workflows. -You can reorder issues within a column. If you drag an issue card to another column, its -associated label or assignee will change to match that of the new column. The entire +You can reorder issues in the column. If you drag an issue card to another column, its +associated label or assignee is changed to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label. ### Design Management With [Design Management](design_management.md), you can upload design -assets to issues and view them all together to easily share and -collaborate with your team. +assets to issues and view them all together for sharing and +collaboration with your team. ### Epics **(PREMIUM)** [Epics](../../group/epics/index.md) let you manage your portfolio of projects more -efficiently and with less effort by tracking groups of issues that share a theme, across +efficiently and with less effort. Epics track groups of issues that share a theme, across projects and milestones. ### Related issues @@ -179,10 +186,10 @@ message in the Activity stream about the reference, with a link to the other iss To prevent duplication of issues for the same topic, GitLab searches for similar issues when new issues are being created. -When typing in the title in the **New Issue** page, GitLab searches titles and descriptions -across all issues the user has access to in the current project. Up to five similar issues, -sorted by most recently updated, are displayed below the title box. Note that this feature -requires [GraphQL](../../../api/graphql/index.md) to be enabled. +As you type in the title field of the **New Issue** page, GitLab searches titles and descriptions +across all issues to in the current project. Only issues you have access to are returned. +Up to five similar issues, sorted by most recently updated, are displayed below the title box. +[GraphQL](../../../api/graphql/index.md) must be enabled to use this feature.  @@ -193,8 +200,8 @@ requires [GraphQL](../../../api/graphql/index.md) to be enabled. > - Issue health status visible in issue lists [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/45141) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.6. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/213567) in GitLab 13.7. -To help you track the status of your issues, you can assign a status to each issue to flag work -that's progressing as planned or needs attention to keep on schedule: +To help you track issue statuses, you can assign a status to each issue. +This marks issues as progressing as planned or needs attention to keep on schedule: - **On track** (green) - **Needs attention** (amber) diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2520a562f1e..4c8630581f5 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -35,6 +35,7 @@ The numbers in the image correspond to the following features: - **12.** [Participants](#participants) - **13.** [Notifications](#notifications) - **14.** [Reference](#reference) +- [Issue email](#email) - **15.** [Edit](#edit) - **16.** [Description](#description) - **17.** [Mentions](#mentions) @@ -174,6 +175,13 @@ for the issue. Notifications are automatically enabled after you participate in `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` is the `project-name`, and `xxx` is the issue number. +### Email + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18816) in GitLab 13.8. + +Guest users can see a button in the right sidebar to copy the email address for the issue. +Sending an email to this address creates a comment containing the email body. + ### Edit Clicking this icon opens the issue for editing. All the fields which diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 03060ca720c..ef860df054e 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -19,16 +19,16 @@ Key actions for issues include: ## Create a new issue -When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), +When you create a new issue, you are prompted to fill in the [data and fields of the issue](issue_data_and_actions.md), as illustrated below. If you know the values you want to assign to an issue, you can use the -[Quick actions](../quick_actions.md) feature to input values, instead of selecting them from lists. +[Quick actions](../quick_actions.md) feature to input values. While creating an issue, you can associate it to an existing epic from current group by selecting it using **Epic** dropdown. ### Accessing the New Issue form -There are many ways to get to the New Issue form from within a project: +There are many ways to get to the New Issue form from a project's page: - Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: @@ -75,9 +75,8 @@ using the dropdown button at the top-right of the page.  -We'll keep track of the project you selected most recently, and use it as the default -for your next visit. This should save you a lot of time and clicks, if you mostly -create issues for the same project. +The project you selected most recently becomes the default for your next visit. +This should save you a lot of time and clicks, if you mostly create issues for the same project.  @@ -90,22 +89,22 @@ the appropriate project and followed up from there. ### New issue via email A link to **Email a new issue to this project** is displayed at the bottom of a project's -**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md) -configured. +**Issues List** page. The link is shown only if your GitLab instance has [incoming email](../../../administration/incoming_email.md) +configured and there is at least one issue in the issue list.  When you click this link, an email address is generated and displayed, which should be used by **you only**, to create issues in this project. You can save this address as a -contact in your email client for easy access. +contact in your email client for quick access. WARNING: This is a private email address, generated just for you. **Keep it to yourself**, as anyone who knows it can create issues or merge requests as if they -were you. If the address is compromised, or you'd like it to be regenerated for -any reason, click **Email a new issue to this project** again and click the reset link. +were you. If the address is compromised, or you want to regenerate it, +click **Email a new issue to this project**, followed by **reset it**. -Sending an email to this address will create a new issue in your name for +Sending an email to this address creates a new issue associated with your account for this project, where: - The email subject becomes the issue title. @@ -118,15 +117,15 @@ older format is still supported, allowing existing aliases or contacts to contin ### New issue via URL with prefilled fields -You can link directly to the new issue page for a given project, with prefilled -field values using query string parameters in a URL. This is useful for embedding -a URL in an external HTML page, and also certain scenarios where you want the user to -create an issue with certain fields prefilled. +To link directly to the new issue page with prefilled fields, use query +string parameters in a URL. You can embed a URL in an external +HTML page, or create issues with certain +fields prefilled. The title, description, description template, and confidential fields can be prefilled using this method. You cannot pre-fill both the description and description template -fields in the same URL (since a description template also populates the description -field). +fields in the same URL because a description template also populates the description +field. | Field | URL Parameter Name | Notes | |----------------------|-----------------------|-------------------------------------------------------| @@ -147,9 +146,9 @@ Follow these examples to form your new issue URL with prefilled fields. ## Moving Issues -Moving an issue will copy it to a new location (project), and close it in the old project, -but it will not be deleted. There will also be a system note added to both issues -indicating where it came from and went to. +Moving an issue copies it to the target project, and closes it in the originating project. +The original issue is not deleted. A system note, which indicates +where it came from and went to, is added to both issues. The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. @@ -157,7 +156,9 @@ The "Move issue" button is at the bottom of the right-sidebar when viewing the i ### Moving Issues in Bulk -If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. +If you have advanced technical skills you can also bulk move all the issues from +one project to another in the rails console. The below script moves all issues +that are not in status **closed** from one project to another. To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change `project`, `admin_user`, and `target_project` to your values. @@ -193,23 +194,18 @@ from its list and dropping it into the **Closed** list. ### Closing issues automatically -NOTE: -For performance reasons, automatic issue closing is disabled for the very first -push from an existing repository. - -When a commit or merge request resolves one or more issues, it is possible to have -these issues closed automatically when the commit or merge request reaches the project's -default branch. +When a commit or merge request resolves issues, the issues +can be closed automatically when the commit reaches the project's default branch. If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), -all issues referenced in the matched text will be closed. This happens when the commit +all issues referenced in the matched text are closed. This happens when the commit is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch), or when a commit or merge request is merged into it. For example, if `Closes #4, #6, Related to #5` is included in a Merge Request -description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`. +description, issues `#4` and `#6` are closed automatically when the MR is merged, but not `#5`. Using `Related to` flags `#5` as a [related issue](related_issues.md), -but it will not close automatically. +but is not closed automatically.  @@ -219,9 +215,12 @@ If the issue is in a different repository than the MR, add the full URL for the Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> ``` +For performance reasons, automatic issue closing is disabled for the very first +push from an existing repository. + #### Default closing pattern -When not specified, the default issue closing pattern as shown below will be used: +When not specified, this default issue closing pattern is used: ```shell \b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+) @@ -251,8 +250,8 @@ This commit is also related to #17 and fixes #18, #19 and https://gitlab.example.com/group/otherproject/issues/23. ``` -will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, -as well as `#22` and `#23` in `group/otherproject`. `#17` won't be closed as it does +closes `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +as well as `#22` and `#23` in `group/otherproject`. `#17` is not closed as it does not match the pattern. It works with multi-line commit messages as well as one-liners when used from the command line with `git commit -m`. @@ -261,14 +260,14 @@ when used from the command line with `git commit -m`. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7. The automatic issue closing feature can be disabled on a per-project basis -within the [project's repository settings](../settings/index.md). Referenced -issues will still be displayed as such but won't be closed automatically. +in the [project's repository settings](../settings/index.md). Referenced +issues are still displayed, but are not closed automatically.  This only applies to issues affected by new merge requests or commits. Already closed issues remain as-is. Disabling automatic issue closing only affects merge -requests *within* the project and won't prevent other projects from closing it +requests *in* the project and does not prevent other projects from closing it via cross-project issues. #### Customizing the issue closing pattern **(CORE ONLY)** |
