debian-mirror-gitlab/doc/user/project/description_templates.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

221 lines
9.6 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
stage: Plan
group: Project Management
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
---
2021-09-30 23:02:18 +05:30
# Description templates **(FREE)**
2016-09-13 17:45:13 +05:30
2022-03-02 08:16:31 +05:30
You can define templates to use as descriptions
for your [issues](issues/index.md) and [merge requests](merge_requests/index.md).
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
You can define these templates in a project, group, or instance. Projects
inherit the templates defined at a higher level.
2016-09-13 17:45:13 +05:30
2022-03-02 08:16:31 +05:30
You might want to use these templates:
2016-09-13 17:45:13 +05:30
2022-03-02 08:16:31 +05:30
- For different stages of your workflow, for example, feature proposal, feature improvement, or a bug report.
- For every issue or merge request for a specific project, so the layout is consistent.
- For a [Service Desk email template](service_desk.md#new-service-desk-issues).
2016-09-13 17:45:13 +05:30
2022-03-02 08:16:31 +05:30
For description templates to work, they must be:
2016-09-13 17:45:13 +05:30
2022-03-02 08:16:31 +05:30
- Saved with the `.md` extension.
- Stored in your project's repository in the `.gitlab/issue_templates`
or `.gitlab/merge_request_templates` directory.
- Be present on the default branch.
2019-07-31 22:56:46 +05:30
2021-04-17 20:07:23 +05:30
## Create an issue template
2016-09-13 17:45:13 +05:30
Create a new Markdown (`.md`) file inside the `.gitlab/issue_templates/`
2022-03-02 08:16:31 +05:30
directory in your repository.
2016-09-13 17:45:13 +05:30
2022-03-02 08:16:31 +05:30
To create an issue description template:
2020-05-24 23:13:21 +05:30
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2022-03-02 08:16:31 +05:30
1. On the left sidebar, select **Repository**.
1. Next to the default branch, select **{plus}**.
2021-04-29 21:17:54 +05:30
1. Select **New file**.
2022-03-02 08:16:31 +05:30
1. Next to the default branch, in the **File name** text box, enter `.gitlab/issue_templates/mytemplate.md`,
where `mytemplate` is the name of your issue template.
1. Commit to your default branch.
2020-05-24 23:13:21 +05:30
2022-01-26 12:08:38 +05:30
To check if this has worked correctly, [create a new issue](issues/managing_issues.md#create-an-issue)
2022-03-02 08:16:31 +05:30
and see if you can find your description template in the **Choose a template** dropdown list.
2020-05-24 23:13:21 +05:30
2021-04-17 20:07:23 +05:30
## Create a merge request template
2016-09-13 17:45:13 +05:30
Similarly to issue templates, create a new Markdown (`.md`) file inside the
`.gitlab/merge_request_templates/` directory in your repository. Commit and
push to your default branch.
2022-03-02 08:16:31 +05:30
To create a merge request description template:
2016-09-13 17:45:13 +05:30
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2022-03-02 08:16:31 +05:30
1. On the left sidebar, select **Repository**.
1. Next to the default branch, select **{plus}**.
1. Select **New file**.
1. Next to the default branch, in the **File name** text box, enter `.gitlab/merge_request_templates/mytemplate.md`,
where `mytemplate` is the name of your merge request template.
1. Commit to your default branch.
2021-01-03 14:25:43 +05:30
2022-03-02 08:16:31 +05:30
To check if this has worked correctly, [create a new merge request](merge_requests/creating_merge_requests.md)
and see if you can find your description template in the **Choose a template** dropdown list.
2016-09-13 17:45:13 +05:30
2022-03-02 08:16:31 +05:30
## Use the templates
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
When you create or edit an issue or a merge request, it shows in the **Choose a template** dropdown list.
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
To apply a template:
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
1. Create or edit an issue or a merge request.
1. Select the **Choose a template** dropdown list.
1. If the **Description** text box hasn't been empty, to confirm, select **Apply template**.
1. Select **Save changes**.
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
When you select a description template, its content is copied to the description text box.
2021-04-29 21:17:54 +05:30
2022-03-02 08:16:31 +05:30
To discard any changes to the description you've made after selecting the template: expand the **Choose a template** dropdown list and select **Reset template**.
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
![Choosing a description template in an issue](img/description_templates_v14_7.png)
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
NOTE:
You can create shortcut links to create an issue using a designated template.
For example: `https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal`. Read more about [creating issues using a URL with prefilled values](issues/managing_issues.md#using-a-url-with-prefilled-values).
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
### Set instance-level description templates **(PREMIUM SELF)**
2021-04-29 21:17:54 +05:30
2022-03-02 08:16:31 +05:30
You can set a description template at the **instance level** for issues
and merge requests by using an [instance template repository](../admin_area/settings/instance_template_repository.md).
You can also use the instance template repository for file templates.
2021-04-17 20:07:23 +05:30
2022-03-02 08:16:31 +05:30
You might also be interested [project templates](../admin_area/custom_project_templates.md)
that you can use when creating a new project in the instance.
2021-04-17 20:07:23 +05:30
2021-04-29 21:17:54 +05:30
### Set group-level description templates **(PREMIUM)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52360) in GitLab 13.9.
2021-09-04 01:27:46 +05:30
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321247) in GitLab 14.0.
2021-04-29 21:17:54 +05:30
With **group-level** description templates, you can store your templates in a single repository and
configure the group file templates setting to point to that repository.
As a result, you can use the same templates in issues and merge requests in all the group's projects.
To re-use templates [you've created](../project/description_templates.md#create-an-issue-template):
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Groups** and find your group.
2022-03-02 08:16:31 +05:30
1. On the left sidebar, select **Settings > General**.
1. Expand **Templates**.
1. From the dropdown list, select your template project as the template repository at group level.
2021-04-29 21:17:54 +05:30
1. Select **Save changes**.
![Group template settings](../group/img/group_file_template_settings.png)
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
You might also be interested in templates for various
2022-08-27 11:52:29 +05:30
[file types in groups](../group/manage.md#group-file-templates).
2022-03-02 08:16:31 +05:30
2022-04-04 11:22:00 +05:30
### Set a default template for merge requests and issues
2022-07-23 23:45:48 +05:30
> `Default.md` (case insensitive) template [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302) in GitLab 14.8.
2019-07-31 22:56:46 +05:30
2021-04-29 21:17:54 +05:30
In a project, you can choose a default description template for new issues and merge requests.
As a result, every time a new merge request or issue is created, it's pre-filled with the text you
entered in the template.
2022-03-02 08:16:31 +05:30
Prerequisites:
- On your project's left sidebar, select **Settings > General** and expand **Visibility, project features, permissions**.
Ensure issues or merge requests are set to either **Everyone with access** or **Only Project Members**.
2019-07-31 22:56:46 +05:30
2022-04-04 11:22:00 +05:30
To set a default description template for merge requests, either:
2021-04-17 20:07:23 +05:30
2022-07-23 23:45:48 +05:30
- [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create a merge request template](#create-a-merge-request-template) named `Default.md` (case insensitive)
2022-04-04 11:22:00 +05:30
and save it in `.gitlab/merge_request_templates/`.
2022-07-23 23:45:48 +05:30
This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings.
2022-04-04 11:22:00 +05:30
- Users on GitLab Premium and higher: set the default template in project settings:
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
1. On the left sidebar, select **Settings > Merge requests**.
1. In the **Merge commit message template** section, fill in **Default description template for merge requests**.
2022-04-04 11:22:00 +05:30
1. Select **Save changes**.
To set a default description template for issues, either:
2021-04-17 20:07:23 +05:30
2022-07-23 23:45:48 +05:30
- [In GitLab 14.8 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/78302), [create an issue template](#create-an-issue-template) named `Default.md` (case insensitive)
2022-04-04 11:22:00 +05:30
and save it in `.gitlab/issue_templates/`.
2022-07-23 23:45:48 +05:30
This [doesn't overwrite](#priority-of-default-description-templates) the default template if one has been set in the project settings.
2022-04-04 11:22:00 +05:30
- Users on GitLab Premium and higher: set the default template in project settings:
2021-04-17 20:07:23 +05:30
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2022-04-04 11:22:00 +05:30
1. On the left sidebar, select **Settings**.
1. Expand **Default issue template**.
1. Fill in the **Default description template for issues** text area.
1. Select **Save changes**.
2019-07-31 22:56:46 +05:30
2021-04-17 20:07:23 +05:30
Because GitLab merge request and issues support [Markdown](../markdown.md), you can use it to format
headings, lists, and so on.
2020-04-22 19:07:51 +05:30
2022-03-02 08:16:31 +05:30
You can also provide `issues_template` and `merge_requests_template` attributes in the
[Projects REST API](../../api/projects.md) to keep your default issue and merge request templates up to date.
2019-07-31 22:56:46 +05:30
2022-07-23 23:45:48 +05:30
#### Priority of default description templates
2022-04-04 11:22:00 +05:30
When you set [merge request and issue description templates](#set-a-default-template-for-merge-requests-and-issues)
in various places, they have the following priorities in a project.
The ones higher up override the ones below:
2022-07-23 23:45:48 +05:30
1. Template set in project settings.
1. `Default.md` (case insensitive) from the parent group.
1. `Default.md` (case insensitive) from the project repository.
2022-04-04 11:22:00 +05:30
2022-03-02 08:16:31 +05:30
## Example description template
2018-03-17 18:26:18 +05:30
2021-04-17 20:07:23 +05:30
We use description templates for issues and merge requests in the
2021-09-04 01:27:46 +05:30
[`.gitlab` folder](https://gitlab.com/gitlab-org/gitlab/-/tree/master/.gitlab) of the
2021-04-17 20:07:23 +05:30
GitLab project, which you can refer to for some examples.
2018-03-17 18:26:18 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-03-11 19:13:27 +05:30
It's possible to use [quick actions](quick_actions.md) in description templates to quickly add
2021-02-22 17:27:13 +05:30
labels, assignees, and milestones. The quick actions are only executed if the user submitting
2020-04-22 19:07:51 +05:30
the issue or merge request has the permissions to perform the relevant actions.
2018-03-17 18:26:18 +05:30
2021-04-17 20:07:23 +05:30
Here is an example of a bug report template:
2018-03-17 18:26:18 +05:30
2021-03-11 19:13:27 +05:30
```markdown
## Summary
2018-03-17 18:26:18 +05:30
(Summarize the bug encountered concisely)
2021-03-11 19:13:27 +05:30
## Steps to reproduce
2018-03-17 18:26:18 +05:30
(How one can reproduce the issue - this is very important)
2021-03-11 19:13:27 +05:30
## Example Project
2018-03-17 18:26:18 +05:30
2022-11-25 23:54:43 +05:30
(If possible, create an example project here on GitLab.com that exhibits the problematic
2021-03-11 19:13:27 +05:30
behavior, and link to it here in the bug report.
If you are using an older version of GitLab, this will also determine whether the bug has been fixed
in a more recent version)
2018-03-17 18:26:18 +05:30
2021-03-11 19:13:27 +05:30
## What is the current bug behavior?
2018-03-17 18:26:18 +05:30
(What actually happens)
2021-03-11 19:13:27 +05:30
## What is the expected correct behavior?
2018-03-17 18:26:18 +05:30
(What you should see instead)
2021-03-11 19:13:27 +05:30
## Relevant logs and/or screenshots
2018-03-17 18:26:18 +05:30
2022-11-25 23:54:43 +05:30
(Paste any relevant logs - use code blocks (```) to format console output, logs, and code, as
2021-03-11 19:13:27 +05:30
it's very hard to read otherwise.)
2018-03-17 18:26:18 +05:30
2021-03-11 19:13:27 +05:30
## Possible fixes
2018-03-17 18:26:18 +05:30
(If you can, link to the line of code that might be responsible for the problem)
/label ~bug ~reproduced ~needs-investigation
/cc @project-manager
/assign @qa-tester
```