Commit 1892b4e8 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis Committed by Rémy Coutable

Merge branch 'docs/issue-closing-pattern' into 'master'

Change location and refactor issue closing pattern documentation

## Moving docs to a new location?

See the guidelines: http://docs.gitlab.com/ce/development/doc_styleguide.html#changing-document-location

- [x] Make sure the old link is not removed and has its contents replaced with a link to the new location.
- [x] Make sure internal links pointing to the document in question are not broken.
- [x] Search and replace any links referring to old docs in GitLab Rails app, specifically under the `app/views/` directory.
- [x] If working on CE, submit an MR to EE with the changes as well.

See merge request !6466
parent 3b890186
...@@ -29,9 +29,9 @@ ...@@ -29,9 +29,9 @@
- [Install](install/README.md) Requirements, directory structures and installation from source. - [Install](install/README.md) Requirements, directory structures and installation from source.
- [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components. - [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components.
- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter. - [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter.
- [Issue closing](customization/issue_closing.md) Customize how to close an issue from commit messages. - [Issue closing pattern](administration/issue_closing_pattern.md) Customize how to close an issue from commit messages.
- [Koding](administration/integration/koding.md) Set up Koding to use with GitLab. - [Koding](administration/integration/koding.md) Set up Koding to use with GitLab.
- [Libravatar](customization/libravatar.md) Use Libravatar for user avatars. - [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars.
- [Log system](administration/logs.md) Log system. - [Log system](administration/logs.md) Log system.
- [Environment Variables](administration/environment_variables.md) to configure GitLab. - [Environment Variables](administration/environment_variables.md) to configure GitLab.
- [Operations](operations/README.md) Keeping GitLab up and running. - [Operations](operations/README.md) Keeping GitLab up and running.
......
# Issue closing pattern
>**Note:**
This is the administration documentation.
There is a separate [user documentation] on issue closing pattern.
When a commit or merge request resolves one or more issues, it is possible to
automatically have these issues closed when the commit or merge request lands
in the project's default branch.
## Change the issue closing pattern
In order to change the pattern you need to have access to the server that GitLab
is installed on.
The default pattern can be located in [gitlab.yml.example] under the
"Automatic issue closing" section.
> **Tip:**
You are advised to use http://rubular.com to test the issue closing pattern.
Because Rubular doesn't understand `%{issue_ref}`, you can replace this by
`#\d+` when testing your patterns, which matches only local issue references like `#123`.
**For Omnibus installations**
1. Open `/etc/gitlab/gitlab.rb` with your editor.
1. Change the value of `gitlab_rails['issue_closing_pattern']` to a regular
expression of your liking:
```ruby
gitlab_rails['issue_closing_pattern'] = "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
```
1. [Reconfigure] GitLab for the changes to take effect.
**For installations from source**
1. Open `gitlab.yml` with your editor.
1. Change the value of `issue_closing_pattern`:
```yaml
issue_closing_pattern: "((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)"
```
1. [Restart] GitLab for the changes to take effect.
[gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
[reconfigure]: restart_gitlab.md#omnibus-gitlab-reconfigure
[restart]: restart_gitlab.md#installations-from-source
[user documentation]: ../user/project/issues/automatic_issue_closing.md
# Issue closing pattern This document was split into:
When a commit or merge request resolves one or more issues, it is possible to automatically have these issues closed when the commit or merge request lands in the project's default branch. - [administration/issue_closing_pattern.md](../administration/issue_closing_pattern.md).
- [user/project/issues/automatic_issue_closing](../user/project/issues/automatic_issue_closing.md).
If a commit message or merge request description contains a sentence matching the regular expression below, all issues referenced from
the matched text will be closed. This happens when the commit is pushed to a project's default branch, or when a commit or merge request is merged into there.
When not specified, the default `issue_closing_pattern` as shown below will be used:
```bash
((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing))(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+)
```
Here, `%{issue_ref}` is a complex regular expression defined inside GitLab, that matches a reference to a local issue (`#123`), cross-project issue (`group/project#123`) or a link to an issue (`https://gitlab.example.com/group/project/issues/123`).
For example:
```
git commit -m "Awesome commit message (Fix #20, Fixes #21 and Closes group/otherproject#22). 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 not match the pattern. It also works with multiline commit messages.
Tip: you can test this closing pattern at [http://rubular.com][1]. Use this site
to test your own patterns.
Because Rubular doesn't understand `%{issue_ref}`, you can replace this by `#\d+` in testing, which matches only local issue references like `#123`.
## Change the pattern
For Omnibus installs you can change the default pattern in `/etc/gitlab/gitlab.rb`:
```
issue_closing_pattern: '((?:[Cc]los(?:e[sd]|ing)|[Ff]ix(?:e[sd]|ing)?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?))+)'
```
For manual installs you can customize the pattern in [gitlab.yml][0] using the `issue_closing_pattern` key.
[0]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
[1]: http://rubular.com/r/Xmbexed1OJ
...@@ -24,4 +24,4 @@ You may assign the Issue to a user, add a milestone and add labels (they are all ...@@ -24,4 +24,4 @@ You may assign the Issue to a user, add a milestone and add labels (they are all
![Submit new issue](basicsimages/submit_new_issue.png) ![Submit new issue](basicsimages/submit_new_issue.png)
Your Issue will now be added to the Issue Tracker and will be ready to be reviewed. You can comment on it and mention the people involved. You can also link Issues to the Merge Requests where the Issues are solved. To do this, you can use an [Issue closing pattern](http://docs.gitlab.com/ce/customization/issue_closing.html). Your Issue will now be added to the Issue Tracker and will be ready to be reviewed. You can comment on it and mention the people involved. You can also link Issues to the Merge Requests where the Issues are solved. To do this, you can use an [Issue closing pattern](../user/project/issues/automatic_issue_closing.md).
...@@ -22,7 +22,7 @@ Create merge requests and review code. ...@@ -22,7 +22,7 @@ Create merge requests and review code.
- [Fork a project and contribute to it](../workflow/forking_workflow.md) - [Fork a project and contribute to it](../workflow/forking_workflow.md)
- [Create a new merge request](../gitlab-basics/add-merge-request.md) - [Create a new merge request](../gitlab-basics/add-merge-request.md)
- [Automatically close issues from merge requests](../customization/issue_closing.md) - [Automatically close issues from merge requests](../user/project/issues/automatic_issue_closing.md)
- [Automatically merge when your builds succeed](../user/project/merge_requests/merge_when_build_succeeds.md) - [Automatically merge when your builds succeed](../user/project/merge_requests/merge_when_build_succeeds.md)
- [Revert any commit](../user/project/merge_requests/revert_changes.md) - [Revert any commit](../user/project/merge_requests/revert_changes.md)
- [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md) - [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md)
......
# Automatic issue closing
>**Note:**
This is the user docs. In order to change the default issue closing pattern,
follow the steps in the [administration docs].
When a commit or merge request resolves one or more issues, it is possible to
automatically have these issues closed when the commit or merge request lands
in the project's default branch.
If a commit message or merge request description contains a sentence matching
a certain regular expression, all issues referenced from the matched text will
be closed. This happens when the commit is pushed to a project's **default**
branch, or when a commit or merge request is merged into it.
## Default closing pattern value
When not specified, the default issue closing pattern as shown below will be
used:
```bash
((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing))(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+)
```
Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's
source code that can match a reference to 1) a local issue (`#123`),
2) a cross-project issue (`group/project#123`) or 3) a link to an issue
(`https://gitlab.example.com/group/project/issues/123`).
---
This translates to the following keywords:
- Close, Closes, Closed, Closing, close, closes, closed, closing
- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
---
For example the following commit message:
```
Awesome commit message
Fix #20, Fixes #21 and Closes group/otherproject#22.
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 not match the pattern. It works with multi-line commit messages as well
as one-liners when used with `git commit -m`.
[administration docs]: ../../../administration/issue_closing_pattern.md
...@@ -172,4 +172,4 @@ you commit the changes you will be taken to a new merge request form. ...@@ -172,4 +172,4 @@ you commit the changes you will be taken to a new merge request form.
![New file button](basicsimages/file_button.png) ![New file button](basicsimages/file_button.png)
[ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808 [ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808
[issue closing pattern]: ../customization/issue_closing.md [issue closing pattern]: ../user/project/issues/automatic_issue_closing.md
# Workflow # Workflow
- [Automatic issue closing](../user/project/issues/automatic_issue_closing.md)
- [Change your time zone](timezone.md) - [Change your time zone](timezone.md)
- [Cycle Analytics](../user/project/cycle_analytics.md) - [Cycle Analytics](../user/project/cycle_analytics.md)
- [Description templates](../user/project/description_templates.md) - [Description templates](../user/project/description_templates.md)
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment