- Fix #53298: JupyterHub restarts should work without errors. !22671 (Amit Rathi)
- Fix incompatibility with IE11 due to non-transpiled gitlab-ui components. !22695
- Fix bug when links in tabs of the labels index pages ends with .html. !22716
- Fixed label removal from issue. !22762
- Align toggle sidebar button across all browsers and OSs. !22771
- Disable replication lag check for Aurora PostgreSQL databases. !22786
- Render unescaped link for failed pipeline status. !22807
- Fix misaligned approvers dropdown. !22832
- Fix bug with wiki page create message. !22849
- Fix rendering of filter bar tokens for special values. !22865 (Heinrich Lee Yu)
- Align sign in button. !22888 (George Tsiolis)
- Fix error handling bugs in kubernetes integration. !22922
- Fix deployment jobs using nil KUBE_TOKEN due to migration issue. !23009
- Avoid returning deployment metrics url to MR widget when the deployment is not successful. !23010
- Fix a race condition intermittently breaking GitLab startup. !23028
- Adds margin after a deleted branch name in the activity feed. !23038
- Ignore environment validation failure. !23100
- Adds CI favicon back to jobs page.
- Redirect to the pipeline builds page when a build is canceled. (Eva Kadlecova)
- Fixed diff stats not showing when performance bar is enabled.
- Show expand all diffs button when a single diff file is collapsed.
- Clear fetched file templates when changing template type in Web IDE.
- Fix bug causing not all emails to show up in commit email selectbox.
- Remove duplicate escape in job sidebar.
- Fixing styling issues on the scheduled pipelines page.
- Fixes broken test in master.
- Renders stuck block when runners are stuck.
- Removes extra border from test reports in the merge request widget.
- Fixes broken borders for reports section in MR widget.
- Only render link to branch when branch still exists in pipeline page.
- Fixed source project not filtering in merge request creation compare form.
- Do not reload self on hooks when creating deployment.
### Changed (38 changes, 12 of them are from the community)
- Link button in markdown editor recognize URLs. !1983 (Johann Hubert Sonntagbauer)
- Replace i to icons in vue components. !20748 (George Tsiolis)
- Remove Linguist gem, reducing Rails memory usage by 128MB per process. !21008
- Issue board card design. !21229
- On deletion of a file in sub directory in web IDE redirect to the sub directory instead of project root. !21465 (George Thomas @thegeorgeous)
- Change single-item breadcrumbs to page titles. !22155
- Improving branch filter sorting by listing exact matches first and added support for begins_with (^) and ends_with ($) matching. !22166 (Jason Rutherford)
- Remove legacy unencrypted webhook columns from the database. !22199
- Show canary status in the performance bar. !22222
- Add failure reason for execution timeout. !22224
- Rename "scheduled" label/badge of delayed jobs to "delayed". !22245
- Update the empty state on wiki-only projects to display an empty state that is more consistent with the rest of the system. !22262
- Add IID headers to E-Mail notifications. !22263
- Allow finding the common ancestor for multiple revisions through the API. !22295
- Add status to Deployment. !22380
- Add dynamic timer to delayed jobs. !22382
- No longer require a deploy to start Prometheus monitoring. !22401
- Secret Variables renamed to CI Variables in the codebase, to match UX. !22414 (Marcel Amirault @ravlen)
- Automatically navigate to last board visited. !22430
- Use merge request prefix symbol in event feed title. !22449 (George Tsiolis)
- Update Ruby version in README. !22466 (J.D. Bean)
- Reword error message for internal CI unknown pipeline status. !22474
- Bump mermaid to 8.0.0-rc.8. !22509 (@blackst0ne)
- Update Todo icons in collapsed sidebar for Issues and MRs. !22534
- Support backward compatibility when introduce new failure reason. !22566
- Add dynamic timer for delayed jobs in pipelines list. !22621
- Truncate milestone title on collapsed sidebar. !22624 (George Tsiolis)
- Standardize milestones filter in APIs to None / Any. !22637 (Heinrich Lee Yu)
- Add dynamic timer for delayed jobs in job list. !22656
- Allowing issues with single letter identifiers to be linked to external issue tracker (f.ex T-123). !22717 (Dídac Rodríguez Arbonès)
- Update project and group labels empty state. !22745 (George Tsiolis)
- Fix environment status in merge request widget. !22799
- Paginate Bitbucket Server importer projects. !22825
- Drop `allow_overflow` option in `TimeHelper.duration_in_numbers`. !52284
- Add 'only history' option to notes filter.
- Adds filtered dropdown with changed files in review.
- Expose {closed,merged}_{at,by} in merge requests API index.
- Make all legacy security reports to use raw format.
### Performance (27 changes, 6 of them are from the community)
- Add preload for routes and namespaces for issues controller. !21651
- Enhance performance of counting local LFS objects. !22143
- Use cached readme contents when available. !22325
- Experimental support for running Puma multithreaded web-server. !22372
- Enhance performance of counting local Uploads. !22522
- Reduce SQL queries needed to load open merge requests. !22709
- Significantly cut memory usage and SQL queries when reloading diffs. !22725
- Optimize merge request refresh by using the database to check commit SHAs. !22731
- Remove dind from license_management auto-devops job definition. !22732
- Add index to find stuck merge requests. !22749
- Allow Rails concurrency when running in Puma. !22751
- Improve performance of rendering large reports. !22835
- Improves performance of stuck import jobs detection. !22879
- Rewrite SnippetsFinder to improve performance by a factor of 1500.
- Enable more frozen string in lib/**/*.rb. (gfyoung)
- Enable some frozen string in lib/gitlab. (gfyoung)
- Enable even more frozen string in lib/**/*.rb. (gfyoung)
- Improve performance of tree rendering in repositories with lots of items.
- Remove gitlab-ui's tooltip from global.
- Remove gitlab-ui's progress bar from global.
- Remove gitlab-ui's pagination from global.
- Remove gitlab-ui's modal from global.
- Remove gitlab-ui's loading icon from global.
- Enable frozen string for lib/gitlab/*.rb. (gfyoung)
- Enable frozen string for lib/gitlab/ci. (gfyoung)
- Enable frozen string for remaining lib/gitlab/ci/**/*.rb. (gfyoung)
- Adds pagination to pipelines table in merge request page.
### Added (33 changes, 11 of them are from the community)
- Add endpoint to update a git submodule reference. !20949
- Add license data to projects endpoint. !21606 (J.D. Bean (@jdbean))
- Allow to configure when to retry failed CI jobs. !21758 (Markus Doits)
- Add API endpoint to list issue related merge requests. !21806 (Helmut Januschka)
- Add the Play button for delayed jobs in environment page. !22106
- Switch between tree list & file list in diffs file browser. !22191
- Re-arrange help-related user menu items into new Help menu. !22195
- Adds trace of each access check when git push times out. !22265
- Add email for milestone change. !22279
- Show post-merge pipeline in merge request page. !22292
- Add Applications API endpoints for listing and deleting entries. !22296 (Jean-Baptiste Vasseur)
- Added `Any` option to milestones filter. !22351 (Heinrich Lee Yu)
- Improve validation errors for external CI/CD configuration. !22394
- Introduce new model to persist specific cluster information. !22404
- Add background migration to populate Kubernetes namespaces. !22433
- Add support for JSON logging for audit events. !22471
- Adds option to override commit email with a noreply private email. !22560
- Add None/Any option for assignee_id in Issues and Merge Requests API. !22598 (Heinrich Lee Yu)
- Add None/Any option for assignee_id in search bar. !22599 (Heinrich Lee Yu)
- Implement parallel job keyword. !22631
- Add None / Any options to reactions filter. !22638 (Heinrich Lee Yu)
- Make index.* render like README.* when it's present in a repository. !22639 (Jakub Jirutka)
- Allow adding patches when creating a merge request via email. !22723 (Serdar Dogruyol)
- Bump Gitaly to 0.129.0. !22868
- Allow commenting on any diff line in Merge Requests. !22914
See also the [corresponding UX guide](../ux_guide/components.md#dropdowns).
See also the [corresponding UX guide](https://design.gitlab.com/#/components/dropdowns).
### How to style a bootstrap dropdown
1. Use the HTML structure provided by the [docs][bootstrap-dropdowns]
...
...
@@ -40,7 +40,7 @@ See also the [corresponding UX guide](../ux_guide/components.md#dropdowns).
## Modals
See also the [corresponding UX guide](../ux_guide/components.md#modals).
See also the [corresponding UX guide](https://design.gitlab.com/#/components/modals).
We have a reusable Vue component for modals: [vue_shared/components/gl_modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl_modal.vue)
We created a page inside GitLab where you can check commonly used html and css elements.
When you run GitLab instance locally - just visit http://localhost:3000/help/ui page to see UI examples
you can use during GitLab development.
## Design repository
All design files are stored in the [gitlab-design](https://gitlab.com/gitlab-org/gitlab-design)
repository and maintained by GitLab UX designers.
## Navigation
GitLab's layout contains 2 sections: the left sidebar and the content. The left sidebar contains a static navigation menu.
This menu will be visible regardless of what page you visit.
The content section contains a header and the content itself. The header describes the current GitLab page and what navigation is
available to the user in this area. Depending on the area (project, group, profile setting) the header name and navigation may change. For example, when the user visits one of the
project pages the header will contain the project's name and navigation for that project. When the user visits a group page it will contain the group's name and navigation related to this group.
You can see a visual representation of the navigation in GitLab in the GitLab Product Map, which is located in the [Design Repository][gitlab-map-graffle]
along with [PDF][gitlab-map-pdf] and [PNG][gitlab-map-png] exports.
### Adding new tab to header navigation
We try to keep the amount of tabs in the header navigation between 5 and 10 so that it fits on a typical laptop screen. We also try not to confuse the user with too many options. Ideally each
tab should represent separate functionality. Everything related to the issue
tracker should be under the 'Issues' tab while everything related to the wiki should
be under 'Wiki' tab and so on and so forth.
When adding a new tab to the header don't use more than 2 words for text in the link.
We want to keep links short and easy to remember and fit all of them in the small screen.
## Mobile screen size
We want GitLab to work well on small mobile screens as well. Size limitations make it is impossible to fit everything on a mobile screen. In this case it is OK to hide
part of the UI for smaller resolutions in favor of a better user experience.
However core functionality like browsing files, creating issues, writing comments, should
be available on all resolutions.
## Icons
*`trash` icon for button or link that does destructive action like removing
information from database or file system
*`x` icon for closing/hiding UI element. For example close modal window
*`pencil` icon for edit button or link
*`eye` icon for subscribe action
*`rss` for rss/atom feed
*`plus` for link or dropdown that lead to page where you create new object (For example new issue page)
### SVGs
When exporting SVGs, be sure to follow the following guidelines:
- Convert all strokes to outlines.
- Use pathfinder tools to combine overlapping paths and create compound paths.
- SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS.
- Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes.
You can open your svg in a text editor to ensure that it is clean.
Motion is a tool to help convey important relationships, changes or transitions between elements. It should be used sparingly and intentionally, highlighting the right elements at the right moment.
## Timings
The longer distance an object travel, the timing should be longer for the animation. However, when in doubt, we should avoid large, full screen animations.
Subtle animations, or objects leaving the screen should take **100-200 milliseconds**. Objects entering the screen, or motion we want to use to direct user attention can take between **200-400 milliseconds**. We should avoid animations of longer than 400 milliseconds as they will make the experience appear sluggish. If a specific animation feels like it will need more than 400 milliseconds, revisit the animation to see if there is a simpler, easier, shorter animation to implement.
## Easing
Easing specifies the rate of change of a parameter over time (see [easings.net](http://easings.net/)). Adding an easing curve will make the motion feel more natural. Being consistent with the easing curves will make the whole experience feel more cohesive and connected.
* When an object is entering the screen, or transforming the scale, position, or shape, use the **easeOutQuint** curve (`cubic-bezier(0.23, 1, 0.32, 1)`)
* When an object is leaving the screen, or transforming the opacity or color, no easing curve is needed. It shouldn't _slow down_ as it is exiting the screen, as that draws attention on the leaving object, where we don't want it. Adding easing to opacity and color transitions will make the motion appear less smooth. Therefore, for these cases, motion should just be **linear**.
## Types of animations
### Hover
Interactive elements (links, buttons, etc.) should have a hover state. A subtle animation for this transition adds a polished feel. We should target a `100ms - 150ms linear` transition for a color hover effect.
View the [interactive example](http://codepen.io/awhildy/full/GNyEvM/) here.
### Dropdowns
The dropdown menu should feel like it is appearing from the triggering element. Combining a position shift `400ms cubic-bezier(0.23, 1, 0.32, 1)` with an opacity animation `200ms linear` on the second half of the motion achieves this affect.
View the [interactive example](http://codepen.io/awhildy/full/jVLJpb/) here.
### Quick update
When information is updating in place, a quick, subtle animation is needed. The previous content should cut out, and the new content should have a quick, `200ms linear` fade in.
Skeleton loading is explained in the [component section](components.html#skeleton-loading) of the UX guide. It includes a horizontally pulsating animation that shows motion as if it's growing. It's timing is a slower `linear 1s`.
When elements move on screen, there should be a quick animation so it is clear to users what moved where. The timing of this animation differs based on the amount of movement and change. Consider animations between `200ms` and `400ms`.
#### Shifting elements on reorder
An example of a moving transition is when elements have to move out of the way when you drag an element.
View the [interactive example](http://codepen.io/awhildy/full/ALyKPE/) here.
#### Autoscroll the page
Another example of a moving transition is when you have to autoscroll the page to keep an active element visible.
View the [interactive example](http://codepen.io/awhildy/full/PbxgVo/) here.
GitLab is a responsive experience that works well across all screen sizes, from mobile devices to large monitors. In order to provide a great user experience, the core functionality (browsing files, creating issues, writing comments, etc.) must be available at all resolutions. However, due to size limitations, some secondary functionality may be hidden on smaller screens. Please keep this functionality limited to rare actions that aren't expected to be needed on small devices.
---
## Typography
### Primary typeface
GitLab's main typeface used throughout the UI is **Source Sans Pro**. We support both the bold and regular weight.
### Monospace typeface
This is the typeface used for code blocks and references to commits, branches, and tags (`.commit-sha` or `.ref-name`). GitLab uses the OS default font.
-**Menlo** (Mac)
-**Consolas** (Windows)
-**Liberation Mono** (Linux)
---
## Icons
GitLab has a strong, unique personality. When you look at any screen, you should know immediately that it is GitLab.
Iconography is a powerful visual cue to the user and is a great way for us to reflect our particular sense of style.
-**Standard size:** 16px * 16px
-**Border thickness:** 2px
-**Border radius:** 3px
> TODO: List all icons, proper usage, hover, and active states.
---
## Color
| | State | Action |
| :------: | :------- | :------- |
|  | Primary and active (such as the current tab) | Organizational, managing, and retry commands|
|  | Opened | Create new objects |
|  | Warning | Non destructive action |
|  | Closed | Delete and other destructive commands |
|  | Pointer cursor: used to indicate that you can click on an element to invoke a command or navigate, such as links and buttons |
|  | Move cursor: used to indicate that you can move an element around on the screen |
|  | Pan cursor (opened): indicates that you can grab and move the entire canvas, affecting what is seen in the view port. |
|  | Pan cursor (closed): indicates that you are actively panning the canvas. |
|  | I-beam cursor: indicates that this is either text that you can select and copy, or a text field that you can click into to enter text. |
The content of this documented was moved into the [GitLab Design System](https://design.gitlab.com/).
Tooltips identify elements or provide additional, useful information about the referring elements. Tooltips are different from ALT-attributes, which are intended primarily for static images. Tooltips are summoned by:
* Hovering over an element with a cursor
* Focusing on an element with a keyboard (usually the tab key)
* Upon touch
### Usage
A tooltip should be used:
* When there isn’t enough space to show the information
* When it isn’t critical for the user to see the information
* For icons that don’t have a label
Tooltips shouldn’t repeat information that is shown near the referring element. However, they can show the same data in a different format (e.g. date or timestamps).
### Placement
By default, tooltips should be placed below the referring element. However, if there isn’t enough space in the viewport, the tooltip should be moved to the side as needed.
Popovers provide additional, useful, unique information about the referring elements and can provide one or multiple actionable elements. They inform the user of additional information within the context of their original view, but without forcing the user to act upon it like a modal. Popovers are different from tooltips, which do not provide rich markup and actionable items. A popover can contain a header section with a different background color.
Popovers are summoned:
* Upon hover or touch on an element
### Usage
A popover should be used:
* When you don't want to let the user lose context, but still want to provide additional useful unique information about referring elements
* When it isn’t critical for the user to act upon the information
* When you want to give a user a summary of extended information and the option to switch context if they want to dive in deeper.
### Styling
A popover can contain a header section with a different background color if that improves readability and separation of content within.
This example shows two sections, where each section includes an actionable element. The first section shows a summary of the content shown when clicking the "read more" link. With this information the user can decide to dive deeper or start their GitLab Ultimate trial immediately.
### Placement
By default, tooltips should be placed below the referring element. However, if there isn’t enough space in the viewport or it blocks related content, the tooltip should be moved to the side or above as needed.
In this example we let the user know more about the setting they are deciding over, without loosing context. If they want to know even more they can do so, but with the expectation of opening that content in a new view.
---
## Anchor links
Anchor links are used for navigational actions and lone, secondary commands (such as 'Reset filters' on the Issues List) when deemed appropriate by the UX team.
### States
#### Rest
Primary links are blue in their rest state. Secondary links (such as the time stamp on comments) are a neutral gray color in rest. Details on the main GitLab navigation links can be found on the [features](features.md#navigation) page.
#### Hover
On hover, an underline should be added and the color should change. Both the primary and secondary link should become the darker blue color on hover.
#### Focus
The focus state should match the hover state.
---
## Buttons
Buttons communicate the command that will occur when the user clicks on them.
### Types
#### Primary
Primary buttons communicate the main call to action. There should only be one call to action in any given experience. Visually, primary buttons are conveyed with a full background fill
#### Secondary
Secondary buttons are for alternative commands. They should be conveyed by a button with a stroke, and no background fill.
Text should be in sentence case, where only the first word is capitalized. "Create issue" is correct, not "Create Issue". Buttons should only contain an icon or a text, not both.
> TODO: Rationalize this. Ensure that we still believe this.
### Colors
The default color treatment is the white/grey button. Follow the guidance on the [basics](basics.md#color) page to add meaningful color to a button.
### Secondary states
Primary buttons darken the color of their background and border for hover, focus and active states. An inner shadow is added to the active state to denote the button being pressed.
When there are a group of buttons in a dialog or a form, we need to be consistent with the placement.
#### Dismissive actions on the left
The dismissive action returns the user to the previous state.
> Example: Cancel
#### Affirmative actions on the right
Affirmative actions continue to progress towards the user goal that triggered the dialog or form.
> Example: Submit, Ok, Delete
---
## Dropdowns
Dropdowns are used to allow users to choose one (or many) options from a list of options. If this list of options is more 20, there should generally be a way to search through and filter the options (see the complex filter dropdowns below.)
> TODO: Will update this section when the new filters UI is implemented.
### Max size
The max height for dropdowns should target **10-15** single line items, or **7-10** multi-line items. If the height of the dropdown is too large, the list becomes very hard to parse and it is easy to visually lose track of the item you are looking for. Usability also suffers as more mouse movement is required, and you have a larger area in which you hijack the scroll away from the page level. While it may initially seem counterintuitive to not show as many items as you can, it is actually quicker and easier to process the information when it is cropped at a reasonable height.
---
## Counts
A count element is used in navigation contexts where it is helpful to indicate the count, or number of items, in a list. Always use the [`number_with_delimiter`][number_with_delimiter] helper to display counts in the UI.
Lists are used where ever there is a single column of information to display. Ths [issues list](https://gitlab.com/gitlab-org/gitlab-ce/issues) is an example of an important list in the GitLab UI.
### Types
Simple list using .content-list
List with avatar, title and description using .content-list
List with hover effect .content-list
When the information is too complex for a list, with multiple columns of information, a table can be used. For example, the [pipelines page](https://gitlab.com/gitlab-org/gitlab-ce/pipelines) uses a table.
---
## Blocks
Blocks are a way to group related information.
### Types
#### Content blocks
Content blocks (`.content-block`) are the basic grouping of content. They are commonly used in [lists](#lists), and are separated by a button border.
#### Row content blocks
A background color can be added to this blocks. For example, items in the [issue list](https://gitlab.com/gitlab-org/gitlab-ce/issues) have a green background if they were created recently. Below is an example of a gray content block with side padding using `.row-content-block`.
Cover blocks are generally used to create a heading element for a page, such as a new project, or a user profile page. Below is a cover block (`.cover-block`) for the profile page with an avatar, name and description.
---
## Skeleton loading
Skeleton loading is a way to convey to the user what kind of content is currently being loaded. It's a paradigm with which content can independently and asynchronously be loaded, while still adhering to the structure and look of the completely loaded view.
### Requirements
* A skeleton should represent an organism in a recognisable way
* Atom elements within organisms (for reference see this article on [atomic design methodology](http://atomicdesign.bradfrost.com/chapter-2/)) may be represented in a maximum of 3 repetitions, if applicable.
* Skeletons should only be presented in grayscale using the HEX colors: `#fafafa` or `#ffffff` (except for shadows)
* Animate the grey atoms in a pulsating way to show motion, as if "loading". The pulse animation transitions colors horizontally from left to right, starting with `#f2f2f2` to `#fafafa`.
Skeleton loading can replace any existing UI elements for the period in which they are loaded and should aim for maintaining a similar structure visually.
---
## Modals
Modals are only used for having a conversation and confirmation with the user. The user is not able to access the features on the main page until closing the modal.
### Usage
* When the action is irreversible, modals provide the details and confirm with the user before they take an advanced action.
* When the action will affect privacy or authorization, modals provide advanced information and confirm with the user.
### Style
* Modals contain the header, body, and actions.
***Header(1):** The header title is a question instead of a descriptive phrase.
***Body(2):** The content in body should never be ambiguous and unclear. It provides specific information.
***Actions(3):** Contains an affirmative action, a dismissive action, and an extra action. The order of actions from left to right: Dismissive action → Extra action → Affirmative action
* Confirmations regarding labels should keep labeling styling.
* References to commits, branches, and tags should be **monospaced**.
### Placement
* Modals should always be the center of the screen horizontally and be positioned **72px** from the top.
| Modal with 2 actions | Modal with 3 actions | Special confirmation |
> TODO: Catalog how we are currently using panels and rationalize how they relate to alerts
---
## Alerts
> TODO: Catalog how we are currently using alerts
---
## Forms
There are two options shown below regarding the positioning of labels in forms. Both are options to consider based on context and available size. However, it is important to have a consistent treatment of labels in the same form.
### Types
#### Labels stack vertically
Form (`form`) with label rendered above input.
#### Labels side-by-side
Horizontal form (`form.horizontal-form`) with label rendered inline with input.
Search boxes across GitLab have a consistent rest, active and text entered state. When text isn't entered in the box, there should be a magnifying glass right aligned with the input field. When text is entered, the magnifying glass should become a x, allowing users to clear their text.
If needed, we indicate the scope of the search in the search box.
Format for exacts dates should be ‘Mon DD, YYYY’, such as the examples below.
#### Relative
This format relates how long since an action has occurred. The exact date can be shown as a tooltip on hover.
### References
Referencing GitLab items depends on a symbol for each type of item. Typing that symbol will invoke a dropdown that allows you to search for and autocomplete the item you were looking for. References are shown as [links](#links) in context, and hovering on them shows the full title or name of the item.
The copy for GitLab is clear and direct. We strike a clear balance between professional and friendly. We can empathesize with users (such as celebrating completing all Todos), and remain respectful of the importance of the work. We are that trusted, friendly coworker that is helpful and understanding.
The copy and messaging is a core part of the experience of GitLab and the conversation with our users. Follow the below conventions throughout GitLab.
Portions of this page are inspired by work found in the [Material Design guidelines][material design].
>**Note:**
We are currently inconsistent with this guidance. Images below are created to illustrate the point. As this guidance is refined, we will ensure that our experiences align.
## Contents
*[Brevity](#brevity)
*[Capitalization and punctuation](#capitalization-and-punctuation)
*[Terminology](#terminology)
---
## Brevity
Users will skim content, rather than read text carefully.
When familiar with a web app, users rely on muscle memory, and may read even less when moving quickly.
A good experience should quickly orient a user, regardless of their experience, to the purpose of the current screen. This should happen without the user having to consciously read long strings of text.
In general, text is burdensome and adds cognitive load. This is especially pronounced in a powerful productivity tool such as GitLab.
We should _not_ rely on words as a crutch to explain the purpose of a screen.
The current navigation and composition of the elements on the screen should get the user 95% there, with the remaining 5% being specific elements such as text.
This means that, as a rule, copy should be very short. A long message or label is a red flag hinting at design that needs improvement.
>**Example:**
Use `Add` instead of `Add issue` as a button label.
Preferably use context and placement of controls to make it obvious what clicking on them will do.
---
## Capitalization and punctuation
### Case
Use sentence case for titles, headings, labels, menu items, and buttons. Use title case when referring to [features][features] or [products][products]. Note that some features are also objects (e.g. “Merge Requests” and “merge requests”).
| :white_check_mark: Do | :no_entry_sign: Don’t |
| --- | --- |
| Add issues to the Issue Board feature in GitLab Hosted | Add Issues To The Issue Board Feature In GitLab Hosted |
### Avoid periods
Avoid using periods in solitary sentences in these elements:
* Labels
* Hover text
* Bulleted lists
* Modal body text
Periods should be used for:
* Lists or modals with multiple sentences
* Any sentence followed by a link
| :white_check_mark: **Do** place periods after sentences followed by a link | :no_entry_sign: **Don’t** place periods after a link if it‘s not followed by a sentence |
| --- | --- |
| Mention someone to notify them. [Learn more](#) | Mention someone to notify them. [Learn more](#). |
| :white_check_mark: **Do** skip periods after solo sentences of body text | :no_entry_sign: **Don’t** place periods after body text if there is only a single sentence |
| --- | --- |
| To see the available commands, enter `/gitlab help` | To see the available commands, enter `/gitlab help`. |
### Use contractions
Don’t make a sentence harder to understand just to follow this rule. For example, “do not” can give more emphasis than “don’t” when needed.
| :white_check_mark: Do | :no_entry_sign: Don’t |
| --- | --- |
| it’s, can’t, wouldn’t, you’re, you’ve, haven’t, don’t | it is, cannot, would not, it’ll, should’ve |
### Use numerals for numbers
Use “1, 2, 3” instead of “one, two, three” for numbers. One exception is when mixing uses of numbers, such as “Enter two 3s.”
| :white_check_mark: Do | :no_entry_sign: Don’t |
| --- | --- |
| 3 new commits | Three new commits |
### Punctuation
Omit punctuation after phrases and labels to create a cleaner and more readable interface. Use punctuation to add clarity or be grammatically correct.
| Punctuation mark | Copy and paste | HTML entity | Unicode | Mac shortcut | Windows shortcut | Description |
|---|---|---|---|---|---|---|
| Period | **.** | | | | | Omit for single sentences in affordances like labels, hover text, bulleted lists, and modal body text.<br><br>Use in lists or modals with multiple sentences, and any sentence followed by a link or inline code.<br><br>Place inside quotation marks unless you’re telling the reader what to enter and it’s ambiguous whether to include the period. |
| Comma | **,** | | | | | Place inside quotation marks.<br><br>Use a [serial comma][serial comma] in lists of three or more terms. |
| Exclamation point | **!** | | | | | Avoid exclamation points as they tend to come across as shouting. Some exceptions include greetings or congratulatory messages. |
| Colon | **:** | `:` | `\u003A` | | | Omit from labels, for example, in the labels for fields in a form. |
| Apostrophe | **’** | `’` | `\u2019` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use for contractions (I’m, you’re, ’89) and to show possession.<br><br>To show possession, add an *’s* to all singular common nouns and names, even if they already end in an *s*: “Look into this worker process’s log.” For singular proper names ending in *s*, use only an apostrophe: “James’ commits.” For plurals of a single letter, add an *’s*: “Dot your i’s and cross your t’s.”<br><br>Omit for decades or acronyms: “the 1990s”, “MRs.” |
| Quotation marks | **“**<br><br>**”**<br><br>**‘**<br><br>**’** | `“`<br><br>`”`<br><br>`‘`<br><br>`’` | `\u201C`<br><br>`\u201D`<br><br>`\u2018`<br><br>`\u2019` | <kbd>⌥ Option</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>[</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>]</kbd><br><br><kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>]</kbd> | <kbd>Alt</kbd>+<kbd>0 1 4 7</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 8</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 5</kbd><br><br><kbd>Alt</kbd>+<kbd>0 1 4 6</kbd> | Use proper quotation marks (also known as smart quotes, curly quotes, or typographer’s quotes) for quotes. Single quotation marks are used for quotes inside of quotes.<br><br>The right single quotation mark symbol is also used for apostrophes.<br><br>Don’t use primes, straight quotes, or free-standing accents for quotation marks. |
| Primes | **′**<br><br>**″** | `′`<br><br>`″` | `\u2032`<br><br>`\u2033` | | <kbd>Alt</kbd>+<kbd>8 2 4 2</kbd><br><br><kbd>Alt</kbd>+<kbd>8 2 4 3</kbd> | Use prime (′) only in abbreviations for feet, arcminutes, and minutes: 3° 15′<br><br>Use double-prime (″) only in abbreviations for inches, arcseconds, and seconds: 3° 15′ 35″<br><br>Don’t use quotation marks, straight quotes, or free-standing accents for primes. |
| Straight quotes and accents | **"**<br><br>**'**<br><br>**`**<br><br>**´** | `"`<br><br>`'`<br><br>```<br><br>`´` | `\u0022`<br><br>`\u0027`<br><br>`\u0060`<br><br>`\u00B4` | | | Don’t use straight quotes or free-standing accents for primes or quotation marks.<br><br>Proper typography never uses straight quotes. They are left over from the age of typewriters and their only modern use is for code. |
| Ellipsis | **…** | `…` | | <kbd>⌥ Option</kbd>+<kbd>;</kbd> | <kbd>Alt</kbd>+<kbd>0 1 3 3</kbd> | Use to indicate an action in progress (“Downloading…”) or incomplete or truncated text. No space before the ellipsis.<br><br>Omit from menu items or buttons that open a modal or start some other process. |
| Chevrons | **«**<br><br>**»**<br><br>**‹**<br><br>**›**<br><br>**<**<br><br>**>** | `«`<br><br>`»`<br><br>`‹`<br><br>`›`<br><br>`<`<br><br>`>` | `\u00AB`<br><br>`\u00BB`<br><br>`\u2039`<br><br>`\u203A`<br><br>`\u003C`<br><br>`\u003E`<br><br> | | | Omit from links or buttons that open another page or move to the next or previous step in a process. Also known as angle brackets, angular quote brackets, or guillemets. |
| Em dash | **—** | `—` | `\u2014` | <kbd>⌥ Option</kbd>+<kbd>⇧ Shift</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 1</kbd> | Avoid using dashes to separate text. If you must use dashes for this purpose — like this — use an em dash surrounded by spaces. |
| En dash | **–** | `–` | `\u2013` | <kbd>⌥ Option</kbd>+<kbd>-</kbd> | <kbd>Alt</kbd>+<kbd>0 1 5 0</kbd> | Use an en dash without spaces instead of a hyphen to indicate a range of values, such as numbers, times, and dates: “3–5 kg”, “8:00 AM–12:30 PM”, “10–17 Jan” |
| Hyphen | **-** | | | | | Use to represent negative numbers, or to avoid ambiguity in adjective-noun or noun-participle pairs. Example: “anti-inflammatory”; “5-mile walk.”<br><br>Omit in commonly understood terms and adverbs that end in *ly*: “frontend”, “greatly improved performance.”<br><br>Omit in the term “open source.” |
| Parentheses | **( )** | | | | | Use only to define acronyms or jargon: “Secure web connections are based on a technology called SSL (the secure sockets layer).”<br><br>Avoid other uses and instead rewrite the text, or use dashes or commas to set off the information. If parentheses are required: If the parenthetical is a complete, independent sentence, place the period inside the parentheses; if not, the period goes outside. |
When using the <kbd>Alt</kbd> keystrokes in Windows, use the numeric keypad, not the row of numbers above the alphabet, and be sure Num Lock is turned on.
---
## Terminology
Only use the terms below.
When using verbs or adjectives:
* If the context clearly refers to the object, use them alone. Example: `Edit` or `Closed`
* If the context isn’t clear enough, use them with the object. Example: `Edit issue` or `Closed issues`
### Search
| Term | Use |
| ---- | --- |
| Search | When using all metadata to add criteria that match/don't match. Search can also affect ordering, by ranking best results. |
| Filter | When taking a single criteria that removes items within a list that match/don't match. Filters do not affect ordering. |
| Sort | Orders a list based on a single or grouped criteria |
### Projects and Groups
| Term | Use | :no_entry_sign: Don't |
| ---- | --- | ----- |
| Members | When discussing the people who are a part of a project or a group. | Don't use `users`. |
### Issues
#### Adjectives (states)
| Term | :no_entry_sign: Don’t |
| ---- | --- |
| Open | Don’t use `Pending` or `Created` |
| Closed | Don’t use `Archived` |
| Deleted | Don’t use `Removed` or `Trashed` |
#### Verbs (actions)
| Term | Use | :no_entry_sign: Don’t |
| ---- | --- | --- |
| New | Although it’s not a verb, `New` is a common standard and used for entering the creation mode of a non-existent issue | Don’t use `Create`, `Open`, or `Add` |
| Create | Only to indicate when or who created an issue ||
| Add | Associate an existing issue with an item or a list of items | Don’t use `New` or `Create` |
| View | Open the detail page of an issue | Don’t use `Open` or `See` |
| Edit | Enter the editing mode of an issue | Don’t use `Change`, `Modify` or `Update` |
| Submit | Finalize the *creation* process of an issue | Don’t use `Add`, `Create`, `New`, `Open`, `Save` or `Save changes` |
| Save | Finalize the *editing* process of an issue | Don’t use `Edit`, `Modify`, `Update`, `Submit`, or `Save changes` |
| Cancel | Cancel the *creation* or *editing* process of an issue | Don’t use `Back`, `Close`, or `Discard` |
| Close | Close an open issue | Don’t use `Archive` |
| Re-open | Re-open a closed issue | Don’t use `Open` |
| Delete | Permanently remove an issue from the system | Don’t use `Remove` |
| Remove | Remove the association an issue with an item or a list of items | Don’t use `Delete` |
### Merge requests
#### Adjectives (states)
| Term |
| ---- |
| Open |
| Merged |
#### Verbs (actions)
| Term | Use | :no_entry_sign: Don’t |
| ---- | --- | --- |
| Add | Add a merge request | Do not use `create` or `new` |
| View | View an open or merged merge request ||
| Edit | Edit an open or merged merge request| Do not use `update` |
| Approve | Approve an open merge request ||
| Remove approval, unapproved | Remove approval of an open merge request | Do not use `unapprove` as that is not an English word|
| Merge | Merge an open merge request ||
### Comments & Discussions
#### Comment
A **comment** is a written piece of text that users of GitLab can create. Comments have the meta data of author and timestamp. Comments can be added in a variety of contexts, such as issues, merge requests, and discussions.
#### Discussion
A **discussion** is a group of 1 or more comments. A discussion can include subdiscussions. Some discussions have the special capability of being able to be **resolved**. Both the comments in the discussion and the discussion itself can be resolved.
## Modals
- Destruction buttons should be clear and always say what they are destroying.
E.g., `Delete page` instead of just `Delete`.
- If the copy describes another action the user can take instead of the
destructive one, provide a way for them to do that as a secondary button.
- Avoid the word `cancel` or `canceled` in the descriptive copy. It can be
confusing when you then see the `Cancel` button.
see also: guidelines for [modal components](components.md#modals)
---
Portions of this page are modifications based on work created and shared by the [Android Open Source Project][android project] and used according to terms described in the [Creative Commons 2.5 Attribution License][creative commons].
[material design]:https://material.io/guidelines/
[features]:https://about.gitlab.com/features/"GitLab features page"
The global navigation is accessible via the menu button on the top left of the screen, and can be pinned to keep it open. It contains a consistent list of pages that allow you to view content that is across GitLab. For example, you can view your todos, issues and merge requests across projects and groups.
### Contextual navigation
The navigation in the header is contextual to each page. These options change depending on if you are looking at a project, group, or settings page. There should be no more than 10 items on a level in the contextual navigation, allowing it to comfortably fit on a typical laptop screen. There can be up to too levels of navigation. Each sub nav group should be a self-contained group of functionality. For example, everything related to the issue tracker should be under the 'Issue' tab, while everything relating to the wiki will be grouped under the 'Wiki' tab. The names used for each section should be short and easy to remember, ideally 1-2 words in length.
### Information architecture
The [GitLab Product Map](https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png) shows a visual representation of the information architecture for GitLab.
redirect_to:'https://design.gitlab.com/'
---
## Filtering
Today, lists are filtered by a series of dropdowns. Some of these dropdowns allow multiselect (labels), while others allow you to filter to one option (milestones). However, we are currently implementing a [new model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747) for this, and will update the guide when it is ready.
---
## Search results
### Global search
[Global search](https://gitlab.com/search?group_id=&project_id=13083&repository_ref=&scope=issues&search=mobile) allows you to search across items in a project, or even across multiple projects. You can switch tabs to filter on type of object, or filter by group.
### List search
There are several core lists in the GitLab experience, such as the Issue list and the Merge Request list. You are also able to [filter and search these lists](https://gitlab.com/gitlab-org/gitlab-ce/issues?utf8=%E2%9C%93&search=mobile). This UI will be updated with the [new filtering model](https://gitlab.com/gitlab-org/gitlab-ce/issues/21747).
---
## Empty states
Empty states need to be considered in the design of features. They are vital to helping onboard new users, making the experience feel more approachable and understandable. Empty states should feel inviting and provide just enough information to get people started. There should be a single call to action and a clear explanation of what to use the feature for.
The content of this documented was moved into the [GitLab Design System](https://design.gitlab.com/).
The illustrations should always align with topics and goals in specific context.
## Principles
#### Be simple.
- For clarity, we use simple and specific elements to create our illustrations.
#### Be optimistic.
- We are an open-minded, optimistic, and friendly team. We should reflect those values in our illustrations to connect with our brand experience.
#### Be gentle.
- Our illustrations assist users in understanding context and guide users in the right direction. Illustrations are supportive, so they should be obvious but not aggressive.
## Style
#### Shapes
- All illustrations are geometric rather than organic.
- The illustrations are made by circles, rectangles, squares, and triangles.
<imgsrc="img/illustrations-geometric.png"width=224pxalt="Example for geometric"/>
#### Stroke
- Standard border thickness: **4px**
- Depending on the situation, border thickness can be changed to **3px**. For example, when the illustration size is small, an illustration with 4px border thickness would look tight. In this case, the border thickness can be changed to 3px.
- We use **rounded caps** and **rounded corner**.
| Do | Don't |
| -------- | -------- |
| <imgsrc="img/illustrations-caps-do.png"width= 133pxalt="Do: caps and corner"/> | <imgsrc="img/illustrations-caps-don't.png"width= 133pxalt="Don't: caps and corner"/> |
#### Radius
- Standard corner radius: **10px**
- Depending on the situation, corner radius can be changed to **5px**. For example, when the illustration size is small, an illustration with 10px corner radius would be over-rounded. In this case, the corner radius can be changed to 5px.
<imgsrc="img/illustrations-border-radius.png"width= 464pxalt="Example for border radius"/>
#### Size
Depends on the situation, the illustration size can be the 3 types below:
**Large**
* Use case: Empty states, error pages(e.g. 404, 403)
* For vertical layout, the illustration should not larger than **430*300 px**.
* For horizontal layout, the illustration should not larger than **430*380 px**.
> We are in the process of transferring UX documentation to the [design.gitlab.com](https://gitlab.com/gitlab-org/design.gitlab.com) project. Any updates to these docs should be made in that project. If documentation does not yet exist within [design.gitlab.com](https://gitlab.com/gitlab-org/design.gitlab.com), [create an issue](https://gitlab.com/gitlab-org/design.gitlab.com/issues) and merge request to add your new changes.
# GitLab UX Guide
The goal of this guide is to provide standards, principles and in-depth information to design beautiful and effective GitLab features. This will be a living document, and we welcome contributions, feedback and suggestions.
## Design
---
### [Principles](principles.md)
These guiding principles set a solid foundation for our design system, and should remain relatively stable over multiple releases. They should be referenced as new design patterns are created.
---
### [Basics](basics.md)
The basic ingredients of our experience establish our personality and feel. This section includes details about typography, iconography, and color.
---
### [Animation](animation.md)
Guidance on the timing, curving and motion for GitLab.
---
### [Illustrations](illustrations.md)
Guidelines for principals and styles related to illustrations for GitLab.
---
### [Copy](copy.md)
Conventions on text and messaging within labels, buttons, and other components.
---
### [Components](components.md)
Components are the controls that make up the GitLab experience, including guidance around buttons, links, dropdowns, etc.
---
### [Surfaces](surfaces.md)
The GitLab experience is broken apart into several surfaces. Each of these surfaces is designated for a specific scope or type of content. Examples include the header, global menu, side pane, etc.
---
### [Features](features.md)
The previous building blocks are combined into complete features in the GitLab UX. Examples include our navigation, filters, search results, and empty states.
---
## Research
---
### [Users](users.md)
How we think about the variety of users of GitLab, from small to large teams, comparing opensource usage to enterprise, etc.
---
## Other
---
### [Tips for designers](tips.md)
Tips for exporting assets, and other guidance.
redirect_to:'https://design.gitlab.com/'
---
### [Resources](resources.md)
Resources for GitLab UX
The content of this documented was moved into the [GitLab Design System](https://design.gitlab.com/).
These are the guiding principles that we should strive for to establish a solid foundation for the GitLab experience.
## Professional and productive
GitLab is a tool to support what people do, day in, day out. We need to respect the importance of their work, and avoid gimicky details.
## Minimal and efficient
While work can get complicated, GitLab is about bringing a sharp focus, helping our customers know what matters now.
## Immediately recognizable
When you look at any screen, you should know immediately that it is GitLab. Our personality is strong and consistent across product and marketing experiences.
## Human and quirky
We need to build empathy with our users, understanding their state of mind, and connect with them at a human level. Quirkiness is part of our DNA, and we should embrace it in the right moments and contexts.
> TODO: Ensure these principles align well with the goals of the Marketing team
The content of this documented was moved into the [GitLab Design System](https://design.gitlab.com/).
This menu is to navigate to pages that contain content global to GitLab.
---
## Header
The header contains 3 main elements: Project switching and searching, user account avatar and settings, and a contextual menu that changes based on the current page.
---
## Side pane
The side pane holds supporting information and meta data for the information in the content area.
redirect_to:'https://design.gitlab.com/'
---
## Content area
The main content of the page. The content area can include other surfaces.
### Item title bar
The item title bar contains the top level information to identify the item, such as the name, id and status.
### Item system information
The system information block contains relevant system controlled information.
The content of this documented was moved into the [GitLab Design System](https://design.gitlab.com/).
When exporting SVGs, be sure to follow the following guidelines:
1. Convert all strokes to outlines.
1. Use pathfinder tools to combine overlapping paths and create compound paths.
1. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS.
1. Ensure that exported SVGs have been run through an [SVG cleaner](https://github.com/RazrFalcon/SVGCleaner) to remove unused elements and attributes.
You can open your SVG in a text editor to ensure that it is clean.
- Small to medium size organizations using GitLab CE
*[Matthieu Poirier](#matthieu-poirier)
- Responsible for managing and maintaining GitLab installation
- Any size organization
- Using CE or EE
*[James Mackey](#james-mackey)
- Medium to large size organizations using CE or EE
- Small organizations using EE
*[Karolina Plaskaty](#karolina-plaskaty)
- Using GitLab.com for personal/hobby projects
- Would like to use GitLab at work
- Working within a medium to large size organization
---
## Nazim Ramesh
- Small to medium size organizations using GitLab CE
### Demographics
**Age**
32 years old
**Location**
Germany
**Education**
Bachelor of Science in Computer Science
**Occupation**
Full-stack web developer
**Programming experience**
Over 10 years
**Frequently used programming languages**
JavaScript, SQL, PHP
**Hobbies / interests**
Functional programming, open source, gaming, web development, and web security.
### Motivations
Nazim works for a software development company which currently hires around 80 people. When Nazim first joined the company, the engineering team were using Subversion (SVN) as their primary form of source control. However, Nazim felt SVN was not flexible enough to work with many feature branches and noticed that developers with less experience of source control struggled with the central-repository nature of SVN. Armed with a wish list of features, Nazim began comparing source control tools. A search for "self-hosted Git server repository management" returned GitLab. In his own words, Nazim explains why he wanted the engineering team to start using GitLab:
>"I wanted them to switch away from SVN. I needed a server application to manage repositories. The common tools that were around just didn't meet the requirements. Most of them were too simple or plain...GitLab provided all the required features. Also, costs had to be low since we don't have a big budget for those things...the Community Edition was perfect in this regard."
In his role as a full-stack web developer, Nazim could recommend products that he would like the engineering team to use, but final approval lay with his line manager, Mike, VP of Engineering. Nazim recalls that he was met with reluctance from his colleagues when he raised moving to Git and using GitLab.
>"The biggest challenge...why should we change anything at all from the status quo? We needed to switch from SVN to Git. They knew they needed to learn Git and a Git workflow...using Git was scary to my colleagues...they thought it was more complex than SVN to use."
Undeterred, Nazim decided to migrate a couple of projects across to GitLab.
>"Old SVN users couldn't see the benefits of Git at first. It took a month or two to convince them."
Slowly, by showing his colleagues how easy it was to use Git, the majority of the team's projects were migrated to GitLab.
The engineering team have been using GitLab CE for around 2 years now. Nazim credits himself as being entirely responsible for his company's decision to move to GitLab.
### Frustrations
#### Adoption to GitLab has been slow
Not only has the engineering team had to get to grips with Git, they've also had to adapt to using GitLab. Due to lack of training and existing skills in other tools, the full feature set of GitLab CE is not being utilized. Nazim sold GitLab to his manager as an ‘all in one' tool which would replace multiple tools used within the company, thus saving costs. Nazim hasn't had the time to integrate the legacy tools to GitLab and he's struggling to convince his peers to change their habits.
#### Missing Features
Nazim's company want GitLab to be able to do everything. There isn't a large budget for software, so they're selective about what tools are implemented. It needs to add real value to the company. In order for GitLab to be widely adopted and to meet the requirements of different roles within the company, it needs a host of features. When an individual within Nazim's company wants to know if GitLab has a specific feature or does a particular thing, Nazim is the person to ask. He becomes the point of contact to investigate, build or sometimes just raise the feature request. Nazim gets frustrated when GitLab isn't able to do what he or his colleagues need it to do.
#### Regressions and bugs
Nazim often has to calm down his colleagues, when a release contains regressions or new bugs. As he puts it "every new version adds something awesome, but breaks something". He feels that "old issues for minor annoyances get quickly buried in the mass of open issues and linger for a very long time. More generally, I have the feeling that GitLab focus on adding new functionalities, but overlook a bunch of annoying minor regressions or introduced bugs." Due to limited resource and expertise within the team, not only is it difficult to remain up-to-date with the frequent release cycle, it's also counterproductive to fix workflows every month.
#### Uses too much RAM and CPU
>"Memory usages mean that if we host it from a cloud-based host like AWS, we spend almost as much on the instance as what we would pay GitHub"
#### UI/UX
GitLab's interface initially attracted Nazim when he was comparing version control software. He thought it would help his less technical colleagues to adapt to using Git and perhaps, GitLab could be rolled out to other areas of the business, beyond engineering. However, using GitLab's interface daily has left him frustrated at the lack of personalization/control over his user experience. He's also regularly lost in a maze of navigation. Whilst he acknowledges that GitLab listens to its users and that the interface is improving, he becomes annoyed when the changes are too progressive. "Too frequent UI changes. Most of them tend to turn out great after a few cycles of fixes, but the frequency is still far too high for me to feel comfortable to always stay on the current release."
### Goals
* To convince his colleagues to fully adopt GitLab CE, thus improving workflow and collaboration.
* To use a feature-rich version control platform that covers all stages of the development lifecycle, in order to reduce dependencies on other tools.
* To use an intuitive and stable product, so he can spend more time on his core job responsibilities and less time bug-fixing, guiding colleagues, etc.
- Responsible for managing and maintaining GitLab installation
- Any size organization
- Using CE or EE
### Demographics
**Age**
42 years old
**Location**
France
**Education**
Masters Degree in Computer Science
**Occupation**
DevOps Engineer
**Programming experience**
Over 10 years
**Frequently used programming languages**
JavaScript, SQL, PHP and Node.js
**Hobbies / interests**
Functional programming, data analysis, building apps, and tools.
### Motivations
Matthieu works in DevOps for a web services company which currently hires 90 staff. When Matthieu first joined the company, he was responsible for managing a custom built in-house bug tracking tool and release management system. Over time, as the company grew, his colleagues requested more features and tools to help them in their day-to-day work. To meet their needs, Matthieu was forced to "hack together" a solution. In his own words, Matthieu explains that it became:
>"...a huge pain managing access to all the individual pieces. In addition, they didn't have any integration with each other, nobody ended up using them and we couldn't do any workflows with merge requests and the like. I was sick of managing all those separate parts and wanted to move to a single platform that would handle it all."
He further explains that he wanted to introduce "better, easier, more formal code reviews" and to start using continuous integration and deployment.
Matthieu tried to find a platform which would consolidate the company's existing toolset, and centralize code, documentation, and issues. He discovered GitHub, but the price was an issue:
>"We needed to host our code on-site and wanted GitHub Enterprise functionality without the GitHub Enterprise costs."
Not only was GitLab cheaper than GitHub, it was also more cost-effective than maintaining multiple tools. Subsequently, Matthieu found it easy to sell the merits of GitLab to his manager.
Matthieu describes GitLab as:
>"the only tool that offers the real feeling of having everything you need in one place."
He credits himself as being entirely responsible for moving his company to GitLab.
### Frustrations
#### Updating to the latest release
Matthieu introduced his company to GitLab. He is responsible for maintaining and managing the company's installation in addition to his day job. He feels updates are too frequent and he doesn't always have sufficient time to update GitLab. As a result, he's not up to date with releases.
Matthieu tried to set up automatic updates, however, as he isn't a Systems Administrator, he wasn't confident in his setup. He feels he should be able to "upgrade without users even noticing" but hasn't figured out how to do this yet. Matthieu would like the "update process to be triggered from the Admin Panel, perhaps accompanied with a changelog and the option to skip updates."
Matthieu is looking for confirmation that his update procedure is "secure and efficient" so more tutorials related to this topic would be useful to him.
#### Configuration
Matthieu dislikes using the combination of gitlab.rb and the UI for changing settings. He explains that it "would be nice to be able to configure more from the Admin UI rather than just the config files."
#### Creating a backup
Matthieu explains that the "backup solution is not well integrated into the UI", for example, he "cannot see if backups succeeded" or whether they have been rolled back to via the UI.
#### Onboarding
It's Matthieu's responsibility to get teams across his organization up and running with GitLab. He explains that whilst many teams might be leveraging GitLab, they are:
>"..not aware of GitLab's powerful CI or our omnibus install of Mattermost...It would be nice to have a tutorial type walkthrough available when a new user logs in on how to get started with all these features. AutoDevOps may solve some of this, but GitLab has many powerful features wrapped up into it and some [teams] may just think that it is only a Git repo similar to GitHub."
He states that there has been: "a sluggishness of others to adapt" and it's "a low-effort adaptation at that."
### Goals
* To save time. One of the reasons Matthieu moved his company to GitLab was to reduce the effort it took him to manage and configure multiple tools, thus saving him time. He has to balance his day job in addition to managing the company's GitLab installation and onboarding new teams to GitLab.
* To use a platform which is easy to manage. Matthieu isn't a Systems Administrator, and when updating GitLab, creating backups, etc. He would prefer to work within GitLab's UI. Explanations / guided instructions when configuring settings in GitLab's interface would really help Matthieu. He needs reassurance that what he is about to change is
- The right setting.
- Will provide him with the desired result he wants.
* Matthieu needs to educate his colleagues about GitLab. Matthieu's colleagues won't adopt GitLab as they're unaware of its capabilities and the positive impact it could have on their work. Matthieu needs support in getting this message across to them.
---
## James Mackey
- Medium to large size organizations using CE or EE
- Small organizations using EE
### Demographics
**Age**
36 years old
**Location**
US
**Education**
Masters degree in Computer Science
**Occupation**
Full-stack web developer
**Programming experience**
Over 10 years
**Frequently used programming languages**
JavaScript, SQL, Node.js, Java, PHP, Python
**Hobbies / interests**
DevOps, open source, web development, science, automation, and electronics.
### Motivations
James works for a research company which currently hires around 800 staff. He began using GitLab.com back in 2013 for his own open source, hobby projects and loved "the simplicity of installation, administration and use". After using GitLab for over a year, he began to wonder about using it at work. James explains:
>"We first installed the CE edition...on a staging server for a PoC and asked a beta team to use it, specifically for the Merge Request features. Soon other teams began asking us to be beta users too because the team that was already using GitLab was really enjoying it."
James and his colleagues also reviewed competitor products including GitHub Enterprise, but they found it "less innovative and with considerable costs...GitLab had the features we wanted at a much lower cost per head than GitHub".
The company James works for provides employees with a discretionary budget to spend how they want on software, so James and his team decided to upgrade to EE.
James feels partially responsible for his organization's decision to start using GitLab.
>"It's still up to the teams themselves [to decide] which tools to use. We just had a great experience moving our daily development to GitLab, so other teams have followed the path or are thinking about switching."
### Frustrations
#### Third Party Integration
Some of GitLab EE's features are too basic, in particular, issues boards which do not have the level of reporting that James and his team need. Subsequently, they still need to use GitLab EE in conjunction with other tools, such as JIRA. Whilst James feels it isn't essential for GitLab to meet all his needs (his company are happy for him to use, and pay for, multiple tools), he sometimes isn't sure what is/isn't possible with plugins and what level of custom development he and his team will need to do.
#### UX/UI
James and his team use CI quite heavily for several projects. Whilst they've welcomed improvements to the builds and pipelines interface, they still have some difficulty following build process on the different tabs under Pipelines. Some confusion has arisen from not knowing where to find different pieces of information or how to get to the next stages logs from the current stage's log output screen. They feel more intuitive linking and flow may alleviate the problem. Generally, they feel GitLab's navigation needs to reviewed and optimized.
#### Permissions
>"There is no granular control over user or group permissions. The permissions for a project are too tightly coupled to the permissions for GitLab CI/build pipelines."
### Goals
* To be able to integrate third-party tools easily with GitLab EE and to create custom integrations and patches where needed.
* To use GitLab EE primarily for code hosting, merge requests, continuous integration and issue management. James and his team want to be able to understand and use these particular features easily.
* To able to share one instance of GitLab EE with multiple teams across the business. Advanced user management, the ability to separate permissions on different parts of the source code, etc are important to James.
---
## Karolina Plaskaty
- Using GitLab.com for personal/hobby projects
- Would like to use GitLab at work
- Working within a medium to large size organization
Web development, mobile development, UX, open source, gaming, and travel.
### Motivations
Karolina has been using GitLab.com for around a year. She roughly spends 8 hours every week programming, of that, 2 hours is spent contributing to open source projects. Karolina contributes to open source projects to gain programming experience and to give back to the community. She likes GitLab.com for its free private repositories and range of features which provide her with everything she needs for her personal projects. Karolina is also a massive fan of GitLab's values and the fact that it isn't a "behemoth of a company". She explains that "displaying every single thing (doc, culture, assumptions, development...) in the open gives me greater confidence to choose GitLab personally and to recommend it at work." She's also an avid reader of GitLab's blog.
Karolina works for a software development company which currently hires around 500 people. Karolina would love to use GitLab at work but the company has used GitHub Enterprise for a number of years. She describes management at her company as "old fashioned" and explains that it's "less of a technical issue and more of a cultural issue" to convince upper management to move to GitLab. Karolina is also relatively new to the company so she's apprehensive about pushing too hard to change version control platforms.
### Frustrations
#### Unable to use GitLab at work
Karolina wants to use GitLab at work but isn't sure how to approach the subject with management. In her current role, she doesn't feel that she has the authority to request GitLab.
#### Performance
GitLab.com is frequently slow and unavailable. Karolina has also heard that GitLab is a "memory hog" which has deterred her from running GitLab on her own machine for just hobby / personal projects.
#### UX/UI
Karolina has an interest in UX and therefore has strong opinions about how GitLab should look and feel. She feels the interface is cluttered, "it has too many links/buttons" and the navigation "feels a bit weird sometimes. I get lost if I don't pay attention." As Karolina also enjoys contributing to open-source projects, it's important to her that GitLab is well designed for public repositories, she doesn't feel that GitLab currently achieves this.
### Goals
* To develop her programming experience and to learn from other developers.
* To contribute to both her own and other open source projects.
* To use a fast and intuitive version control platform.
The content of this documented was moved into the [GitLab Design System](https://design.gitlab.com/).
@@ -19,6 +19,7 @@ A permission level of `Developer` or higher is required to create labels.
### New project label
To create a **project label**, navigate to **Issues > Labels** in the project.
This page only shows project labels in this project and group labels of this project's parent group.
Click the **New label** button. Enter the title, an optional description, and the background color. Click **Create label** to create the label.
...
...
@@ -33,6 +34,7 @@ GitLab will add the following default labels to the project:
### New group label
To create a **group label**, follow similar steps from above to project labels. Navigate to **Issues > Labels** in the group and create it from there.
This page only shows group labels in this group.
Alternatively, you can create group labels also from Epic sidebar. Please note that the created label will belong to the immediate group to which epic belongs.
