From f83c5d243459c06fc80a4bf0e287ed59f83e009c Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Sun, 21 Aug 2016 10:59:19 +0300 Subject: Document the new behavior of protected branches --- .../img/protected_branches_devs_can_push.png | Bin 23976 -> 19312 bytes doc/user/project/img/protected_branches_list.png | Bin 16817 -> 16223 bytes doc/user/project/img/protected_branches_page.png | Bin 0 -> 17839 bytes doc/user/project/protected_branches.md | 78 ++++++++++++--------- 4 files changed, 43 insertions(+), 35 deletions(-) create mode 100644 doc/user/project/img/protected_branches_page.png (limited to 'doc/user') diff --git a/doc/user/project/img/protected_branches_devs_can_push.png b/doc/user/project/img/protected_branches_devs_can_push.png index 9c33db36586..812cc8767b7 100644 Binary files a/doc/user/project/img/protected_branches_devs_can_push.png and b/doc/user/project/img/protected_branches_devs_can_push.png differ diff --git a/doc/user/project/img/protected_branches_list.png b/doc/user/project/img/protected_branches_list.png index 9f070f7a208..f33f1b2bdb6 100644 Binary files a/doc/user/project/img/protected_branches_list.png and b/doc/user/project/img/protected_branches_list.png differ diff --git a/doc/user/project/img/protected_branches_page.png b/doc/user/project/img/protected_branches_page.png new file mode 100644 index 00000000000..1585dde5b29 Binary files /dev/null and b/doc/user/project/img/protected_branches_page.png differ diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 96d9bdc1b29..330e0040998 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -5,6 +5,8 @@ idea of having read or write permission to the repository and branches. To prevent people from messing with history or pushing code without review, we've created protected branches. +## Overview + By default, a protected branch does four simple things: - it prevents its creation, if not already created, from everybody except users @@ -15,6 +17,11 @@ By default, a protected branch does four simple things: See the [Changelog](#changelog) section for changes over time. +> +>Added benefits for GitLab Enterprise Edition: +> +>- Restrict push and merge access to [certain users][ee-restrict] + ## Configuring protected branches To protect a branch, you need to have at least Master permission level. Note @@ -28,26 +35,45 @@ that the `master` branch is protected by default. 1. From the **Branch** dropdown menu, select the branch you want to protect and click **Protect**. In the screenshot below, we chose the `develop` branch. - ![Choose protected branch](img/protected_branches_choose_branch.png) + ![Protected branches page](img/protected_branches_page.png) -1. Once done, the protected branch will appear in the "Already protected" list. +1. Once done, the protected branch will appear in the "Protected branches" list. ![Protected branches list](img/protected_branches_list.png) +## Using the Allowed to merge and Allowed to push settings + +> This feature was [introduced][ce-5081] in GitLab 8.11. + +Since GitLab 8.11, we added another layer of branch protection which provides +more granular management of protected branches. The "Developers can push" +option was replaced by an "Allowed to push" setting which can be set to +allow/prohibit Masters and/or Developers to push to a protected branch. + +Using the "Allowed to push" and "Allowed to merge" settings, you can control +the actions that different roles can perform with the protected branch. +For example, you could set "Allowed to push" to "No one", and "Allowed to merge" +to "Developers + Masters", to require _everyone_ to submit a merge request for +changes going into the protected branch. This is compatible with workflows like +the [GitLab workflow](../../workflow/gitlab_flow.md). + +However, there are workflows where that is not needed, and only protecting from +force pushes and branch removal is useful. For those workflows, you can allow +everyone with write access to push to a protected branch by setting +"Allowed to push" to "Developers + Masters". + +You can set the "Allowed to push" and "Allowed to merge" options while creating +a protected branch or afterwards by selecting the option you want from the +dropdown list in the "Already protected" area. -Since GitLab 8.10, we added another layer of branch protection which provides -more granular management of protected branches. You can now choose the option -"Developers can merge" so that Developer users can merge a merge request but -not directly push. In that case, your branches are protected from direct pushes, -yet Developers don't need elevated permissions or wait for someone with a higher -permission level to press merge. +![Developers can push](img/protected_branches_devs_can_push.png) -You can set this option while creating the protected branch or after its -creation. +If you don't choose any of those options while creating a protected branch, +they are set to "Masters" by default. ## Wildcard protected branches -> [Introduced][ce-4665] in GitLab 8.10. +> This feature was [introduced][ce-4665] in GitLab 8.10. You can specify a wildcard protected branch, which will protect all branches matching the wildcard. For example: @@ -66,40 +92,22 @@ Two different wildcards can potentially match the same branch. For example, In that case, if _any_ of these protected branches have a setting like "Allowed to push", then `production-stable` will also inherit this setting. -If you click on a protected branch's name that is created using a wildcard, -you will be presented with a list of all matching branches: +If you click on a protected branch's name, you will be presented with a list of +all matching branches: ![Protected branch matches](img/protected_branches_matches.png) ## Restrict the creation of protected branches -Creating a protected branch or a list of protected branches using the wildcard -feature, not only you are restricting pushes to those branches, but also their -creation if not already created. - -## Error messages when pushing to a protected branch - -A user with insufficient permissions will be presented with an error when -creating or pushing to a branch that's prohibited, either through GitLab's UI: - -![Protected branch error GitLab UI](img/protected_branches_error_ui.png) - -or using Git from their terminal: - -```bash -remote: GitLab: You are not allowed to push code to protected branches on this project. -To https://gitlab.example.com/thedude/bowling.git - ! [remote rejected] staging-stable -> staging-stable (pre-receive hook declined) -error: failed to push some refs to 'https://gitlab.example.com/thedude/bowling.git' -``` - ## Changelog -**8.10.0** +**8.10** -- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!5081][ce-4665] +- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!5081][ce-5081] +- Allow creating protected branches that can't be pushed to [gitlab-org/gitlab-ce!5081][ce-4665] --- [ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards" [ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to" +[ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users -- cgit v1.2.1 From 13a9f454ff0f8fedf6f1bd584beeb05957a395f7 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 22 Aug 2016 15:14:36 +0300 Subject: Add changelog items to protected branches docs --- doc/user/project/protected_branches.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 330e0040998..53a6fdfa820 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -97,17 +97,20 @@ all matching branches: ![Protected branch matches](img/protected_branches_matches.png) -## Restrict the creation of protected branches - ## Changelog +**8.11** + +- Allow creating protected branches that can't be pushed to [gitlab-org/gitlab-ce!5081][ce-5081] + **8.10** -- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!5081][ce-5081] -- Allow creating protected branches that can't be pushed to [gitlab-org/gitlab-ce!5081][ce-4665] +- Allow developers to merge into a protected branch without having push access [gitlab-org/gitlab-ce!4892][ce-4892] +- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!4665][ce-4665] --- [ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards" +[ce-4892]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4892 "Allow developers to merge into a protected branch without having push access" [ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to" [ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users -- cgit v1.2.1 From 16f484890c9a9489786a0eb138bec701d9d45dc8 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 22 Aug 2016 15:19:01 +0300 Subject: Reword GitLab EE ad --- doc/user/project/protected_branches.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/user') diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 53a6fdfa820..6e0f2dcc436 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -18,7 +18,7 @@ By default, a protected branch does four simple things: See the [Changelog](#changelog) section for changes over time. > ->Added benefits for GitLab Enterprise Edition: +>Additional functionality for GitLab Enterprise Edition: > >- Restrict push and merge access to [certain users][ee-restrict] -- cgit v1.2.1 From e466aeb87ee620f83320f0c9718386c38be56a74 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 22 Aug 2016 15:22:05 +0300 Subject: Conform to doc styleguide on new features --- doc/user/project/protected_branches.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 6e0f2dcc436..f7a686d2ccf 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -43,7 +43,7 @@ that the `master` branch is protected by default. ## Using the Allowed to merge and Allowed to push settings -> This feature was [introduced][ce-5081] in GitLab 8.11. +> [Introduced][ce-5081] in GitLab 8.11. Since GitLab 8.11, we added another layer of branch protection which provides more granular management of protected branches. The "Developers can push" @@ -73,7 +73,7 @@ they are set to "Masters" by default. ## Wildcard protected branches -> This feature was [introduced][ce-4665] in GitLab 8.10. +> [Introduced][ce-4665] in GitLab 8.10. You can specify a wildcard protected branch, which will protect all branches matching the wildcard. For example: -- cgit v1.2.1 From c70037752c7d3d7ccf52a19fc8d637ec441bfa25 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 22 Aug 2016 15:53:09 +0300 Subject: Change location of slash commands docs --- doc/user/project/slash_commands.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 doc/user/project/slash_commands.md (limited to 'doc/user') diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md new file mode 100644 index 00000000000..91d69d4e77e --- /dev/null +++ b/doc/user/project/slash_commands.md @@ -0,0 +1,30 @@ +# GitLab slash commands + +Slash commands are textual shortcuts for common actions on issues or merge +requests that are usually done by clicking buttons or dropdowns in GitLab's UI. +You can enter these commands while creating a new issue or merge request, and +in comments. Each command should be on a separate line in order to be properly +detected and executed. The commands are removed from the issue, merge request or +comment body before it is saved and will not be visible to anyone else. + +Below is a list of all of the available commands and descriptions about what they +do. + +| Command | Action | +|:---------------------------|:-------------| +| `/close` | Close the issue or merge request | +| `/reopen` | Reopen the issue or merge request | +| `/title ` | Change title | +| `/assign @username` | Assign | +| `/unassign` | Remove assignee | +| `/milestone %milestone` | Set milestone | +| `/remove_milestone` | Remove milestone | +| `/label ~foo ~"bar baz"` | Add label(s) | +| `/unlabel ~foo ~"bar baz"` | Remove all or specific label(s) | +| `/relabel ~foo ~"bar baz"` | Replace all label(s) | +| `/todo` | Add a todo | +| `/done` | Mark todo as done | +| `/subscribe` | Subscribe | +| `/unsubscribe` | Unsubscribe | +| `/due ` | Set due date | +| `/remove_due_date` | Remove due date | -- cgit v1.2.1 From 2955ca51e306452590131a361f9f0ab293e47114 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 22 Aug 2016 15:56:43 +0300 Subject: Fix docs not rendering the pipe symbol --- doc/user/project/slash_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/user') diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md index 91d69d4e77e..11e1574f772 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -26,5 +26,5 @@ do. | `/done` | Mark todo as done | | `/subscribe` | Subscribe | | `/unsubscribe` | Unsubscribe | -| `/due ` | Set due date | +| `/due ` | Set due date | | `/remove_due_date` | Remove due date | -- cgit v1.2.1 From 7a34794a98e498d69cfeac74c20d15f167e7c070 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 8 Aug 2016 17:26:32 +0300 Subject: Documentation for Issue Boards --- doc/user/project/issue_board.md | 45 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 doc/user/project/issue_board.md (limited to 'doc/user') diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md new file mode 100644 index 00000000000..5890c48013f --- /dev/null +++ b/doc/user/project/issue_board.md @@ -0,0 +1,45 @@ +# Issue board + +> [Introduced][ce-5554] in GitLab 8.11. + +The GitLab Issue Board is a software project management tool used to plan, +organize, and visualize a workflow for a feature or product release. + +It allows you to create lists, which are based on the [labels] that already +exist in the issue tracker. Issues can be seen as cards and they can easily be +moved between the lists, as to create workflows. + +The starting point is two lists: **Backlog** and **Done**. Under the **Backlog** +list, all the issues that are not assigned to a list will appear. Drag a card +to the **Done** list and the relevant issue will be closed. + +## Creating workflows + +By adding new lists, you can create workflows. For instance you can create a +list based on the label of `Design` and one for `Backend`. A designer can start +working on an issue by dragging it to `Design`. That way, everyone knows, this +issue is now being worked on by the designers. Then, once they’re done, all +they have to do is drag it over to the next list, Backend, where a Backend +developer can eventually pick it up. Once they’re done, they move it to closed, +to close the issue. + +As lists in Issue Boards are based on labels, it works out of the box with your +existing issues. So if you've already labeled things with `Backend` and `Frontend`, +the issue will appear in the lists as you create them. In addition, this means +you can easily move something between lists by changing a label. + +If you move an issue from one list to the next, it removes the label from the +list it comes from and adds the label from the list it moves towards. + +## Pro-tips + +- Issue boards can have between 2-10 lists which display as columns. +- Creating a new list is easy! Simply click the **Create new list** button in + the upper right corner and select the labels from your GitLab issue tracker + to populate the list. +- If you need to create a list based on a label that doesn't exist yet, just + click **Create new list** and then "Create new**. +- All issues can be dragged and dropped into lists. + +[ce-5554]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5554 +[labels]: ./labels.md -- cgit v1.2.1 From aef158a74dd4bc8c5a40afd8976419dd6052fcd0 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 16 Aug 2016 13:40:16 +0300 Subject: Great refactor of Issue Board docs --- doc/user/project/img/issue_board.png | Bin 0 -> 200614 bytes doc/user/project/issue_board.md | 98 +++++++++++++++++++++++++++++++---- 2 files changed, 88 insertions(+), 10 deletions(-) create mode 100644 doc/user/project/img/issue_board.png (limited to 'doc/user') diff --git a/doc/user/project/img/issue_board.png b/doc/user/project/img/issue_board.png new file mode 100644 index 00000000000..accd0900cbb Binary files /dev/null and b/doc/user/project/img/issue_board.png differ diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 5890c48013f..29c823a68f3 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -4,15 +4,96 @@ The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. +It can be seen like a light version of a [Kanban] or a [Scrum] board. -It allows you to create lists, which are based on the [labels] that already -exist in the issue tracker. Issues can be seen as cards and they can easily be +## Overview + +The Issue Board builds on GitLab's existing issue tracking functionality and +leverages the power of [labels] by utilizing them as lists of the scrum board. + +With the Issue Board you can have a different view of your issues while also +maintaining the same filtering and sorting abilities you see across the +issue tracker. + +There are three types of lists, of which two are default: + +- **Backlog** (default): shows all issues that do not fall in one of the other + lists. Always appears on the very left. +- **Done** (default): shows all closed issues. Always appears on the very right. +- Label list: a list based on a label. It shows all issues with that label. + +![GitLab Issue Board](img/issue_board.png) + +--- + +Below is a table of the definitions used for GitLab's Issue Board. + +| Term | Definition | +| ---- | ----------- | +| **Issue Board** | It can have up to 10 lists with each list consisting of issues represented by cards. | +| **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. You can create up to 10 lists per Issue Board. | +| **Card** | Every card represents an issue. The information you can see on a card consists of the issue number, the issue title and the labels associated with it. You can drag cards around from one lists to another. Issues are [ordered by priority](labels.md#prioritize-labels). | + + +## Functionality + +The Issue Board consists of lists appearing as columns. Each list is named after +and based on the labels that already exist in your issue tracker. + +It allows you to create lists, which are based on the labels that already +exist in your issue tracker. Issues can be seen as cards and they can easily be moved between the lists, as to create workflows. +Every list contains all issues that are associated with the corresponding label. + +The issues inside each list are sorted by priority. + +- Issue boards can have between 2-10 lists which display as columns. + +The first time you navigate to your Issue Board, you will be presented with the +two special lists ('Backlog' and 'Done') and a welcoming message that The starting point is two lists: **Backlog** and **Done**. Under the **Backlog** list, all the issues that are not assigned to a list will appear. Drag a card to the **Done** list and the relevant issue will be closed. +Here's a list of actions you can take in an Issue Board: + +1. Create a new issue list +1. Delete an issue list +1. Drag issues between lists +1. Drag and reorder the lists themselves +1. Change issue labels on-the-fly while dragging issues between lists +1. Close an issue if you drag it to the 'Done' list +1. Create a new list from a non-existing label by creating the label on-the-fly +1. Populate lists with issues automatically + +Issues > Labels + +Board > Lists > Cards + +Moving an issue between lists removes the label from the list it came from (exception: backlog) and adds the label of the list it goes to: + +When moving from the backlog, just add the new label. The backlog is not a label. + +When moving to Done, remove the label of the list it came from and close the issue. + +If an issue exists in multiple label lists, just show it in multiple lists: + + +## First time using the Issue Board + +When default lists are created, they are empty because the labels associated to them did not exist up until that moment, which means the system has no way of populating them automatically. It'll be the users' job to add individual issues to them. + +## Adding a new list + +Add a new list by clicking on the button. In a modal you will find a label dropdown, where you can also create new labels (like in the sidebar): + +The new list should be inserted at the end of the lists, before Done. + +## Moving lists + +You should be able to drag the label lists around by dragging them on the top. + ## Creating workflows By adding new lists, you can create workflows. For instance you can create a @@ -31,15 +112,12 @@ you can easily move something between lists by changing a label. If you move an issue from one list to the next, it removes the label from the list it comes from and adds the label from the list it moves towards. -## Pro-tips +## Filtering issues -- Issue boards can have between 2-10 lists which display as columns. -- Creating a new list is easy! Simply click the **Create new list** button in - the upper right corner and select the labels from your GitLab issue tracker - to populate the list. -- If you need to create a list based on a label that doesn't exist yet, just - click **Create new list** and then "Create new**. -- All issues can be dragged and dropped into lists. +You should be able to use the filters on top, as seen in the mockup and similar to the issue list. +Every issue contains metadata. [ce-5554]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5554 [labels]: ./labels.md +[scrum]: https://en.wikipedia.org/wiki/Scrum_(software_development) +[kanban]: https://en.wikipedia.org/wiki/Kanban_(development) -- cgit v1.2.1 From 641e50368a17475404056e835e510305d178dc89 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 16 Aug 2016 19:30:03 +0300 Subject: Clean up Issue Board doc a bit --- doc/user/project/issue_board.md | 62 +++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 37 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 29c823a68f3..75ac14167fd 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -34,59 +34,47 @@ Below is a table of the definitions used for GitLab's Issue Board. | **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. You can create up to 10 lists per Issue Board. | | **Card** | Every card represents an issue. The information you can see on a card consists of the issue number, the issue title and the labels associated with it. You can drag cards around from one lists to another. Issues are [ordered by priority](labels.md#prioritize-labels). | - ## Functionality -The Issue Board consists of lists appearing as columns. Each list is named after -and based on the labels that already exist in your issue tracker. - -It allows you to create lists, which are based on the labels that already -exist in your issue tracker. Issues can be seen as cards and they can easily be -moved between the lists, as to create workflows. - -Every list contains all issues that are associated with the corresponding label. - -The issues inside each list are sorted by priority. - -- Issue boards can have between 2-10 lists which display as columns. +The Issue Board consists of lists appearing as columns. Each list you add is +named after and based on the labels that already exist in your issue tracker. +Issues can be seen as cards and they can easily be moved between the lists, as +to create workflows. The issues inside each list are sorted by priority. The first time you navigate to your Issue Board, you will be presented with the -two special lists ('Backlog' and 'Done') and a welcoming message that -The starting point is two lists: **Backlog** and **Done**. Under the **Backlog** -list, all the issues that are not assigned to a list will appear. Drag a card +two special lists (**Backlog** and **Done**) and a welcoming message that +The starting point is two lists: **Backlog** and **Done**. The **Backlog** +list shows all issues that do not fall in one of the other lists. Drag a card to the **Done** list and the relevant issue will be closed. Here's a list of actions you can take in an Issue Board: -1. Create a new issue list +1. Add a new issue list 1. Delete an issue list 1. Drag issues between lists 1. Drag and reorder the lists themselves 1. Change issue labels on-the-fly while dragging issues between lists -1. Close an issue if you drag it to the 'Done' list -1. Create a new list from a non-existing label by creating the label on-the-fly +1. Close an issue if you drag it to the **Done** list +1. Add a new list from a non-existing label by creating the label on-the-fly 1. Populate lists with issues automatically -Issues > Labels - -Board > Lists > Cards - -Moving an issue between lists removes the label from the list it came from (exception: backlog) and adds the label of the list it goes to: - -When moving from the backlog, just add the new label. The backlog is not a label. +Moving an issue between lists removes the label from the list it came from +and adds the label of the list it goes to. When moving to Done, remove the label of the list it came from and close the issue. -If an issue exists in multiple label lists, just show it in multiple lists: - +An issue can exist in multiple lists if it has more than one labels. ## First time using the Issue Board -When default lists are created, they are empty because the labels associated to them did not exist up until that moment, which means the system has no way of populating them automatically. It'll be the users' job to add individual issues to them. +When default lists are created, they are empty because the labels associated to +them did not exist up until that moment, which means the system has no way of +populating them automatically. It'll be the users' job to add individual issues to them. ## Adding a new list -Add a new list by clicking on the button. In a modal you will find a label dropdown, where you can also create new labels (like in the sidebar): +Add a new list by clicking on the button. In a modal you will find a label +dropdown, where you can also create new labels (like in the sidebar). The new list should be inserted at the end of the lists, before Done. @@ -97,15 +85,15 @@ You should be able to drag the label lists around by dragging them on the top. ## Creating workflows By adding new lists, you can create workflows. For instance you can create a -list based on the label of `Design` and one for `Backend`. A designer can start -working on an issue by dragging it to `Design`. That way, everyone knows, this -issue is now being worked on by the designers. Then, once they’re done, all -they have to do is drag it over to the next list, Backend, where a Backend -developer can eventually pick it up. Once they’re done, they move it to closed, -to close the issue. +list based on the label of 'Frontend' and one for 'Backend'. A designer can start +working on an issue by dragging it from **Backlog** to 'Frontend'. That way, everyone +knows, this issue is now being worked on by the designers. Then, once they’re +done, all they have to do is drag it over to the next list, 'Backend', where a +backend developer can eventually pick it up. Once they’re done, they move it to +**Done**, to close the issue. As lists in Issue Boards are based on labels, it works out of the box with your -existing issues. So if you've already labeled things with `Backend` and `Frontend`, +existing issues. So if you've already labeled things with 'Backend' and 'Frontend', the issue will appear in the lists as you create them. In addition, this means you can easily move something between lists by changing a label. -- cgit v1.2.1 From 31e11c90ce2a28d7733c6596d7beefb4db60a305 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 18 Aug 2016 09:09:16 +0300 Subject: Remove 10 lists limit --- doc/user/project/issue_board.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 75ac14167fd..5f87a06504e 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -30,8 +30,8 @@ Below is a table of the definitions used for GitLab's Issue Board. | Term | Definition | | ---- | ----------- | -| **Issue Board** | It can have up to 10 lists with each list consisting of issues represented by cards. | -| **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. You can create up to 10 lists per Issue Board. | +| **Issue Board** | It can have multiple lists with each list consisting of issues represented by cards. | +| **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. | | **Card** | Every card represents an issue. The information you can see on a card consists of the issue number, the issue title and the labels associated with it. You can drag cards around from one lists to another. Issues are [ordered by priority](labels.md#prioritize-labels). | ## Functionality -- cgit v1.2.1 From 53f11f9be79c30e50d4077257945467ff75e7d03 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 18 Aug 2016 13:31:44 +0300 Subject: Complete rest of documentation for Issue Boards --- doc/user/project/img/issue_board_add_list.png | Bin 0 -> 22046 bytes .../project/img/issue_board_welcome_message.png | Bin 0 -> 92257 bytes doc/user/project/issue_board.md | 136 +++++++++++++-------- 3 files changed, 87 insertions(+), 49 deletions(-) create mode 100644 doc/user/project/img/issue_board_add_list.png create mode 100644 doc/user/project/img/issue_board_welcome_message.png (limited to 'doc/user') diff --git a/doc/user/project/img/issue_board_add_list.png b/doc/user/project/img/issue_board_add_list.png new file mode 100644 index 00000000000..e5538763dee Binary files /dev/null and b/doc/user/project/img/issue_board_add_list.png differ diff --git a/doc/user/project/img/issue_board_welcome_message.png b/doc/user/project/img/issue_board_welcome_message.png new file mode 100644 index 00000000000..ebb9fbe8246 Binary files /dev/null and b/doc/user/project/img/issue_board_welcome_message.png differ diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 5f87a06504e..a0edc062f99 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -15,6 +15,14 @@ With the Issue Board you can have a different view of your issues while also maintaining the same filtering and sorting abilities you see across the issue tracker. +Below is a table of the definitions used for GitLab's Issue Board. + +| How we call it | What it means | +| -------------- | ------------- | +| **Issue Board** | It represents a different view for your issues. It can have multiple lists with each list consisting of issues represented by cards. | +| **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. | +| **Card** | Every card represents an issue and it is shown under the list for which it has a label for. The information you can see on a card consists of the issue number, the issue title, the assignee and the labels associated with it. You can drag cards around from one list to another. Issues inside lists are [ordered by priority](labels.md#prioritize-labels). | + There are three types of lists, of which two are default: - **Backlog** (default): shows all issues that do not fall in one of the other @@ -26,86 +34,116 @@ There are three types of lists, of which two are default: --- -Below is a table of the definitions used for GitLab's Issue Board. +In short, here's a list of actions you can take in an Issue Board: -| Term | Definition | -| ---- | ----------- | -| **Issue Board** | It can have multiple lists with each list consisting of issues represented by cards. | -| **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. | -| **Card** | Every card represents an issue. The information you can see on a card consists of the issue number, the issue title and the labels associated with it. You can drag cards around from one lists to another. Issues are [ordered by priority](labels.md#prioritize-labels). | +- [Add a new list](#adding-a-new-list). +- [Remove an existing list](#removing-a-list). +- Drag issues between lists. +- Drag and reorder the lists themselves. +- Change issue labels on-the-fly while dragging issues between lists. +- Close an issue if you drag it to the **Done** list. +- Add a new list from a non-existing label by creating the label on-the-fly. +- [Filter issues](#filtering-issues) that appear across your Issue Board. -## Functionality +If you are not able to perform one or more of the things above, make sure you +have the right [permissions](#permissions). -The Issue Board consists of lists appearing as columns. Each list you add is -named after and based on the labels that already exist in your issue tracker. -Issues can be seen as cards and they can easily be moved between the lists, as -to create workflows. The issues inside each list are sorted by priority. +## First time using the Issue Board The first time you navigate to your Issue Board, you will be presented with the -two special lists (**Backlog** and **Done**) and a welcoming message that -The starting point is two lists: **Backlog** and **Done**. The **Backlog** -list shows all issues that do not fall in one of the other lists. Drag a card -to the **Done** list and the relevant issue will be closed. +two special lists (**Backlog** and **Done**) and a welcoming message that gives +you two options. You can either create a predefined set of labels and add their +corresponding lists to the Issue Board or opt-out and use your own lists. + +![Issue Board welcome message](img/issue_board_welcome_message.png) -Here's a list of actions you can take in an Issue Board: +If you choose to use and add the default lists, they will appear as empty +because the labels associated to them will not exist up until that moment, +which means the system has no way of populating them automatically. It'll be +the users' job to add individual issues to them. -1. Add a new issue list -1. Delete an issue list -1. Drag issues between lists -1. Drag and reorder the lists themselves -1. Change issue labels on-the-fly while dragging issues between lists -1. Close an issue if you drag it to the **Done** list -1. Add a new list from a non-existing label by creating the label on-the-fly -1. Populate lists with issues automatically +## Adding a new list -Moving an issue between lists removes the label from the list it came from -and adds the label of the list it goes to. +Add a new list by clicking on the **Add new list** button at the upper right +corner of the Issue Board. -When moving to Done, remove the label of the list it came from and close the issue. +![Issue Board welcome message](img/issue_board_add_list.png) -An issue can exist in multiple lists if it has more than one labels. +Simply choose the label to create the list from. The new list will be inserted +at the end of the lists, before **Done**. Moving and reordering lists is as +easy as dragging them around. -## First time using the Issue Board +To add a list for a label that doesn't exist yet, simply create the label by +choosing **Create new label**. The label will be created on-the-fly and it will +be immediately added to the dropdown. You can now choose it to add a list. -When default lists are created, they are empty because the labels associated to -them did not exist up until that moment, which means the system has no way of -populating them automatically. It'll be the users' job to add individual issues to them. +## Removing a list -## Adding a new list +To remove a list from the Issue Board use the small trash icon that is present +in the list's heading. A confirmation dialog will appear for you to confirm. -Add a new list by clicking on the button. In a modal you will find a label -dropdown, where you can also create new labels (like in the sidebar). +Removing a list doesn't have any effect in issues and labels, it's just the +list view that is removed. -The new list should be inserted at the end of the lists, before Done. +## Filtering issues -## Moving lists +You should be able to use the filters on top of your Issue Board to show only +the results you want. This is similar to the filtering used in the issue tracker +since the metadata from the issues and labels are re-used in the Issue Board. -You should be able to drag the label lists around by dragging them on the top. +You can filter by author, assignee, milestone and label. ## Creating workflows -By adding new lists, you can create workflows. For instance you can create a +By adding new lists, you can create workflows. As lists in Issue Boards are +based on labels, it works out of the box with your existing issues. So if you've +already labeled things with 'Backend' and 'Frontend', the issue will appear in +the lists as you create them. In addition, this means you can easily move +something between lists by changing a label. + +A typical workflow of using the Issue Board would be: + +1. You have [created labels] so that you can easily categorize your issues. +1. You have a bunch of issues (ideally labeled). +1. You visit the Issue Board and start [adding lists](#adding-a-new-list) as to + create a workflow. +1. You move issues around in lists so that your team knows who should be working + on what issue. +1. When the work by one team is done, the issue can be dragged to the next list + so someone else can pick up. +1. When the issue is finally resolved, the issue is moved to the **Done** list + and gets automatically closed. + +For instance you can add a list based on the label of 'Frontend' and one for 'Backend'. A designer can start working on an issue by dragging it from **Backlog** to 'Frontend'. That way, everyone -knows, this issue is now being worked on by the designers. Then, once they’re +knows that this issue is now being worked on by the designers. Then, once they’re done, all they have to do is drag it over to the next list, 'Backend', where a backend developer can eventually pick it up. Once they’re done, they move it to **Done**, to close the issue. -As lists in Issue Boards are based on labels, it works out of the box with your -existing issues. So if you've already labeled things with 'Backend' and 'Frontend', -the issue will appear in the lists as you create them. In addition, this means -you can easily move something between lists by changing a label. +## Permissions -If you move an issue from one list to the next, it removes the label from the -list it comes from and adds the label from the list it moves towards. +[Developers and up](../permissions.md) can use all the functionality of the +Issue Board, that is add/remove lists and drag issues around. -## Filtering issues +## Tips + +A few things to remember: -You should be able to use the filters on top, as seen in the mockup and similar to the issue list. -Every issue contains metadata. +- Moving an issue between lists removes the label from the list it came from + and adds the label from the list it goes to. +- When moving a card to **Done**, the label of the list it came from is removed + the issue gets closed. +- An issue can exist in multiple lists if it has more than one labels. +- Lists are populated with issues automatically if the issues are labeled. +- Clicking on the issue title inside a card will get you to that issue. +- Clicking on a label inside a card will quickly filter the entire Issue Board + and show only the issues from all lists that have that label. +- Issues inside lists are [ordered by priority](labels.md#prioritize-labels). [ce-5554]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5554 [labels]: ./labels.md [scrum]: https://en.wikipedia.org/wiki/Scrum_(software_development) [kanban]: https://en.wikipedia.org/wiki/Kanban_(development) +[created labels]: ./labels.md#create-new-labels -- cgit v1.2.1 From 1804f60fd5a1aab92f553b7c66b79857ef35df35 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 18 Aug 2016 22:34:17 +0300 Subject: Change images to reflect current status, add link to inline docs --- doc/user/project/img/issue_board_add_list.png | Bin 22046 -> 22391 bytes .../project/img/issue_board_welcome_message.png | Bin 92257 -> 78694 bytes doc/user/project/issue_board.md | 34 ++++++++++----------- 3 files changed, 17 insertions(+), 17 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/img/issue_board_add_list.png b/doc/user/project/img/issue_board_add_list.png index e5538763dee..2b8c10eaa0a 100644 Binary files a/doc/user/project/img/issue_board_add_list.png and b/doc/user/project/img/issue_board_add_list.png differ diff --git a/doc/user/project/img/issue_board_welcome_message.png b/doc/user/project/img/issue_board_welcome_message.png index ebb9fbe8246..b757faeb230 100644 Binary files a/doc/user/project/img/issue_board_welcome_message.png and b/doc/user/project/img/issue_board_welcome_message.png differ diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index a0edc062f99..0ad21606ef6 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -36,8 +36,8 @@ There are three types of lists, of which two are default: In short, here's a list of actions you can take in an Issue Board: -- [Add a new list](#adding-a-new-list). -- [Remove an existing list](#removing-a-list). +- [Create a new list](#creating-a-new-list). +- [Delete an existing list](#deleting-a-list). - Drag issues between lists. - Drag and reorder the lists themselves. - Change issue labels on-the-fly while dragging issues between lists. @@ -62,10 +62,10 @@ because the labels associated to them will not exist up until that moment, which means the system has no way of populating them automatically. It'll be the users' job to add individual issues to them. -## Adding a new list +## Creating a new list -Add a new list by clicking on the **Add new list** button at the upper right -corner of the Issue Board. +Create a new list by clicking on the **Create new list** button at the upper +right corner of the Issue Board. ![Issue Board welcome message](img/issue_board_add_list.png) @@ -73,16 +73,16 @@ Simply choose the label to create the list from. The new list will be inserted at the end of the lists, before **Done**. Moving and reordering lists is as easy as dragging them around. -To add a list for a label that doesn't exist yet, simply create the label by +To create a list for a label that doesn't exist yet, simply create the label by choosing **Create new label**. The label will be created on-the-fly and it will -be immediately added to the dropdown. You can now choose it to add a list. +be immediately added to the dropdown. You can now choose it to create a list. -## Removing a list +## Deleting a list -To remove a list from the Issue Board use the small trash icon that is present +To delete a list from the Issue Board use the small trash icon that is present in the list's heading. A confirmation dialog will appear for you to confirm. -Removing a list doesn't have any effect in issues and labels, it's just the +Deleting a list doesn't have any effect in issues and labels, it's just the list view that is removed. ## Filtering issues @@ -114,13 +114,13 @@ A typical workflow of using the Issue Board would be: 1. When the issue is finally resolved, the issue is moved to the **Done** list and gets automatically closed. -For instance you can add a -list based on the label of 'Frontend' and one for 'Backend'. A designer can start -working on an issue by dragging it from **Backlog** to 'Frontend'. That way, everyone -knows that this issue is now being worked on by the designers. Then, once they’re -done, all they have to do is drag it over to the next list, 'Backend', where a -backend developer can eventually pick it up. Once they’re done, they move it to -**Done**, to close the issue. +For instance you can add a list based on the label of 'Frontend' and one for +'Backend'. A designer can start working on an issue by dragging it from +**Backlog** to 'Frontend'. That way, everyone knows that this issue is now being +worked on by the designers. Then, once they're done, all they have to do is +drag it over to the next list, 'Backend', where a backend developer can +eventually pick it up. Once they’re done, they move it to **Done**, to close the +issue. ## Permissions -- cgit v1.2.1 From 04d4208eed39d72ba4886c9920796d0172a20627 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 19 Aug 2016 08:30:59 +0300 Subject: Add section on searching through the Backlog list --- .../project/img/issue_board_search_backlog.png | Bin 0 -> 25948 bytes doc/user/project/issue_board.md | 21 +++++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 doc/user/project/img/issue_board_search_backlog.png (limited to 'doc/user') diff --git a/doc/user/project/img/issue_board_search_backlog.png b/doc/user/project/img/issue_board_search_backlog.png new file mode 100644 index 00000000000..112ea171539 Binary files /dev/null and b/doc/user/project/img/issue_board_search_backlog.png differ diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 0ad21606ef6..edc93f6bc13 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -85,6 +85,24 @@ in the list's heading. A confirmation dialog will appear for you to confirm. Deleting a list doesn't have any effect in issues and labels, it's just the list view that is removed. +## Searching issues in the Backlog list + +The very first time you start using the Issue Board, it is very likely your +issue tracker is already populated with labels and issues. In that case, +**Backlog** will have all the issues that don't belong to another list, and +**Done** will have all the closed ones. + +For performance and visibility reasons, each list shows the first 20 issues +by default. If you have more than 20, you have to start scrolling down for the +next 20 issues to appear. This can be cumbersome if your issue tracker hosts +hundreds of issues, and for that reason it is easier to search for issues to +move from **Backlog** to another list. + +Start typing in the search bar under the **Backlog** list and the relevant +issues will appear. + +![Issue Board search Backlog](img/issue_board_search_backlog.png) + ## Filtering issues You should be able to use the filters on top of your Issue Board to show only @@ -141,6 +159,9 @@ A few things to remember: - Clicking on a label inside a card will quickly filter the entire Issue Board and show only the issues from all lists that have that label. - Issues inside lists are [ordered by priority](labels.md#prioritize-labels). +- For performance and visibility reasons, each list shows the first 20 issues + by default. If you have more than 20 issues start scrolling down and the next + 20 will appear. [ce-5554]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5554 [labels]: ./labels.md -- cgit v1.2.1 From 3a737e7ea5d4a497489e38ed1e1f14140d7c45e3 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 19 Aug 2016 08:35:39 +0300 Subject: Mention missing labels for corresponding lists --- doc/user/project/issue_board.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/user') diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index edc93f6bc13..f3fd7e1ec1a 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -149,6 +149,7 @@ Issue Board, that is add/remove lists and drag issues around. A few things to remember: +- The label that corresponds to a list is hidden for issues under that list. - Moving an issue between lists removes the label from the list it came from and adds the label from the list it goes to. - When moving a card to **Done**, the label of the list it came from is removed -- cgit v1.2.1 From 3d1b24767b292af2bcadd3de728abd9a1d08cdb6 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 19 Aug 2016 08:44:39 +0300 Subject: Add note about labels and system notes --- doc/user/project/img/issue_board_system_notes.png | Bin 0 -> 20637 bytes doc/user/project/issue_board.md | 5 +++++ 2 files changed, 5 insertions(+) create mode 100644 doc/user/project/img/issue_board_system_notes.png (limited to 'doc/user') diff --git a/doc/user/project/img/issue_board_system_notes.png b/doc/user/project/img/issue_board_system_notes.png new file mode 100644 index 00000000000..b69ef034954 Binary files /dev/null and b/doc/user/project/img/issue_board_system_notes.png differ diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index f3fd7e1ec1a..c0b040c3c07 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -140,6 +140,11 @@ drag it over to the next list, 'Backend', where a backend developer can eventually pick it up. Once they’re done, they move it to **Done**, to close the issue. +This process can be seen clearly when visiting an issue since with every move +to another list the label changes and a system not is recorded. + +![Issue Board system notes](img/issue_board_system_notes.png) + ## Permissions [Developers and up](../permissions.md) can use all the functionality of the -- cgit v1.2.1 From fa72b5fa1481f49758cef45fa37c6d1d4e261e3a Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Sat, 20 Aug 2016 18:21:30 +0300 Subject: Fix typos and grammar --- doc/user/project/issue_board.md | 49 +++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 22 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index c0b040c3c07..33db21d442b 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -17,13 +17,14 @@ issue tracker. Below is a table of the definitions used for GitLab's Issue Board. -| How we call it | What it means | +| What we call it | What it means | | -------------- | ------------- | | **Issue Board** | It represents a different view for your issues. It can have multiple lists with each list consisting of issues represented by cards. | | **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. | -| **Card** | Every card represents an issue and it is shown under the list for which it has a label for. The information you can see on a card consists of the issue number, the issue title, the assignee and the labels associated with it. You can drag cards around from one list to another. Issues inside lists are [ordered by priority](labels.md#prioritize-labels). | +| **Card** | Every card represents an issue and it is shown under the list for which it has a label. The information you can see on a card consists of the issue number, the issue title, the assignee and the labels associated with it. You can drag cards around from one list to another. Issues inside lists are [ordered by priority](labels.md#prioritize-labels). | -There are three types of lists, of which two are default: +There are three types of lists, the ones you create based on your labels, and +two default: - **Backlog** (default): shows all issues that do not fall in one of the other lists. Always appears on the very left. @@ -42,7 +43,8 @@ In short, here's a list of actions you can take in an Issue Board: - Drag and reorder the lists themselves. - Change issue labels on-the-fly while dragging issues between lists. - Close an issue if you drag it to the **Done** list. -- Add a new list from a non-existing label by creating the label on-the-fly. +- Create a new list from a non-existing label by [creating the label on-the-fly](#creating-a-new-list) + within the Issue Board. - [Filter issues](#filtering-issues) that appear across your Issue Board. If you are not able to perform one or more of the things above, make sure you @@ -51,16 +53,17 @@ have the right [permissions](#permissions). ## First time using the Issue Board The first time you navigate to your Issue Board, you will be presented with the -two special lists (**Backlog** and **Done**) and a welcoming message that gives -you two options. You can either create a predefined set of labels and add their -corresponding lists to the Issue Board or opt-out and use your own lists. +two default lists (**Backlog** and **Done**) and a welcoming message that gives +you two options. You can either create a predefined set of labels and create +their corresponding lists to the Issue Board or opt-out and use your own lists. ![Issue Board welcome message](img/issue_board_welcome_message.png) -If you choose to use and add the default lists, they will appear as empty +If you choose to use and create the predefined lists, they will appear as empty because the labels associated to them will not exist up until that moment, -which means the system has no way of populating them automatically. It'll be -the users' job to add individual issues to them. +which means the system has no way of populating them automatically. That's of +course if the predefined labels don't already exist. If any of them does exist, +the list will be created and filled with the issues that have that label. ## Creating a new list @@ -73,7 +76,7 @@ Simply choose the label to create the list from. The new list will be inserted at the end of the lists, before **Done**. Moving and reordering lists is as easy as dragging them around. -To create a list for a label that doesn't exist yet, simply create the label by +To create a list for a label that doesn't yet exist, simply create the label by choosing **Create new label**. The label will be created on-the-fly and it will be immediately added to the dropdown. You can now choose it to create a list. @@ -83,7 +86,7 @@ To delete a list from the Issue Board use the small trash icon that is present in the list's heading. A confirmation dialog will appear for you to confirm. Deleting a list doesn't have any effect in issues and labels, it's just the -list view that is removed. +list view that is removed. You can always add it back later if you need. ## Searching issues in the Backlog list @@ -113,7 +116,7 @@ You can filter by author, assignee, milestone and label. ## Creating workflows -By adding new lists, you can create workflows. As lists in Issue Boards are +By reordering your lists, you can create workflows. As lists in Issue Boards are based on labels, it works out of the box with your existing issues. So if you've already labeled things with 'Backend' and 'Frontend', the issue will appear in the lists as you create them. In addition, this means you can easily move @@ -121,9 +124,10 @@ something between lists by changing a label. A typical workflow of using the Issue Board would be: -1. You have [created labels] so that you can easily categorize your issues. +1. You have [created][create-labels] and [prioritized][label-priority] labels + so that you can easily categorize your issues. 1. You have a bunch of issues (ideally labeled). -1. You visit the Issue Board and start [adding lists](#adding-a-new-list) as to +1. You visit the Issue Board and start [creating lists](#creating-a-new-list) to create a workflow. 1. You move issues around in lists so that your team knows who should be working on what issue. @@ -132,7 +136,7 @@ A typical workflow of using the Issue Board would be: 1. When the issue is finally resolved, the issue is moved to the **Done** list and gets automatically closed. -For instance you can add a list based on the label of 'Frontend' and one for +For instance you can create a list based on the label of 'Frontend' and one for 'Backend'. A designer can start working on an issue by dragging it from **Backlog** to 'Frontend'. That way, everyone knows that this issue is now being worked on by the designers. Then, once they're done, all they have to do is @@ -148,7 +152,7 @@ to another list the label changes and a system not is recorded. ## Permissions [Developers and up](../permissions.md) can use all the functionality of the -Issue Board, that is add/remove lists and drag issues around. +Issue Board, that is create/delete lists and drag issues around. ## Tips @@ -158,13 +162,13 @@ A few things to remember: - Moving an issue between lists removes the label from the list it came from and adds the label from the list it goes to. - When moving a card to **Done**, the label of the list it came from is removed - the issue gets closed. -- An issue can exist in multiple lists if it has more than one labels. + and the issue gets closed. +- An issue can exist in multiple lists if it has more than one label. - Lists are populated with issues automatically if the issues are labeled. -- Clicking on the issue title inside a card will get you to that issue. +- Clicking on the issue title inside a card will take you to that issue. - Clicking on a label inside a card will quickly filter the entire Issue Board and show only the issues from all lists that have that label. -- Issues inside lists are [ordered by priority](labels.md#prioritize-labels). +- Issues inside lists are [ordered by priority][label-priority]. - For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues start scrolling down and the next 20 will appear. @@ -173,4 +177,5 @@ A few things to remember: [labels]: ./labels.md [scrum]: https://en.wikipedia.org/wiki/Scrum_(software_development) [kanban]: https://en.wikipedia.org/wiki/Kanban_(development) -[created labels]: ./labels.md#create-new-labels +[create-labels]: ./labels.md#create-new-labels +[label-priority]: ./labels.md#prioritize-labels -- cgit v1.2.1 From 31584d8e5518da596cfc0b963e7a403a461e098f Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Sat, 20 Aug 2016 18:41:57 +0300 Subject: Add links to landing page and youtube video --- doc/user/project/issue_board.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc/user') diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 33db21d442b..9df9ed9c9da 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -6,6 +6,11 @@ The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow for a feature or product release. It can be seen like a light version of a [Kanban] or a [Scrum] board. +Other interesting links: + +- [GitLab Issue Board landing page on about.gitlab.com][landing] +- [YouTube video introduction to Issue Boards][youtube] + ## Overview The Issue Board builds on GitLab's existing issue tracking functionality and @@ -179,3 +184,5 @@ A few things to remember: [kanban]: https://en.wikipedia.org/wiki/Kanban_(development) [create-labels]: ./labels.md#create-new-labels [label-priority]: ./labels.md#prioritize-labels +[landing]: https://about.gitlab.com/solutions/issueboard +[youtube]: https://www.youtube.com/watch?v=UWsJ8tkHAa8 -- cgit v1.2.1 From 915dda1421d8227c0ba395bfdb04ff915724c4ac Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 22 Aug 2016 17:09:15 +0300 Subject: Split Koding admin/user docs --- doc/user/project/img/koding_build-in-progress.png | Bin 0 -> 70949 bytes doc/user/project/img/koding_build-logs.png | Bin 0 -> 263623 bytes doc/user/project/img/koding_build-success.png | Bin 0 -> 304666 bytes doc/user/project/img/koding_commit-koding.yml.png | Bin 0 -> 302703 bytes .../img/koding_different-stack-on-mr-try.png | Bin 0 -> 333649 bytes doc/user/project/img/koding_edit-on-ide.png | Bin 0 -> 330880 bytes doc/user/project/img/koding_enable-koding.png | Bin 0 -> 73499 bytes doc/user/project/img/koding_landing.png | Bin 0 -> 268455 bytes .../project/img/koding_open-gitlab-from-koding.png | Bin 0 -> 32559 bytes doc/user/project/img/koding_run-in-ide.png | Bin 0 -> 65465 bytes doc/user/project/img/koding_run-mr-in-ide.png | Bin 0 -> 339759 bytes doc/user/project/img/koding_set-up-ide.png | Bin 0 -> 207481 bytes doc/user/project/img/koding_stack-import.png | Bin 0 -> 500352 bytes doc/user/project/img/koding_start-build.png | Bin 0 -> 105253 bytes doc/user/project/koding.md | 128 +++++++++++++++++++++ 15 files changed, 128 insertions(+) create mode 100644 doc/user/project/img/koding_build-in-progress.png create mode 100644 doc/user/project/img/koding_build-logs.png create mode 100644 doc/user/project/img/koding_build-success.png create mode 100644 doc/user/project/img/koding_commit-koding.yml.png create mode 100644 doc/user/project/img/koding_different-stack-on-mr-try.png create mode 100644 doc/user/project/img/koding_edit-on-ide.png create mode 100644 doc/user/project/img/koding_enable-koding.png create mode 100644 doc/user/project/img/koding_landing.png create mode 100644 doc/user/project/img/koding_open-gitlab-from-koding.png create mode 100644 doc/user/project/img/koding_run-in-ide.png create mode 100644 doc/user/project/img/koding_run-mr-in-ide.png create mode 100644 doc/user/project/img/koding_set-up-ide.png create mode 100644 doc/user/project/img/koding_stack-import.png create mode 100644 doc/user/project/img/koding_start-build.png create mode 100644 doc/user/project/koding.md (limited to 'doc/user') diff --git a/doc/user/project/img/koding_build-in-progress.png b/doc/user/project/img/koding_build-in-progress.png new file mode 100644 index 00000000000..f8cc81834c4 Binary files /dev/null and b/doc/user/project/img/koding_build-in-progress.png differ diff --git a/doc/user/project/img/koding_build-logs.png b/doc/user/project/img/koding_build-logs.png new file mode 100644 index 00000000000..a04cd5aff99 Binary files /dev/null and b/doc/user/project/img/koding_build-logs.png differ diff --git a/doc/user/project/img/koding_build-success.png b/doc/user/project/img/koding_build-success.png new file mode 100644 index 00000000000..2a0dd296480 Binary files /dev/null and b/doc/user/project/img/koding_build-success.png differ diff --git a/doc/user/project/img/koding_commit-koding.yml.png b/doc/user/project/img/koding_commit-koding.yml.png new file mode 100644 index 00000000000..3e133c50327 Binary files /dev/null and b/doc/user/project/img/koding_commit-koding.yml.png differ diff --git a/doc/user/project/img/koding_different-stack-on-mr-try.png b/doc/user/project/img/koding_different-stack-on-mr-try.png new file mode 100644 index 00000000000..fd25e32f648 Binary files /dev/null and b/doc/user/project/img/koding_different-stack-on-mr-try.png differ diff --git a/doc/user/project/img/koding_edit-on-ide.png b/doc/user/project/img/koding_edit-on-ide.png new file mode 100644 index 00000000000..fd5aaff75f5 Binary files /dev/null and b/doc/user/project/img/koding_edit-on-ide.png differ diff --git a/doc/user/project/img/koding_enable-koding.png b/doc/user/project/img/koding_enable-koding.png new file mode 100644 index 00000000000..c0ae0ee9918 Binary files /dev/null and b/doc/user/project/img/koding_enable-koding.png differ diff --git a/doc/user/project/img/koding_landing.png b/doc/user/project/img/koding_landing.png new file mode 100644 index 00000000000..7c629d9b05e Binary files /dev/null and b/doc/user/project/img/koding_landing.png differ diff --git a/doc/user/project/img/koding_open-gitlab-from-koding.png b/doc/user/project/img/koding_open-gitlab-from-koding.png new file mode 100644 index 00000000000..c958cf8f224 Binary files /dev/null and b/doc/user/project/img/koding_open-gitlab-from-koding.png differ diff --git a/doc/user/project/img/koding_run-in-ide.png b/doc/user/project/img/koding_run-in-ide.png new file mode 100644 index 00000000000..f91ee0f74cc Binary files /dev/null and b/doc/user/project/img/koding_run-in-ide.png differ diff --git a/doc/user/project/img/koding_run-mr-in-ide.png b/doc/user/project/img/koding_run-mr-in-ide.png new file mode 100644 index 00000000000..502817a2a46 Binary files /dev/null and b/doc/user/project/img/koding_run-mr-in-ide.png differ diff --git a/doc/user/project/img/koding_set-up-ide.png b/doc/user/project/img/koding_set-up-ide.png new file mode 100644 index 00000000000..7f408c980b5 Binary files /dev/null and b/doc/user/project/img/koding_set-up-ide.png differ diff --git a/doc/user/project/img/koding_stack-import.png b/doc/user/project/img/koding_stack-import.png new file mode 100644 index 00000000000..2a4e3c87fc8 Binary files /dev/null and b/doc/user/project/img/koding_stack-import.png differ diff --git a/doc/user/project/img/koding_start-build.png b/doc/user/project/img/koding_start-build.png new file mode 100644 index 00000000000..52159440f62 Binary files /dev/null and b/doc/user/project/img/koding_start-build.png differ diff --git a/doc/user/project/koding.md b/doc/user/project/koding.md new file mode 100644 index 00000000000..e54587fab68 --- /dev/null +++ b/doc/user/project/koding.md @@ -0,0 +1,128 @@ +# Koding & GitLab + +> [Introduced][ce-5909] in GitLab 8.11. + +This document will guide you through using Koding integration on GitLab in +detail. For configuring and installing please follow the +[administrator guide](../../administration/integration/koding.md). + +You can use Koding integration to run and develop your projects on GitLab. This +will allow you and the users to test your project without leaving the browser. +Koding handles projects as stacks which are basic recipes to define your +environment for your project. With this integration you can automatically +create a proper stack template for your projects. Currently auto-generated +stack templates are designed to work with AWS which requires a valid AWS +credential to be able to use these stacks. You can find more information about +stacks and the other providers that you can use on Koding following the +[Koding documentation][koding-docs]. + +## Enable Integration + +You can enable Koding integration by providing the running Koding instance URL +in Application Settings under **Admin area > Settings** (`/admin/application_settings`). + +![Enable Koding](img/koding_enable-koding.png) + +Once enabled you will see `Koding` link on your sidebar which leads you to +Koding Landing page. + +![Koding Landing](img/koding_landing.png) + +You can navigate to running Koding instance from here. For more information and +details about configuring the integration, please follow the +[administrator guide](../../administration/integration/koding.md). + +## Set up Koding on Projects + +Once it's enabled, you will see some integration buttons on Project pages, +Merge Requests etc. To get started working on a specific project you first need +to create a `.koding.yml` file under your project root. You can easily do that +by using `Set Up Koding` button which will be visible on every project's +landing page; + +![Set Up Koding](img/koding_set-up-ide.png) + +Once you click this will open a New File page on GitLab with auto-generated +`.koding.yml` content based on your server and repository configuration. + +![Commit .koding.yml](img/koding_commit-koding.yml.png) + + +## Run a project on Koding + +If there is `.koding.yml` exists in your project root, you will see +`Run in IDE (Koding)` button in your project landing page. You can initiate the +process from here. + +![Run on Koding](img/koding_run-in-ide.png) + +This will open Koding defined in the settings in a new window and will start +importing the project's stack file. + +![Import Stack](img/koding_stack-import.png) + +You should see the details of your repository imported into your Koding +instance. Once it's completed it will lead you to the Stack Editor and from +there you can start using your new stack integrated with your project on your +GitLab instance. For details about what's next you can follow +[this guide](https://www.koding.com/docs/creating-an-aws-stack) from step 8. + +Once stack initialized you will see the `README.md` content from your project +in `Stack Build` wizard, this wizard will let you to build the stack and import +your project into it. **Once it's completed it will automatically open the +related vm instead of importing from scratch**. + +![Stack Building](img/koding_start-build.png) + +This will take time depending on the required environment. + +![Stack Building in Progress](img/koding_build-in-progress.png) + +It usually takes ~4 min. to make it ready with a `t2.nano` instance on given +AWS region. (`t2.nano` is default vm type on auto-generated stack template +which can be manually changed). + +![Stack Building Success](img/koding_build-success.png) + +You can check out the `Build Logs` from this success modal as well. + +![Stack Build Logs](img/koding_build-logs.png) + +You can now `Start Coding`! + +![Edit On IDE](img/koding_edit-on-ide.png) + +## Try a Merge Request on IDE + +It's also possible to try a change on IDE before merging it. This flow only +enabled if the target project has `.koding.yml` in it's target branch. You +should see the alternative version of `Run in IDE (Koding)` button in merge +request pages as well; + +![Run in IDE on MR](img/koding_run-mr-in-ide.png) + +This will again take you to Koding with proper arguments passed, which will +allow Koding to modify the stack template provided by target branch. You can +see the difference; + +![Different Branch for MR](img/koding_different-stack-on-mr-try.png) + +The flow for the branch stack is also same with the regular project flow. + +## Open GitLab from Koding + +Since stacks generated with import flow defined in previous steps, they have +information about the repository they are belonging to. By using this +information you can access to related GitLab page from stacks on your sidebar +on Koding. + +![Open GitLab from Koding](img/koding_open-gitlab-from-koding.png) + +## Other links + +- [YouTube video on GitLab + Koding workflow][youtube] +- [Koding documentation][koding-docs] + +[ce-5909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5909 +[youtube]: https://youtu.be/3wei5yv_Ye8 +[koding-docs]: https://www.koding.com/docs -- cgit v1.2.1 From bba85773519e972d036a933b1f054b6c76050c5f Mon Sep 17 00:00:00 2001 From: Drew Blessing Date: Tue, 26 Jul 2016 16:48:51 -0500 Subject: Add two factor recovery endpoint to internal API --- doc/user/account/security.md | 3 ++ doc/user/account/two_factor_authentication.md | 68 +++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 doc/user/account/security.md create mode 100644 doc/user/account/two_factor_authentication.md (limited to 'doc/user') diff --git a/doc/user/account/security.md b/doc/user/account/security.md new file mode 100644 index 00000000000..816094bf8d2 --- /dev/null +++ b/doc/user/account/security.md @@ -0,0 +1,3 @@ +# Account Security + +- [Two-Factor Authentication](two_factor_authentication.md) diff --git a/doc/user/account/two_factor_authentication.md b/doc/user/account/two_factor_authentication.md new file mode 100644 index 00000000000..881358ed94d --- /dev/null +++ b/doc/user/account/two_factor_authentication.md @@ -0,0 +1,68 @@ +# Two-Factor Authentication + +## Recovery options + +If you lose your code generation device (such as your mobile phone) and you need +to disable two-factor authentication on your account, you have several options. + +### Use a saved recovery code + +When you enabled two-factor authentication for your account, a series of +recovery codes were generated. If you saved those codes somewhere safe, you +may use one to sign in. + +First, enter your username/email and password on the GitLab sign in page. When +prompted for a two-factor code, enter one of the recovery codes you saved +previously. + +> **Note:** Once a particular recovery code has been used, it cannot be used again. + You may still use the other saved recovery codes at a later time. + +### Generate new recovery codes using SSH + +It's not uncommon for users to forget to save the recovery codes when enabling +two-factor authentication. If you have an SSH key added to your GitLab account, +you can generate a new set of recovery codes using SSH. + +Run `ssh git@gitlab.example.com 2fa_recovery_codes`. You will be prompted to +confirm that you wish to generate new codes. If you choose to continue, any +previously saved codes will be invalidated. + +```bash +$ ssh git@gitlab.example.com 2fa_recovery_codes +Are you sure you want to generate new two-factor recovery codes? +Any existing recovery codes you saved will be invalidated. (yes/no) +yes + +Your two-factor authentication recovery codes are: + +119135e5a3ebce8e +11f6v2a498810dcd +3924c7ab2089c902 +e79a3398bfe4f224 +34bd7b74adbc8861 +f061691d5107df1a +169bf32a18e63e7f +b510e7422e81c947 +20dbed24c5e74663 +df9d3b9403b9c9f0 + +During sign in, use one of the codes above when prompted for +your two-factor code. Then, visit your Profile Settings and add +a new device so you do not lose access to your account again. +``` + +Next, go to the GitLab sign in page and enter your username/email and password. +When prompted for a two-factor code, enter one of the recovery codes obtained +from the command line output. + +> **Note:** After signing in, you should immediately visit your **Profile Settings + -> Account** to set up two-factor authentication with a new device. + +### Ask a GitLab administrator to disable two-factor on your account + +If the above two methods are not possible, you may ask a GitLab global +administrator to disable two-factor authentication for your account. Please +be aware that this will temporarily leave your account in a less secure state. +You should sign in and re-enable two-factor authentication as soon as possible +after the administrator disables it. -- cgit v1.2.1 From 44eb3197a9c30503a00384b3d688b64558b80397 Mon Sep 17 00:00:00 2001 From: Sean McGivern Date: Tue, 23 Aug 2016 16:37:14 +0100 Subject: Handle non-UTF-8 conflicts gracefully These can't be resolved in the UI because if they aren't in a UTF-8 compatible encoding, they can't be rendered as JSON. Even if they could, we would be implicitly changing the file encoding anyway, which seems like a bad idea. --- doc/user/project/merge_requests/resolve_conflicts.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/user') diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index 44b76ffc8e6..4d7225bd820 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -26,6 +26,7 @@ this is similar to performing `git checkout feature; git merge master` locally. GitLab allows resolving conflicts in a file where all of the below are true: - The file is text, not binary +- The file is in a UTF-8 compatible encoding - The file does not already contain conflict markers - The file, with conflict markers added, is not over 200 KB in size - The file exists under the same path in both branches -- cgit v1.2.1 From cad63d4045623391d5e36ff541d531b6dfae7d81 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 25 Aug 2016 10:21:51 +0200 Subject: Use new image for Issue Board page [ci skip] --- doc/user/project/img/issue_board.png | Bin 200614 -> 275093 bytes 1 file changed, 0 insertions(+), 0 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/img/issue_board.png b/doc/user/project/img/issue_board.png index accd0900cbb..63c269f6dbc 100644 Binary files a/doc/user/project/img/issue_board.png and b/doc/user/project/img/issue_board.png differ -- cgit v1.2.1 From 3eb4c74f88dfb316d695dc9396b88555bf314189 Mon Sep 17 00:00:00 2001 From: Douglas Barbosa Alexandre Date: Wed, 24 Aug 2016 15:19:36 -0300 Subject: Update Issue board documentation --- doc/user/project/issue_board.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 9df9ed9c9da..cac926b3e28 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -31,10 +31,9 @@ Below is a table of the definitions used for GitLab's Issue Board. There are three types of lists, the ones you create based on your labels, and two default: -- **Backlog** (default): shows all issues that do not fall in one of the other - lists. Always appears on the very left. -- **Done** (default): shows all closed issues. Always appears on the very right. -- Label list: a list based on a label. It shows all issues with that label. +- **Backlog** (default): shows all opened issues that do not fall in one of the other lists. Always appears on the very left. +- **Done** (default): shows all closed issues that do not fall in one of the other lists. Always appears on the very right. +- Label list: a list based on a label. It shows all opened or closed issues with that label. ![GitLab Issue Board](img/issue_board.png) -- cgit v1.2.1 From 1aed63dad2fc87ec04cbef86627507348a2eca47 Mon Sep 17 00:00:00 2001 From: "Federico \"Lox" Date: Thu, 25 Aug 2016 21:01:43 +0000 Subject: Fix `Stack Build` wizard description in koding.md --- doc/user/project/koding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/user') diff --git a/doc/user/project/koding.md b/doc/user/project/koding.md index e54587fab68..c56a1efe3c2 100644 --- a/doc/user/project/koding.md +++ b/doc/user/project/koding.md @@ -68,7 +68,7 @@ GitLab instance. For details about what's next you can follow [this guide](https://www.koding.com/docs/creating-an-aws-stack) from step 8. Once stack initialized you will see the `README.md` content from your project -in `Stack Build` wizard, this wizard will let you to build the stack and import +in `Stack Build` wizard, this wizard will let you build the stack and import your project into it. **Once it's completed it will automatically open the related vm instead of importing from scratch**. -- cgit v1.2.1 From aeb280b0ccb7186b75cf73fcd2e051c5ed661443 Mon Sep 17 00:00:00 2001 From: Clement Ho Date: Thu, 25 Aug 2016 09:19:14 -0500 Subject: Fix markdown help references --- doc/user/markdown.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'doc/user') diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 7fe96e67dbb..c7fda8a497f 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -66,7 +66,7 @@ dependency to do so. Please see the [github-markup gem readme](https://github.co ## Newlines > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#newlines +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#newlines GFM honors the markdown specification in how [paragraphs and line breaks are handled](https://daringfireball.net/projects/markdown/syntax#p). @@ -86,7 +86,7 @@ Sugar is sweet ## Multiple underscores in words > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#multiple-underscores-in-words +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiple-underscores-in-words It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names that often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words: @@ -101,7 +101,7 @@ do_this_and_do_that_and_another_thing ## URL auto-linking > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#url-auto-linking +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#url-auto-linking GFM will autolink almost any URL you copy and paste into your text: @@ -122,7 +122,7 @@ GFM will autolink almost any URL you copy and paste into your text: ## Multiline Blockquote > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#multiline-blockquote +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#multiline-blockquote On top of standard Markdown [blockquotes](#blockquotes), which require prepending `>` to quoted lines, GFM supports multiline blockquotes fenced by >>>: @@ -156,7 +156,7 @@ you can quote that without having to manually prepend `>` to every line! ## Code and Syntax Highlighting > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#code-and-syntax-highlighting +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#code-and-syntax-highlighting _GitLab uses the [Rouge Ruby library][rouge] for syntax highlighting. For a list of supported languages visit the Rouge website._ @@ -226,7 +226,7 @@ But let's throw in a tag. ## Inline Diff > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#inline-diff +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff With inline diffs tags you can display {+ additions +} or [- deletions -]. @@ -242,7 +242,7 @@ However the wrapping tags cannot be mixed as such: ## Emoji > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#emoji +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#emoji Sometimes you want to :monkey: around a bit and add some :star2: to your :speech_balloon:. Well we have a gift for you: @@ -307,7 +307,7 @@ GFM also recognizes certain cross-project references: ## Task Lists > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#task-lists +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#task-lists You can add task lists to issues, merge requests and comments. To create a task list, add a specially-formatted Markdown list, like so: @@ -330,7 +330,7 @@ Task lists can only be created in descriptions, not in titles. Task item state c ## Videos > If this is not rendered correctly, see -https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md#videos +https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#videos Image tags with a video extension are automatically converted to a video player. @@ -780,7 +780,7 @@ A link starting with a `/` is relative to the wiki root. - The [Markdown Syntax Guide](https://daringfireball.net/projects/markdown/syntax) at Daring Fireball is an excellent resource for a detailed explanation of standard markdown. - [Dillinger.io](http://dillinger.io) is a handy tool for testing standard markdown. -[markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/markdown/markdown.md +[markdown.md]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md [rouge]: http://rouge.jneen.net/ "Rouge website" [redcarpet]: https://github.com/vmg/redcarpet "Redcarpet website" [^1]: This link will be broken if you see this document from the Help page or docs.gitlab.com -- cgit v1.2.1 From e8b66d4bc70f33139f51a1154b2c2090cc6a814b Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Mon, 22 Aug 2016 09:59:15 +0200 Subject: Fix due date example in slash commands documentation --- doc/user/project/slash_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/user') diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md index 11e1574f772..cfdf04a32a3 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -26,5 +26,5 @@ do. | `/done` | Mark todo as done | | `/subscribe` | Subscribe | | `/unsubscribe` | Unsubscribe | -| `/due ` | Set due date | +| /due in 2 days | this Friday | December 31st | Set due date | | `/remove_due_date` | Remove due date | -- cgit v1.2.1 From 700ffcf16cd6816fa0e4c65c0d40136d6f29fd36 Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Mon, 29 Aug 2016 10:16:09 +0200 Subject: Add angle brackets around due date in slash cmds docs --- doc/user/project/slash_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/user') diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md index cfdf04a32a3..1792a0c501d 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -26,5 +26,5 @@ do. | `/done` | Mark todo as done | | `/subscribe` | Subscribe | | `/unsubscribe` | Unsubscribe | -| /due in 2 days | this Friday | December 31st | Set due date | +| /due <in 2 days | this Friday | December 31st> | Set due date | | `/remove_due_date` | Remove due date | -- cgit v1.2.1 From 892dea67717c0efbd6a28f7639f34535ec0a8747 Mon Sep 17 00:00:00 2001 From: Felipe Artur Date: Mon, 1 Aug 2016 19:31:21 -0300 Subject: Project tools visibility level --- doc/user/permissions.md | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'doc/user') diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 66542861781..1498cb361c8 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -104,6 +104,15 @@ will find the option to flag the user as external. By default new users are not set as external users. This behavior can be changed by an administrator under **Admin > Application Settings**. +## Project features + +Project features like wiki and issues can be hidden from users depending on +which visibility level you select on project settings. + +- Disabled: disabled for everyone +- Only team members: only team members will see even if your project is public or internal +- Everyone with access: everyone can see depending on your project visibility level + ## GitLab CI GitLab CI permissions rely on the role the user has in GitLab. There are four -- cgit v1.2.1 From 30b56b160b854baf03bfacd80c0e87d62716dd0f Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 2 Sep 2016 13:11:57 +0200 Subject: Move web_editor doc to new location --- .../img/web_editor_new_branch_dropdown.png | Bin 0 -> 20436 bytes .../repository/img/web_editor_new_branch_page.png | Bin 0 -> 11245 bytes .../img/web_editor_new_directory_dialog.png | Bin 0 -> 13339 bytes .../img/web_editor_new_directory_dropdown.png | Bin 0 -> 20007 bytes .../img/web_editor_new_file_dropdown.png | Bin 0 -> 20680 bytes .../repository/img/web_editor_new_file_editor.png | Bin 0 -> 66261 bytes .../repository/img/web_editor_new_push_widget.png | Bin 0 -> 7076 bytes .../repository/img/web_editor_new_tag_dropdown.png | Bin 0 -> 20080 bytes .../repository/img/web_editor_new_tag_page.png | Bin 0 -> 36610 bytes .../img/web_editor_start_new_merge_request.png | Bin 0 -> 8596 bytes .../img/web_editor_upload_file_dialog.png | Bin 0 -> 21502 bytes .../img/web_editor_upload_file_dropdown.png | Bin 0 -> 20651 bytes doc/user/project/repository/web_editor.md | 151 +++++++++++++++++++++ 13 files changed, 151 insertions(+) create mode 100644 doc/user/project/repository/img/web_editor_new_branch_dropdown.png create mode 100644 doc/user/project/repository/img/web_editor_new_branch_page.png create mode 100644 doc/user/project/repository/img/web_editor_new_directory_dialog.png create mode 100644 doc/user/project/repository/img/web_editor_new_directory_dropdown.png create mode 100644 doc/user/project/repository/img/web_editor_new_file_dropdown.png create mode 100644 doc/user/project/repository/img/web_editor_new_file_editor.png create mode 100644 doc/user/project/repository/img/web_editor_new_push_widget.png create mode 100644 doc/user/project/repository/img/web_editor_new_tag_dropdown.png create mode 100644 doc/user/project/repository/img/web_editor_new_tag_page.png create mode 100644 doc/user/project/repository/img/web_editor_start_new_merge_request.png create mode 100644 doc/user/project/repository/img/web_editor_upload_file_dialog.png create mode 100644 doc/user/project/repository/img/web_editor_upload_file_dropdown.png create mode 100644 doc/user/project/repository/web_editor.md (limited to 'doc/user') diff --git a/doc/user/project/repository/img/web_editor_new_branch_dropdown.png b/doc/user/project/repository/img/web_editor_new_branch_dropdown.png new file mode 100644 index 00000000000..a8e635d2faf Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_branch_dropdown.png differ diff --git a/doc/user/project/repository/img/web_editor_new_branch_page.png b/doc/user/project/repository/img/web_editor_new_branch_page.png new file mode 100644 index 00000000000..7f36b7faf63 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_branch_page.png differ diff --git a/doc/user/project/repository/img/web_editor_new_directory_dialog.png b/doc/user/project/repository/img/web_editor_new_directory_dialog.png new file mode 100644 index 00000000000..d16e3c67116 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_directory_dialog.png differ diff --git a/doc/user/project/repository/img/web_editor_new_directory_dropdown.png b/doc/user/project/repository/img/web_editor_new_directory_dropdown.png new file mode 100644 index 00000000000..c8d77b16ee8 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_directory_dropdown.png differ diff --git a/doc/user/project/repository/img/web_editor_new_file_dropdown.png b/doc/user/project/repository/img/web_editor_new_file_dropdown.png new file mode 100644 index 00000000000..3fcb91c9b93 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_file_dropdown.png differ diff --git a/doc/user/project/repository/img/web_editor_new_file_editor.png b/doc/user/project/repository/img/web_editor_new_file_editor.png new file mode 100644 index 00000000000..21c340b9288 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_file_editor.png differ diff --git a/doc/user/project/repository/img/web_editor_new_push_widget.png b/doc/user/project/repository/img/web_editor_new_push_widget.png new file mode 100644 index 00000000000..c7738a4c930 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_push_widget.png differ diff --git a/doc/user/project/repository/img/web_editor_new_tag_dropdown.png b/doc/user/project/repository/img/web_editor_new_tag_dropdown.png new file mode 100644 index 00000000000..ac7415009b3 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_tag_dropdown.png differ diff --git a/doc/user/project/repository/img/web_editor_new_tag_page.png b/doc/user/project/repository/img/web_editor_new_tag_page.png new file mode 100644 index 00000000000..231e1a13fc0 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_new_tag_page.png differ diff --git a/doc/user/project/repository/img/web_editor_start_new_merge_request.png b/doc/user/project/repository/img/web_editor_start_new_merge_request.png new file mode 100644 index 00000000000..2755501dfd1 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_start_new_merge_request.png differ diff --git a/doc/user/project/repository/img/web_editor_upload_file_dialog.png b/doc/user/project/repository/img/web_editor_upload_file_dialog.png new file mode 100644 index 00000000000..9d6d8250bbe Binary files /dev/null and b/doc/user/project/repository/img/web_editor_upload_file_dialog.png differ diff --git a/doc/user/project/repository/img/web_editor_upload_file_dropdown.png b/doc/user/project/repository/img/web_editor_upload_file_dropdown.png new file mode 100644 index 00000000000..6b5205b05ec Binary files /dev/null and b/doc/user/project/repository/img/web_editor_upload_file_dropdown.png differ diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md new file mode 100644 index 00000000000..ee8e7862572 --- /dev/null +++ b/doc/user/project/repository/web_editor.md @@ -0,0 +1,151 @@ +# GitLab Web Editor + +Sometimes it's easier to make quick changes directly from the GitLab interface +than to clone the project and use the Git command line tool. In this feature +highlight we look at how you can create a new file, directory, branch or +tag from the file browser. All of these actions are available from a single +dropdown menu. + +## Create a file + +From a project's files page, click the '+' button to the right of the branch selector. +Choose **New file** from the dropdown. + +![New file dropdown menu](img/web_editor_new_file_dropdown.png) + +--- + +Enter a file name in the **File name** box. Then, add file content in the editor +area. Add a descriptive commit message and choose a branch. The branch field +will default to the branch you were viewing in the file browser. If you enter +a new branch name, a checkbox will appear allowing you to start a new merge +request after you commit the changes. + +When you are satisfied with your new file, click **Commit Changes** at the bottom. + +![Create file editor](img/web_editor_new_file_editor.png) + +## Upload a file + +The ability to create a file is great when the content is text. However, this +doesn't work well for binary data such as images, PDFs or other file types. In +this case you need to upload a file. + +From a project's files page, click the '+' button to the right of the branch +selector. Choose **Upload file** from the dropdown. + +![Upload file dropdown menu](img/web_editor_upload_file_dropdown.png) + +--- + +Once the upload dialog pops up there are two ways to upload your file. Either +drag and drop a file on the pop up or use the **click to upload** link. A file +preview will appear once you have selected a file to upload. + +Enter a commit message, choose a branch, and click **Upload file** when you are +ready. + +![Upload file dialog](img/web_editor_upload_file_dialog.png) + +## Create a directory + +To keep files in the repository organized it is often helpful to create a new +directory. + +From a project's files page, click the '+' button to the right of the branch selector. +Choose **New directory** from the dropdown. + +![New directory dropdown](img/web_editor_new_directory_dropdown.png) + +--- + +In the new directory dialog enter a directory name, a commit message and choose +the target branch. Click **Create directory** to finish. + +![New directory dialog](img/web_editor_new_directory_dialog.png) + +## Create a new branch + +There are multiple ways to create a branch from GitLab's web interface. + +### Create a new branch from an issue + +> [Introduced][ce-2808] in GitLab 8.6. + +In case your development workflow dictates to have an issue for every merge +request, you can quickly create a branch right on the issue page which will be +tied with the issue itself. You can see a **New Branch** button after the issue +description, unless there is already a branch with the same name or a referenced +merge request. + +![New Branch Button](img/new_branch_from_issue.png) + +Once you click it, a new branch will be created that diverges from the default +branch of your project, by default `master`. The branch name will be based on +the title of the issue and as suffix it will have its ID. Thus, the example +screenshot above will yield a branch named +`2-et-cum-et-sed-expedita-repellat-consequatur-ut-assumenda-numquam-rerum`. + +After the branch is created, you can edit files in the repository to fix +the issue. When a merge request is created based on the newly created branch, +the description field will automatically display the [issue closing pattern] +`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the +merge request is merged. + +### Create a new branch from a project's dashboard + +If you want to make changes to several files before creating a new merge +request, you can create a new branch up front. From a project's files page, +choose **New branch** from the dropdown. + +![New branch dropdown](img/web_editor_new_branch_dropdown.png) + +--- + +Enter a new **Branch name**. Optionally, change the **Create from** field +to choose which branch, tag or commit SHA this new branch will originate from. +This field will autocomplete if you start typing an existing branch or tag. +Click **Create branch** and you will be returned to the file browser on this new +branch. + +![New branch page](img/web_editor_new_branch_page.png) + +--- + +You can now make changes to any files, as needed. When you're ready to merge +the changes back to master you can use the widget at the top of the screen. +This widget only appears for a period of time after you create the branch or +modify files. + +![New push widget](img/web_editor_new_push_widget.png) + +## Create a new tag + +Tags are useful for marking major milestones such as production releases, +release candidates, and more. You can create a tag from a branch or a commit +SHA. From a project's files page, choose **New tag** from the dropdown. + +![New tag dropdown](img/web_editor_new_tag_dropdown.png) + +--- + +Give the tag a name such as `v1.0.0`. Choose the branch or SHA from which you +would like to create this new tag. You can optionally add a message and +release notes. The release notes section supports markdown format and you can +also upload an attachment. Click **Create tag** and you will be taken to the tag +list page. + +![New tag page](img/web_editor_new_tag_page.png) + +## Tips + +When creating or uploading a new file, or creating a new directory, you can +trigger a new merge request rather than committing directly to master. Enter +a new branch name in the **Target branch** field. You will notice a checkbox +appear that is labeled **Start a new merge request with these changes**. After +you commit the changes you will be taken to a new merge request form. + +![Start a new merge request with these changes](img/web_editor_start_new_merge_request.png) + +[ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808 +[issue closing pattern]: ../customization/issue_closing.md -- cgit v1.2.1 From 7c89308ae4891085d59c6f85da77c5c13e0bd233 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 2 Sep 2016 13:28:17 +0200 Subject: Move docs for template dropdowns to the new location --- .../img/web_editor_template_dropdown_buttons.png | Bin 0 -> 14131 bytes .../web_editor_template_dropdown_first_file.png | Bin 0 -> 25748 bytes .../web_editor_template_dropdown_mit_license.png | Bin 0 -> 85413 bytes doc/user/project/repository/web_editor.md | 24 +++++++++++++++++++++ 4 files changed, 24 insertions(+) create mode 100644 doc/user/project/repository/img/web_editor_template_dropdown_buttons.png create mode 100644 doc/user/project/repository/img/web_editor_template_dropdown_first_file.png create mode 100644 doc/user/project/repository/img/web_editor_template_dropdown_mit_license.png (limited to 'doc/user') diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png b/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png new file mode 100644 index 00000000000..4efc51cc423 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_template_dropdown_buttons.png differ diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_first_file.png b/doc/user/project/repository/img/web_editor_template_dropdown_first_file.png new file mode 100644 index 00000000000..67190c58823 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_template_dropdown_first_file.png differ diff --git a/doc/user/project/repository/img/web_editor_template_dropdown_mit_license.png b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license.png new file mode 100644 index 00000000000..47719113805 Binary files /dev/null and b/doc/user/project/repository/img/web_editor_template_dropdown_mit_license.png differ diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index ee8e7862572..7c041d019bb 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -25,6 +25,29 @@ When you are satisfied with your new file, click **Commit Changes** at the botto ![Create file editor](img/web_editor_new_file_editor.png) +### Template dropdowns + +When starting a new project, there are some common files which the new project +might need too. Therefore a message will be displayed by GitLab to make this +easy for you. + +![First file for your project](img/web_editor_template_dropdown_first_file.png) + +When clicking on either `LICENSE` or `.gitignore`, a dropdown will be displayed +to provide you with a template which might be suitable for your project. + +![MIT license selected](img/web_editor_template_dropdown_mit_license.png) + +The license, changelog, contribution guide, or `.gitlab-ci.yml` file could also +be added through a button on the project page. In the example below the license +has already been created, which creates a link to the license itself. + +![New file button](img/web_editor_template_dropdown_buttons.png) + +>**Note:** +The **Set up CI** button will not appear on an empty repository. You have to at +least add a file in order for the button to show up. + ## Upload a file The ability to create a file is great when the content is text. However, this @@ -147,5 +170,6 @@ you commit the changes you will be taken to a new merge request form. ![Start a new merge request with these changes](img/web_editor_start_new_merge_request.png) +![New file button](basicsimages/file_button.png) [ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808 [issue closing pattern]: ../customization/issue_closing.md -- cgit v1.2.1 From 7973a22ff4f3ca4d34f69864e2438f1e44c1cfe2 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 12:13:11 +0200 Subject: Move `workflow/merge_requests.md` to `user/project/merge_requests.md` --- doc/user/project/merge_requests.md | 90 +++++++++++++++++++++ .../project/merge_requests/img/commit_compare.png | Bin 0 -> 65010 bytes .../merge_requests/img/merge_request_diff.png | Bin 0 -> 103239 bytes .../img/merge_request_diff_without_whitespace.png | Bin 0 -> 71896 bytes .../img/only_allow_merge_if_build_succeeds.png | Bin 0 -> 17552 bytes doc/user/project/merge_requests/img/versions.png | Bin 0 -> 100566 bytes 6 files changed, 90 insertions(+) create mode 100644 doc/user/project/merge_requests.md create mode 100644 doc/user/project/merge_requests/img/commit_compare.png create mode 100644 doc/user/project/merge_requests/img/merge_request_diff.png create mode 100644 doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png create mode 100644 doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png create mode 100644 doc/user/project/merge_requests/img/versions.png (limited to 'doc/user') diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md new file mode 100644 index 00000000000..ecccc96582c --- /dev/null +++ b/doc/user/project/merge_requests.md @@ -0,0 +1,90 @@ +# Merge Requests + +Merge requests allow you to exchange changes you made to source code + +## Only allow merge requests to be merged if the build succeeds + +You can prevent merge requests from being merged if their build did not succeed +in the project settings page. + +![only_allow_merge_if_build_succeeds](merge_requests/img/only_allow_merge_if_build_succeeds.png) + +Navigate to project settings page and select the `Only allow merge requests to be merged if the build succeeds` check box. + +Please note that you need to have builds configured to enable this feature. + +## Checkout merge requests locally + +### By adding a git alias + +Add the following alias to your `~/.gitconfig`: + +``` +[alias] + mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - +``` + +Now you can check out a particular merge request from any repository and any remote, e.g. to check out a merge request number 5 as shown in GitLab from the `upstream` remote, do: + +``` +$ git mr upstream 5 +``` + +This will fetch the merge request into a local `mr-upstream-5` branch and check it out. + +### By modifying `.git/config` for a given repository + +Locate the section for your GitLab remote in the `.git/config` file. It looks like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-ce.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +Now add the line `fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*` to this section. + +It should look like this: + +``` +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-ce.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests: + +``` +$ git fetch origin +From https://gitlab.com/gitlab-org/gitlab-ce.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +To check out a particular merge request: + +``` +$ git checkout origin/merge-requests/1 +``` + +## Ignore whitespace changes in Merge Request diff view + +![MR diff](merge_requests/img/merge_request_diff.png) + +If you click the "Hide whitespace changes" button, you can see the diff without whitespace changes. + +![MR diff without whitespace](merge_requests/img/merge_request_diff_without_whitespace.png) + +It is also working on commits compare view. + +![Commit Compare](merge_requests/img/commit_compare.png) + +## Merge Requests versions + +Every time you push to merge request branch, a new version of merge request diff +is created. When you visit the merge request page you see latest version of changes. +However you can select an older one from version dropdown + +![Merge Request Versions](merge_requests/img/versions.png) diff --git a/doc/user/project/merge_requests/img/commit_compare.png b/doc/user/project/merge_requests/img/commit_compare.png new file mode 100644 index 00000000000..0e4a2b23c04 Binary files /dev/null and b/doc/user/project/merge_requests/img/commit_compare.png differ diff --git a/doc/user/project/merge_requests/img/merge_request_diff.png b/doc/user/project/merge_requests/img/merge_request_diff.png new file mode 100644 index 00000000000..3ebbfb75ea3 Binary files /dev/null and b/doc/user/project/merge_requests/img/merge_request_diff.png differ diff --git a/doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png b/doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png new file mode 100644 index 00000000000..a0db535019c Binary files /dev/null and b/doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png differ diff --git a/doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png b/doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png new file mode 100644 index 00000000000..18bebf5fe92 Binary files /dev/null and b/doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png differ diff --git a/doc/user/project/merge_requests/img/versions.png b/doc/user/project/merge_requests/img/versions.png new file mode 100644 index 00000000000..c0a6dfe6806 Binary files /dev/null and b/doc/user/project/merge_requests/img/versions.png differ -- cgit v1.2.1 From cd93b90f85b197dc0b386bbcaa027beaa93e3410 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 12:36:14 +0200 Subject: Move authorization_for_merge_requests.md to new location --- .../authorization_for_merge_requests.md | 40 ++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 doc/user/project/merge_requests/authorization_for_merge_requests.md (limited to 'doc/user') diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md new file mode 100644 index 00000000000..d1d6d94ec11 --- /dev/null +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -0,0 +1,40 @@ +# Authorization for Merge requests + +There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project. + +## Protected branch flow + +With the protected branch flow everybody works within the same GitLab project. + +The project maintainers get Master access and the regular developers get Developer access. + +The maintainers mark the authoritative branches as 'Protected'. + +The developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. + +Only users with Master access can merge changes into a protected branch. + +### Advantages + +- fewer projects means less clutter +- developers need to consider only one remote repository + +### Disadvantages + +- manual setup of protected branch required for each new project + +## Forking workflow + +With the forking workflow the maintainers get Master access and the regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. + +Developers create forks of the authoritative project and push their feature branches to their own forks. + +To get their changes into master they need to create a merge request across forks. + +### Advantages + +- in an appropriately configured GitLab group, new projects automatically get the required access restrictions for regular developers: fewer manual steps to configure authorization for new projects + +### Disadvantages + +- the project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes) -- cgit v1.2.1 From cbc97870bc03d987d82dac679d2a81eee54a4448 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 13:21:22 +0200 Subject: Move merge_when_build_succeeds.md to new location --- .../img/merge_when_build_succeeds_enable.png | Bin 0 -> 68769 bytes .../img/merge_when_build_succeeds_status.png | Bin 0 -> 82655 bytes .../merge_requests/merge_when_build_succeeds.md | 28 +++++++++++++++++++++ 3 files changed, 28 insertions(+) create mode 100644 doc/user/project/merge_requests/img/merge_when_build_succeeds_enable.png create mode 100644 doc/user/project/merge_requests/img/merge_when_build_succeeds_status.png create mode 100644 doc/user/project/merge_requests/merge_when_build_succeeds.md (limited to 'doc/user') diff --git a/doc/user/project/merge_requests/img/merge_when_build_succeeds_enable.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_enable.png new file mode 100644 index 00000000000..b86e6d7b3fd Binary files /dev/null and b/doc/user/project/merge_requests/img/merge_when_build_succeeds_enable.png differ diff --git a/doc/user/project/merge_requests/img/merge_when_build_succeeds_status.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_status.png new file mode 100644 index 00000000000..f3ea61d8147 Binary files /dev/null and b/doc/user/project/merge_requests/img/merge_when_build_succeeds_status.png differ diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md new file mode 100644 index 00000000000..e89fb772d0d --- /dev/null +++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md @@ -0,0 +1,28 @@ +# Merge When Build Succeeds + +When reviewing a merge request that looks ready to merge but still has one or +more CI builds running, you can set it to be merged automatically when all +builds succeed. This way, you don't have to wait for the builds to finish and +remember to merge the request manually. + +![Enable](img/merge_when_build_succeeds_enable.png) + +When you hit the "Merge When Build Succeeds" button, the status of the merge +request will be updated to represent the impending merge. If you cannot wait +for the build to succeed and want to merge immediately, this option is available +in the dropdown menu on the right of the main button. + +Both team developers and the author of the merge request have the option to +cancel the automatic merge if they find a reason why it shouldn't be merged +after all. + +![Status](img/merge_when_build_succeeds_status.png) + +When the build succeeds, the merge request will automatically be merged. When +the build fails, the author gets a chance to retry any failed builds, or to +push new commits to fix the failure. + +When the builds are retried and succeed on the second try, the merge request +will automatically be merged after all. When the merge request is updated with +new commits, the automatic merge is automatically canceled to allow the new +changes to be reviewed. -- cgit v1.2.1 From 99e03f80ca875d261622268cf11eb63a02ae2bf5 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 13:33:45 +0200 Subject: Move `wip_merge_requests.md` to a new location --- .../merge_requests/img/wip_blocked_accept_button.png | Bin 0 -> 32720 bytes .../project/merge_requests/img/wip_mark_as_wip.png | Bin 0 -> 21640 bytes .../project/merge_requests/img/wip_unmark_as_wip.png | Bin 0 -> 16606 bytes .../merge_requests/work_in_progress_merge_requests.md | 17 +++++++++++++++++ 4 files changed, 17 insertions(+) create mode 100644 doc/user/project/merge_requests/img/wip_blocked_accept_button.png create mode 100644 doc/user/project/merge_requests/img/wip_mark_as_wip.png create mode 100644 doc/user/project/merge_requests/img/wip_unmark_as_wip.png create mode 100644 doc/user/project/merge_requests/work_in_progress_merge_requests.md (limited to 'doc/user') diff --git a/doc/user/project/merge_requests/img/wip_blocked_accept_button.png b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png new file mode 100644 index 00000000000..89c458aa8d9 Binary files /dev/null and b/doc/user/project/merge_requests/img/wip_blocked_accept_button.png differ diff --git a/doc/user/project/merge_requests/img/wip_mark_as_wip.png b/doc/user/project/merge_requests/img/wip_mark_as_wip.png new file mode 100644 index 00000000000..9c37354a653 Binary files /dev/null and b/doc/user/project/merge_requests/img/wip_mark_as_wip.png differ diff --git a/doc/user/project/merge_requests/img/wip_unmark_as_wip.png b/doc/user/project/merge_requests/img/wip_unmark_as_wip.png new file mode 100644 index 00000000000..31f7326beb0 Binary files /dev/null and b/doc/user/project/merge_requests/img/wip_unmark_as_wip.png differ diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md new file mode 100644 index 00000000000..546c8bdc5e5 --- /dev/null +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -0,0 +1,17 @@ +# "Work In Progress" Merge Requests + +To prevent merge requests from accidentally being accepted before they're +completely ready, GitLab blocks the "Accept" button for merge requests that +have been marked a **Work In Progress**. + +![Blocked Accept Button](img/wip_blocked_accept_button.png) + +To mark a merge request a Work In Progress, simply start its title with `[WIP]` +or `WIP:`. + +![Mark as WIP](img/wip_mark_as_wip.png) + +To allow a Work In Progress merge request to be accepted again when it's ready, +simply remove the `WIP` prefix. + +![Unark as WIP](img/wip_unmark_as_wip.png) -- cgit v1.2.1 From 14a96a1ad2d96078cbd73a60e260601f47373060 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 13:40:41 +0200 Subject: Move cherry_pick_changes.md to new location --- .../project/merge_requests/cherry_pick_changes.md | 52 +++++++++++++++++++++ .../img/cherry_pick_changes_commit.png | Bin 0 -> 304098 bytes .../img/cherry_pick_changes_commit_modal.png | Bin 0 -> 264883 bytes .../merge_requests/img/cherry_pick_changes_mr.png | Bin 0 -> 212267 bytes .../img/cherry_pick_changes_mr_modal.png | Bin 0 -> 186597 bytes 5 files changed, 52 insertions(+) create mode 100644 doc/user/project/merge_requests/cherry_pick_changes.md create mode 100644 doc/user/project/merge_requests/img/cherry_pick_changes_commit.png create mode 100644 doc/user/project/merge_requests/img/cherry_pick_changes_commit_modal.png create mode 100644 doc/user/project/merge_requests/img/cherry_pick_changes_mr.png create mode 100644 doc/user/project/merge_requests/img/cherry_pick_changes_mr_modal.png (limited to 'doc/user') diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md new file mode 100644 index 00000000000..64b94d81024 --- /dev/null +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -0,0 +1,52 @@ +# Cherry-pick changes + +> [Introduced][ce-3514] in GitLab 8.7. + +--- + +GitLab implements Git's powerful feature to [cherry-pick any commit][git-cherry-pick] +with introducing a **Cherry-pick** button in Merge Requests and commit details. + +## Cherry-picking a Merge Request + +After the Merge Request has been merged, a **Cherry-pick** button will be available +to cherry-pick the changes introduced by that Merge Request: + +![Cherry-pick Merge Request](img/cherry_pick_changes_mr.png) + +--- + +You can cherry-pick the changes directly into the selected branch or you can opt to +create a new Merge Request with the cherry-pick changes: + +![Cherry-pick Merge Request modal](img/cherry_pick_changes_mr_modal.png) + +## Cherry-picking a Commit + +You can cherry-pick a Commit from the Commit details page: + +![Cherry-pick commit](img/cherry_pick_changes_commit.png) + +--- + +Similar to cherry-picking a Merge Request, you can opt to cherry-pick the changes +directly into the target branch or create a new Merge Request to cherry-pick the +changes: + +![Cherry-pick commit modal](img/cherry_pick_changes_commit_modal.png) + +--- + +Please note that when cherry-picking merge commits, the mainline will always be the +first parent. If you want to use a different mainline then you need to do that +from the command line. + +Here is a quick example to cherry-pick a merge commit using the second parent as the +mainline: + +```bash +git cherry-pick -m 2 7a39eb0 +``` + +[ce-3514]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3514 "Cherry-pick button Merge Request" +[git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation" diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png b/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png new file mode 100644 index 00000000000..7fb68cc9e9b Binary files /dev/null and b/doc/user/project/merge_requests/img/cherry_pick_changes_commit.png differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_commit_modal.png b/doc/user/project/merge_requests/img/cherry_pick_changes_commit_modal.png new file mode 100644 index 00000000000..5267e04562f Binary files /dev/null and b/doc/user/project/merge_requests/img/cherry_pick_changes_commit_modal.png differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png b/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png new file mode 100644 index 00000000000..975fb13e463 Binary files /dev/null and b/doc/user/project/merge_requests/img/cherry_pick_changes_mr.png differ diff --git a/doc/user/project/merge_requests/img/cherry_pick_changes_mr_modal.png b/doc/user/project/merge_requests/img/cherry_pick_changes_mr_modal.png new file mode 100644 index 00000000000..6c003bacbe3 Binary files /dev/null and b/doc/user/project/merge_requests/img/cherry_pick_changes_mr_modal.png differ -- cgit v1.2.1 From a8ba5840e0c86f3fb72cf81940674698e02ed025 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 13:46:37 +0200 Subject: Move revert_changes.md to new location --- .../merge_requests/img/revert_changes_commit.png | Bin 0 -> 233750 bytes .../img/revert_changes_commit_modal.png | Bin 0 -> 205046 bytes .../merge_requests/img/revert_changes_mr.png | Bin 0 -> 241051 bytes .../merge_requests/img/revert_changes_mr_modal.png | Bin 0 -> 211022 bytes doc/user/project/merge_requests/revert_changes.md | 64 +++++++++++++++++++++ 5 files changed, 64 insertions(+) create mode 100644 doc/user/project/merge_requests/img/revert_changes_commit.png create mode 100644 doc/user/project/merge_requests/img/revert_changes_commit_modal.png create mode 100644 doc/user/project/merge_requests/img/revert_changes_mr.png create mode 100644 doc/user/project/merge_requests/img/revert_changes_mr_modal.png create mode 100644 doc/user/project/merge_requests/revert_changes.md (limited to 'doc/user') diff --git a/doc/user/project/merge_requests/img/revert_changes_commit.png b/doc/user/project/merge_requests/img/revert_changes_commit.png new file mode 100644 index 00000000000..e7194fc3504 Binary files /dev/null and b/doc/user/project/merge_requests/img/revert_changes_commit.png differ diff --git a/doc/user/project/merge_requests/img/revert_changes_commit_modal.png b/doc/user/project/merge_requests/img/revert_changes_commit_modal.png new file mode 100644 index 00000000000..c660ec7eaec Binary files /dev/null and b/doc/user/project/merge_requests/img/revert_changes_commit_modal.png differ diff --git a/doc/user/project/merge_requests/img/revert_changes_mr.png b/doc/user/project/merge_requests/img/revert_changes_mr.png new file mode 100644 index 00000000000..3002f0ac1c5 Binary files /dev/null and b/doc/user/project/merge_requests/img/revert_changes_mr.png differ diff --git a/doc/user/project/merge_requests/img/revert_changes_mr_modal.png b/doc/user/project/merge_requests/img/revert_changes_mr_modal.png new file mode 100644 index 00000000000..c6aaeecc8a6 Binary files /dev/null and b/doc/user/project/merge_requests/img/revert_changes_mr_modal.png differ diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md new file mode 100644 index 00000000000..5ead9f4177f --- /dev/null +++ b/doc/user/project/merge_requests/revert_changes.md @@ -0,0 +1,64 @@ +# Reverting changes + +> [Introduced][ce-1990] in GitLab 8.5. + +--- + +GitLab implements Git's powerful feature to [revert any commit][git-revert] +with introducing a **Revert** button in Merge Requests and commit details. + +## Reverting a Merge Request + +_**Note:** The **Revert** button will only be available for Merge Requests +created since GitLab 8.5. However, you can still revert a Merge Request +by reverting the merge commit from the list of Commits page._ + +After the Merge Request has been merged, a **Revert** button will be available +to revert the changes introduced by that Merge Request: + +![Revert Merge Request](img/revert_changes_mr.png) + +--- + +You can revert the changes directly into the selected branch or you can opt to +create a new Merge Request with the revert changes: + +![Revert Merge Request modal](img/revert_changes_mr_modal.png) + +--- + +After the Merge Request has been reverted, the **Revert** button will not be +available anymore. + +## Reverting a Commit + +You can revert a Commit from the Commit details page: + +![Revert commit](img/revert_changes_commit.png) + +--- + +Similar to reverting a Merge Request, you can opt to revert the changes +directly into the target branch or create a new Merge Request to revert the +changes: + +![Revert commit modal](img/revert_changes_commit_modal.png) + +--- + +After the Commit has been reverted, the **Revert** button will not be available +anymore. + +Please note that when reverting merge commits, the mainline will always be the +first parent. If you want to use a different mainline then you need to do that +from the command line. + +Here is a quick example to revert a merge commit using the second parent as the +mainline: + +```bash +git revert -m 2 7a39eb0 +``` + +[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request" +[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation" -- cgit v1.2.1 From 4d77056af1ca5532ae8482b362b5ef466a640ae2 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 14:15:57 +0200 Subject: Move "Only allow merge requests to be merged if the build succeeds" to new location --- doc/user/project/merge_requests.md | 14 ++------------ ...merge_when_build_succeeds_only_if_succeeds_msg.png | Bin 0 -> 11136 bytes ..._when_build_succeeds_only_if_succeeds_settings.png | Bin 0 -> 17552 bytes .../img/only_allow_merge_if_build_succeeds.png | Bin 17552 -> 0 bytes .../merge_requests/merge_when_build_succeeds.md | 18 ++++++++++++++++++ 5 files changed, 20 insertions(+), 12 deletions(-) create mode 100644 doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_msg.png create mode 100644 doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_settings.png delete mode 100644 doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png (limited to 'doc/user') diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index ecccc96582c..a1f5cc29ba8 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -1,17 +1,7 @@ # Merge Requests -Merge requests allow you to exchange changes you made to source code - -## Only allow merge requests to be merged if the build succeeds - -You can prevent merge requests from being merged if their build did not succeed -in the project settings page. - -![only_allow_merge_if_build_succeeds](merge_requests/img/only_allow_merge_if_build_succeeds.png) - -Navigate to project settings page and select the `Only allow merge requests to be merged if the build succeeds` check box. - -Please note that you need to have builds configured to enable this feature. +Merge requests allow you to exchange changes you made to source code and +collaborate with other people on the same project. ## Checkout merge requests locally diff --git a/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_msg.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_msg.png new file mode 100644 index 00000000000..6b9756b7418 Binary files /dev/null and b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_msg.png differ diff --git a/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_settings.png b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_settings.png new file mode 100644 index 00000000000..18bebf5fe92 Binary files /dev/null and b/doc/user/project/merge_requests/img/merge_when_build_succeeds_only_if_succeeds_settings.png differ diff --git a/doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png b/doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png deleted file mode 100644 index 18bebf5fe92..00000000000 Binary files a/doc/user/project/merge_requests/img/only_allow_merge_if_build_succeeds.png and /dev/null differ diff --git a/doc/user/project/merge_requests/merge_when_build_succeeds.md b/doc/user/project/merge_requests/merge_when_build_succeeds.md index e89fb772d0d..011f9cbc381 100644 --- a/doc/user/project/merge_requests/merge_when_build_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_build_succeeds.md @@ -26,3 +26,21 @@ When the builds are retried and succeed on the second try, the merge request will automatically be merged after all. When the merge request is updated with new commits, the automatic merge is automatically canceled to allow the new changes to be reviewed. + +## Only allow merge requests to be merged if the build succeeds + +> **Note:** +You need to have builds configured to enable this feature. + +You can prevent merge requests from being merged if their build did not succeed. + +Navigate to your project's settings page, select the +**Only allow merge requests to be merged if the build succeeds** check box and +hit **Save** for the changes to take effect. + +![Only allow merge if build succeeds settings](img/merge_when_build_succeeds_only_if_succeeds_settings.png) + +From now on, every time the build fails you will not be able to merge the merge +request from the UI, until you make the build pass. + +![Only allow merge if build succeeds msg](img/merge_when_build_succeeds_only_if_succeeds_msg.png) -- cgit v1.2.1 From 99f28c50d5483d6f55e7accaf1806e68acc46568 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 15:04:51 +0200 Subject: Move merge request versions to its own document --- doc/user/project/merge_requests.md | 6 +----- doc/user/project/merge_requests/img/versions.png | Bin 100566 -> 35001 bytes doc/user/project/merge_requests/versions.md | 22 ++++++++++++++++++++++ 3 files changed, 23 insertions(+), 5 deletions(-) create mode 100644 doc/user/project/merge_requests/versions.md (limited to 'doc/user') diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index a1f5cc29ba8..f1a14e7e91c 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -73,8 +73,4 @@ It is also working on commits compare view. ## Merge Requests versions -Every time you push to merge request branch, a new version of merge request diff -is created. When you visit the merge request page you see latest version of changes. -However you can select an older one from version dropdown - -![Merge Request Versions](merge_requests/img/versions.png) +Select an older revision to from the version dropdown. diff --git a/doc/user/project/merge_requests/img/versions.png b/doc/user/project/merge_requests/img/versions.png index c0a6dfe6806..f279ccd7ce3 100644 Binary files a/doc/user/project/merge_requests/img/versions.png and b/doc/user/project/merge_requests/img/versions.png differ diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md new file mode 100644 index 00000000000..2b1c5ddd562 --- /dev/null +++ b/doc/user/project/merge_requests/versions.md @@ -0,0 +1,22 @@ +# Merge requests versions + +> Will be [introduced][ce-5467] in GitLab 8.12. + +Every time you push to a branch that is tied to a merge request, a new version +of merge request diff is created. When you visit a merge request that contains +more than one pushes, you can select and compare the versions of those merge +request diffs. + +By default, the latest version of changes is shown. However, you +can select an older one from version dropdown. + +![Merge Request Versions](img/versions.png) + +--- + +>**Note:** +Merge request versions are based on push not on commit. So, if you pushed 5 +commits in a single push, it will be a single option in the dropdown. If you +pushed 5 times, that will count for 5 options. + +[ce-5467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5467 -- cgit v1.2.1 From bf00e0f4b2fd8994df8f7b567839f12715a05fde Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 18:25:05 +0200 Subject: Add links to new docs in merge_requests.md and workflow/README.md --- doc/user/project/merge_requests.md | 144 +++++++++++++++++---- .../merge_requests/img/merge_request_diff.png | Bin 103239 -> 69394 bytes .../img/merge_request_diff_without_whitespace.png | Bin 71896 -> 0 bytes 3 files changed, 117 insertions(+), 27 deletions(-) delete mode 100644 doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png (limited to 'doc/user') diff --git a/doc/user/project/merge_requests.md b/doc/user/project/merge_requests.md index f1a14e7e91c..f79535d1542 100644 --- a/doc/user/project/merge_requests.md +++ b/doc/user/project/merge_requests.md @@ -3,9 +3,97 @@ Merge requests allow you to exchange changes you made to source code and collaborate with other people on the same project. -## Checkout merge requests locally +## Authorization for merge requests -### By adding a git alias +There are two main ways to have a merge request flow with GitLab: + +1. Working with [protected branches][] in a single repository +1. Working with forks of an authoritative project + +[Learn more about the authorization for merge requests.](merge_requests/authorization_for_merge_requests.md) + +## Cherry-pick changes + +Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button +in a merged merge requests or a commit. + +[Learn more about cherry-picking changes.](merge_requests/cherry_pick_changes.md) + +## Merge when build succeeds + +When reviewing a merge request that looks ready to merge but still has one or +more CI builds running, you can set it to be merged automatically when all +builds succeed. This way, you don't have to wait for the builds to finish and +remember to merge the request manually. + +[Learn more about merging when build succeeds.](merge_requests/merge_when_build_succeeds.md) + +## Resolve discussion comments in merge requests reviews + +Keep track of the progress during a code review with resolving comments. +Resolving comments prevents you from forgetting to address feedback and lets +you hide discussions that are no longer relevant. + +[Read more about resolving discussion comments in merge requests reviews.](merge_requests/merge_request_discussion_resolution.md) + +## Resolve conflicts + +When a merge request has conflicts, GitLab may provide the option to resolve +those conflicts in the GitLab UI. + +[Learn more about resolving merge conflicts in the UI.](merge_requests/resolve_conflicts.md) + +## Revert changes + +GitLab implements Git's powerful feature to revert any commit with introducing +a **Revert** button in merge requests and commit details. + +[Learn more about reverting changes in the UI](merge_requests/revert_changes.md) + +## Merge requests versions + +Every time you push to a branch that is tied to a merge request, a new version +of merge request diff is created. When you visit a merge request that contains +more than one pushes, you can select and compare the versions of those merge +request diffs. + +[Read more about the merge requests versions.](merge_requests/versions.md) + +## Work In Progress merge requests + +To prevent merge requests from accidentally being accepted before they're +completely ready, GitLab blocks the "Accept" button for merge requests that +have been marked as a **Work In Progress**. + +[Learn more about settings a merge request as "Work In Progress".](merge_requests/work_in_progress_merge_requests.md) + +## Ignore whitespace changes in Merge Request diff view + +If you click the **Hide whitespace changes** button, you can see the diff +without whitespace changes (if there are any). This is also working when on a +specific commit page. + +![MR diff](merge_requests/img/merge_request_diff.png) + +>**Tip:** +You can append `?w=1` while on the diffs page of a merge request to ignore any +whitespace changes. + +## Tips + +Here are some tips that will help you be more efficient with merge requests in +the command line. + +> **Note:** +This section might move in its own document in the future. + +### Checkout merge requests locally + +A merge request contains all the history from a repository, plus the additional +commits added to the branch associated with the merge request. Here's a few +tricks to checkout a merge request locally. + +#### Checkout locally by adding a git alias Add the following alias to your `~/.gitconfig`: @@ -14,17 +102,21 @@ Add the following alias to your `~/.gitconfig`: mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - ``` -Now you can check out a particular merge request from any repository and any remote, e.g. to check out a merge request number 5 as shown in GitLab from the `upstream` remote, do: +Now you can check out a particular merge request from any repository and any +remote. For example, to check out the merge request with ID 5 as shown in GitLab +from the `upstream` remote, do: ``` -$ git mr upstream 5 +git mr upstream 5 ``` -This will fetch the merge request into a local `mr-upstream-5` branch and check it out. +This will fetch the merge request into a local `mr-upstream-5` branch and check +it out. -### By modifying `.git/config` for a given repository +#### Checkout locally by modifying `.git/config` for a given repository -Locate the section for your GitLab remote in the `.git/config` file. It looks like this: +Locate the section for your GitLab remote in the `.git/config` file. It looks +like this: ``` [remote "origin"] @@ -32,9 +124,19 @@ Locate the section for your GitLab remote in the `.git/config` file. It looks li fetch = +refs/heads/*:refs/remotes/origin/* ``` -Now add the line `fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/*` to this section. +You can open the file with: + +``` +git config -e +``` + +Now add the following line to the above section: + +``` +fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` -It should look like this: +In the end, it should look like this: ``` [remote "origin"] @@ -46,31 +148,19 @@ It should look like this: Now you can fetch all the merge requests: ``` -$ git fetch origin +git fetch origin + +... From https://gitlab.com/gitlab-org/gitlab-ce.git * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 ... ``` -To check out a particular merge request: +And to check out a particular merge request: ``` -$ git checkout origin/merge-requests/1 +git checkout origin/merge-requests/1 ``` -## Ignore whitespace changes in Merge Request diff view - -![MR diff](merge_requests/img/merge_request_diff.png) - -If you click the "Hide whitespace changes" button, you can see the diff without whitespace changes. - -![MR diff without whitespace](merge_requests/img/merge_request_diff_without_whitespace.png) - -It is also working on commits compare view. - -![Commit Compare](merge_requests/img/commit_compare.png) - -## Merge Requests versions - -Select an older revision to from the version dropdown. +[protected branches]: protected_branches.md diff --git a/doc/user/project/merge_requests/img/merge_request_diff.png b/doc/user/project/merge_requests/img/merge_request_diff.png index 3ebbfb75ea3..06ee4908edc 100644 Binary files a/doc/user/project/merge_requests/img/merge_request_diff.png and b/doc/user/project/merge_requests/img/merge_request_diff.png differ diff --git a/doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png b/doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png deleted file mode 100644 index a0db535019c..00000000000 Binary files a/doc/user/project/merge_requests/img/merge_request_diff_without_whitespace.png and /dev/null differ -- cgit v1.2.1 From 026d1acd26dd09a84db969bfc0d5f64e67a5e96f Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 5 Sep 2016 19:32:37 +0200 Subject: Refactor authorization_for_merge_requests.md --- .../authorization_for_merge_requests.md | 48 ++++++++++++++-------- 1 file changed, 32 insertions(+), 16 deletions(-) (limited to 'doc/user') diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index d1d6d94ec11..59b3fe7242c 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,40 +1,56 @@ # Authorization for Merge requests -There are two main ways to have a merge request flow with GitLab: working with protected branches in a single repository, or working with forks of an authoritative project. +There are two main ways to have a merge request flow with GitLab: + +1. Working with [protected branches] in a single repository. +1. Working with forks of an authoritative project. ## Protected branch flow With the protected branch flow everybody works within the same GitLab project. -The project maintainers get Master access and the regular developers get Developer access. +The project maintainers get Master access and the regular developers get +Developer access. The maintainers mark the authoritative branches as 'Protected'. -The developers push feature branches to the project and create merge requests to have their feature branches reviewed and merged into one of the protected branches. +The developers push feature branches to the project and create merge requests +to have their feature branches reviewed and merged into one of the protected +branches. -Only users with Master access can merge changes into a protected branch. +By default, only users with Master access can merge changes into a protected +branch. -### Advantages +**Advantages** -- fewer projects means less clutter -- developers need to consider only one remote repository +- Fewer projects means less clutter. +- Developers need to consider only one remote repository. -### Disadvantages +**Disadvantages** -- manual setup of protected branch required for each new project +- Manual setup of protected branch required for each new project ## Forking workflow -With the forking workflow the maintainers get Master access and the regular developers get Reporter access to the authoritative repository, which prohibits them from pushing any changes to it. +With the forking workflow the maintainers get Master access and the regular +developers get Reporter access to the authoritative repository, which prohibits +them from pushing any changes to it. + +Developers create forks of the authoritative project and push their feature +branches to their own forks. -Developers create forks of the authoritative project and push their feature branches to their own forks. +To get their changes into master they need to create a merge request across +forks. -To get their changes into master they need to create a merge request across forks. +**Advantages** -### Advantages +- In an appropriately configured GitLab group, new projects automatically get + the required access restrictions for regular developers: fewer manual steps + to configure authorization for new projects. -- in an appropriately configured GitLab group, new projects automatically get the required access restrictions for regular developers: fewer manual steps to configure authorization for new projects +**Disadvantages** -### Disadvantages +- The project need to keep their forks up to date, which requires more advanced + Git skills (managing multiple remotes). -- the project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes) +[protected branches]: ../protected_branches.md -- cgit v1.2.1