diff options
Diffstat (limited to 'doc')
135 files changed, 2608 insertions, 369 deletions
diff --git a/doc/README.md b/doc/README.md index c30bf328003..66c8c26e4f0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -21,6 +21,7 @@ - [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN. - [University](university/README.md) Learn Git and GitLab through videos and courses. - [Git Attributes](user/project/git_attributes.md) Managing Git attributes using a `.gitattributes` file. +- [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf) Download a PDF describing the most used Git operations. ## Administrator documentation diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index bf7814875bf..fd23047f027 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -35,6 +35,10 @@ of one hour. To enable LDAP integration you need to add your LDAP server settings in `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml`. +There is a Rake task to check LDAP configuration. After configuring LDAP +using the documentation below, see [LDAP check Rake task](../raketasks/check.md#ldap-check) +for information on the LDAP check Rake task. + >**Note**: In GitLab EE, you can configure multiple LDAP servers to connect to one GitLab server. diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index 537f4f3501d..5602d70f1ef 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -76,7 +76,7 @@ configuration to move each data location to a subdirectory: user['home'] = '/gitlab-data/home' git_data_dir '/gitlab-data/git-data' gitlab_rails['shared_path'] = '/gitlab-data/shared' -gitlab_rails['uploads_directory'] = "/gitlab-data/uploads" +gitlab_rails['uploads_directory'] = '/gitlab-data/uploads' gitlab_ci['builds_directory'] = '/gitlab-data/builds' ``` diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index bc424330656..8656b42f274 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -48,15 +48,15 @@ Redis. redis['password'] = 'Redis Password' ``` -1. Run `sudo gitlab-ctl reconfigure` to install and configure PostgreSQL. +1. Run `sudo touch /etc/gitlab/skip-auto-migrations` to prevent database migrations + from running on upgrade. Only the primary GitLab application server should + handle migrations. + +1. Run `sudo gitlab-ctl reconfigure` to install and configure Redis. > **Note**: This `reconfigure` step will result in some errors. That's OK - don't be alarmed. -1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations - from running on upgrade. Only the primary GitLab application server should - handle migrations. - ## Experimental Redis Sentinel support > [Introduced][ce-1877] in GitLab 8.11. diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index ad1fa98b63b..f846c06ca42 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -3,6 +3,14 @@ > [Introduced][ce-2371] in GitLab 8.4. --- +## Automatic housekeeping + +GitLab automatically runs `git gc` and `git repack` on repositories +after Git pushes. If needed you can change how often this happens, or +to turn it off, go to **Admin area > Settings** +(`/admin/application_settings`). + +## Manual housekeeping The housekeeping function runs `git gc` ([man page][man]) on the current project Git repository. diff --git a/doc/raketasks/check_repos_output.png b/doc/administration/img/raketasks/check_repos_output.png Binary files differindex 1f632566b00..1f632566b00 100644 --- a/doc/raketasks/check_repos_output.png +++ b/doc/administration/img/raketasks/check_repos_output.png diff --git a/doc/administration/operations.md b/doc/administration/operations.md index 4b582d16b64..0daceb98d99 100644 --- a/doc/administration/operations.md +++ b/doc/administration/operations.md @@ -1,6 +1,7 @@ # GitLab operations - [Sidekiq MemoryKiller](operations/sidekiq_memory_killer.md) +- [Sidekiq Job throttling](operations/sidekiq_job_throttling.md) - [Cleaning up Redis sessions](operations/cleaning_up_redis_sessions.md) - [Understanding Unicorn and unicorn-worker-killer](operations/unicorn.md) - [Moving repositories to a new location](operations/moving_repositories.md) diff --git a/doc/administration/operations/img/sidekiq_job_throttling.png b/doc/administration/operations/img/sidekiq_job_throttling.png Binary files differnew file mode 100644 index 00000000000..7f29a4d3c46 --- /dev/null +++ b/doc/administration/operations/img/sidekiq_job_throttling.png diff --git a/doc/administration/operations/sidekiq_job_throttling.md b/doc/administration/operations/sidekiq_job_throttling.md new file mode 100644 index 00000000000..ddeaa22e288 --- /dev/null +++ b/doc/administration/operations/sidekiq_job_throttling.md @@ -0,0 +1,33 @@ +# Sidekiq Job throttling + +> Note: Introduced with GitLab 8.14 + +When your GitLab installation needs to handle tens of thousands of background +jobs, it can be convenient to throttle queues that do not need to be executed +immediately, e.g. long running jobs like Pipelines, thus allowing jobs that do +need to be executed immediately to have access to more resources. + +In order to accomplish this, you can limit the amount of workers that certain +slow running queues can have available. This is what we call Sidekiq Job +Throttling. Depending on your infrastructure, you might have different slow +running queues, which is why you can choose which queues you want to throttle +and by how much you want to throttle them. + +These settings are available in the Application Settings of your GitLab +installation. + + + +The throttle factor determines the maximum number of workers a queue can run on. +This value gets multiplied by `:concurrency` value set in the Sidekiq settings +and rounded up to the closest full integer. + +So, for example, you set the `:concurrency` to 25 and the `Throttling factor` to +0.1, the maximum workers assigned to the selected queues would be 3. + +```ruby +queue_limit = (factor * Sidekiq.options[:concurrency]).ceil +``` + +After enabling the job throttling, you will need to restart your GitLab +instance, in order for the changes to take effect.
\ No newline at end of file diff --git a/doc/administration/raketasks/check.md b/doc/administration/raketasks/check.md new file mode 100644 index 00000000000..d1d2fed4861 --- /dev/null +++ b/doc/administration/raketasks/check.md @@ -0,0 +1,97 @@ +# Check Rake Tasks + +## Repository Integrity + +Even though Git is very resilient and tries to prevent data integrity issues, +there are times when things go wrong. The following Rake tasks intend to +help GitLab administrators diagnose problem repositories so they can be fixed. + +There are 3 things that are checked to determine integrity. + +1. Git repository file system check ([git fsck](https://git-scm.com/docs/git-fsck)). + This step verifies the connectivity and validity of objects in the repository. +1. Check for `config.lock` in the repository directory. +1. Check for any branch/references lock files in `refs/heads`. + +It's important to note that the existence of `config.lock` or reference locks +alone do not necessarily indicate a problem. Lock files are routinely created +and removed as Git and GitLab perform operations on the repository. They serve +to prevent data integrity issues. However, if a Git operation is interrupted these +locks may not be cleaned up properly. + +The following symptoms may indicate a problem with repository integrity. If users +experience these symptoms you may use the rake tasks described below to determine +exactly which repositories are causing the trouble. + +- Receiving an error when trying to push code - `remote: error: cannot lock ref` +- A 500 error when viewing the GitLab dashboard or when accessing a specific project. + +### Check all GitLab repositories + +This task loops through all repositories on the GitLab server and runs the +3 integrity checks described previously. + +**Omnibus Installation** + +``` +sudo gitlab-rake gitlab:repo:check +``` + +**Source Installation** + +```bash +sudo -u git -H bundle exec rake gitlab:repo:check RAILS_ENV=production +``` + +### Check repositories for a specific user + +This task checks all repositories that a specific user has access to. This is important +because sometimes you know which user is experiencing trouble but you don't know +which project might be the cause. + +If the rake task is executed without brackets at the end, you will be prompted +to enter a username. + +**Omnibus Installation** + +```bash +sudo gitlab-rake gitlab:user:check_repos +sudo gitlab-rake gitlab:user:check_repos[<username>] +``` + +**Source Installation** + +```bash +sudo -u git -H bundle exec rake gitlab:user:check_repos RAILS_ENV=production +sudo -u git -H bundle exec rake gitlab:user:check_repos[<username>] RAILS_ENV=production +``` + +Example output: + + + +## LDAP Check + +The LDAP check Rake task will test the bind_dn and password credentials +(if configured) and will list a sample of LDAP users. This task is also +executed as part of the `gitlab:check` task, but can run independently +using the command below. + +**Omnibus Installation** + +``` +sudo gitlab-rake gitlab:ldap:check +``` + +**Source Installation** + +```bash +sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production +``` + +By default, the task will return a sample of 100 LDAP users. Change this +limit by passing a number to the check task: + +```bash +rake gitlab:ldap:check[50] +``` diff --git a/doc/api/groups.md b/doc/api/groups.md index b56d74d25e0..45a3118f27a 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -26,6 +26,15 @@ GET /groups You can search for groups by name or path, see below. +======= +## List owned groups + +Get a list of groups which are owned by the authenticated user. + +``` +GET /groups/owned +``` + ## List a group's projects Get a list of projects in this group. diff --git a/doc/api/labels.md b/doc/api/labels.md index 656232cc940..78686fdcad4 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -20,46 +20,61 @@ Example response: ```json [ - { - "name" : "bug", - "color" : "#d9534f", - "description": "Bug reported by user", - "open_issues_count": 1, - "closed_issues_count": 0, - "open_merge_requests_count": 1 - }, - { - "color" : "#d9534f", - "name" : "confirmed", - "description": "Confirmed issue", - "open_issues_count": 2, - "closed_issues_count": 5, - "open_merge_requests_count": 0 - }, - { - "name" : "critical", - "color" : "#d9534f", - "description": "Critical issue. Need fix ASAP", - "open_issues_count": 1, - "closed_issues_count": 3, - "open_merge_requests_count": 1 - }, - { - "name" : "documentation", - "color" : "#f0ad4e", - "description": "Issue about documentation", - "open_issues_count": 1, - "closed_issues_count": 0, - "open_merge_requests_count": 2 - }, - { - "color" : "#5cb85c", - "name" : "enhancement", - "description": "Enhancement proposal", - "open_issues_count": 1, - "closed_issues_count": 0, - "open_merge_requests_count": 1 - } + { + "id" : 1, + "name" : "bug", + "color" : "#d9534f", + "description": "Bug reported by user", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 1, + "subscribed": false, + "priority": 10 + }, + { + "id" : 4, + "color" : "#d9534f", + "name" : "confirmed", + "description": "Confirmed issue", + "open_issues_count": 2, + "closed_issues_count": 5, + "open_merge_requests_count": 0, + "subscribed": false, + "priority": null + }, + { + "id" : 7, + "name" : "critical", + "color" : "#d9534f", + "description": "Critical issue. Need fix ASAP", + "open_issues_count": 1, + "closed_issues_count": 3, + "open_merge_requests_count": 1, + "subscribed": false, + "priority": null + }, + { + "id" : 8, + "name" : "documentation", + "color" : "#f0ad4e", + "description": "Issue about documentation", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 2, + "subscribed": false, + "priority": null + }, + { + "id" : 9, + "color" : "#5cb85c", + "name" : "enhancement", + "description": "Enhancement proposal", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 1, + "subscribed": true, + "priority": null + } ] ``` @@ -80,6 +95,7 @@ POST /projects/:id/labels | `name` | string | yes | The name of the label | | `color` | string | yes | The color of the label in 6-digit hex notation with leading `#` sign | | `description` | string | no | The description of the label | +| `priority` | integer | no | The priority of the label. Must be greater or equal than zero or `null` to remove the priority. | ```bash curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels" @@ -89,9 +105,15 @@ Example response: ```json { - "name" : "feature", - "color" : "#5843AD", - "description":null + "id" : 10, + "name" : "feature", + "color" : "#5843AD", + "description":null, + "open_issues_count": 0, + "closed_issues_count": 0, + "open_merge_requests_count": 0, + "subscribed": false, + "priority": null } ``` @@ -120,14 +142,15 @@ Example response: ```json { - "title" : "feature", - "color" : "#5843AD", - "description": "New feature proposal", - "updated_at" : "2015-11-03T21:22:30.737Z", - "template" : false, - "project_id" : 1, - "created_at" : "2015-11-03T21:22:30.737Z", - "id" : 9 + "id" : 1, + "name" : "bug", + "color" : "#d9534f", + "description": "Bug reported by user", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 1, + "subscribed": false, + "priority": null } ``` @@ -151,6 +174,8 @@ PUT /projects/:id/labels | `new_name` | string | yes if `color` is not provided | The new name of the label | | `color` | string | yes if `new_name` is not provided | The new color of the label in 6-digit hex notation with leading `#` sign | | `description` | string | no | The new description of the label | +| `priority` | integer | no | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. | + ```bash curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/labels" @@ -160,9 +185,15 @@ Example response: ```json { - "color" : "#8E44AD", - "name" : "docs", - "description": "Documentation" + "id" : 8, + "name" : "docs", + "color" : "#8E44AD", + "description": "Documentation", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 2, + "subscribed": false, + "priority": null } ``` @@ -191,13 +222,15 @@ Example response: ```json { - "name": "Docs", - "color": "#cc0033", - "description": "", - "open_issues_count": 0, - "closed_issues_count": 0, - "open_merge_requests_count": 0, - "subscribed": true + "id" : 1, + "name" : "bug", + "color" : "#d9534f", + "description": "Bug reported by user", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 1, + "subscribed": true, + "priority": null } ``` @@ -226,12 +259,14 @@ Example response: ```json { - "name": "Docs", - "color": "#cc0033", - "description": "", - "open_issues_count": 0, - "closed_issues_count": 0, - "open_merge_requests_count": 0, - "subscribed": false + "id" : 1, + "name" : "bug", + "color" : "#d9534f", + "description": "Bug reported by user", + "open_issues_count": 1, + "closed_issues_count": 0, + "open_merge_requests_count": 1, + "subscribed": false, + "priority": null } ``` diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index ff6c9e4931c..aea1c12a392 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -4,7 +4,7 @@ **Valid notification levels** -The notification levels are defined in the `NotificationSetting::level` model enumeration. Currently, these levels are recognized: +The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized: ``` disabled @@ -28,6 +28,8 @@ reopen_merge_request close_merge_request reassign_merge_request merge_merge_request +failed_pipeline +success_pipeline ``` ## Global notification settings @@ -77,6 +79,8 @@ curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab | `close_merge_request` | boolean | no | Enable/disable this notification | | `reassign_merge_request` | boolean | no | Enable/disable this notification | | `merge_merge_request` | boolean | no | Enable/disable this notification | +| `failed_pipeline` | boolean | no | Enable/disable this notification | +| `success_pipeline` | boolean | no | Enable/disable this notification | Example response: @@ -141,6 +145,8 @@ curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab | `close_merge_request` | boolean | no | Enable/disable this notification | | `reassign_merge_request` | boolean | no | Enable/disable this notification | | `merge_merge_request` | boolean | no | Enable/disable this notification | +| `failed_pipeline` | boolean | no | Enable/disable this notification | +| `success_pipeline` | boolean | no | Enable/disable this notification | Example responses: @@ -161,7 +167,9 @@ Example responses: "reopen_merge_request": false, "close_merge_request": false, "reassign_merge_request": false, - "merge_merge_request": false + "merge_merge_request": false, + "failed_pipeline": false, + "success_pipeline": false } } ``` diff --git a/doc/api/users.md b/doc/api/users.md index a50ba5432fe..041df07c051 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -33,6 +33,18 @@ GET /users ] ``` +In addition, you can filter users based on states eg. `blocked`, `active` +This works only to filter users who are `blocked` or `active`. +It does not support `active=false` or `blocked=false`. + +``` +GET /users?active=true +``` + +``` +GET /users?blocked=true +``` + ### For admins ``` @@ -120,6 +132,8 @@ For example: GET /users?username=jack_smith ``` +You can search for users who are external with: `/users?external=true` + ## Single user Get a single user. diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 959741f7338..89088cf9b83 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -44,7 +44,8 @@ GitLab Runner then executes build scripts as the `gitlab-runner` user. 2. Install Docker Engine on server. - For more information how to install Docker Engine on different systems checkout the [Supported installations](https://docs.docker.com/engine/installation/). + For more information how to install Docker Engine on different systems + checkout the [Supported installations](https://docs.docker.com/engine/installation/). 3. Add `gitlab-runner` user to `docker` group: @@ -122,11 +123,17 @@ In order to do that, follow the steps: Insecure = false ``` -1. You can now use `docker` in the build script (note the inclusion of the `docker:dind` service): +1. You can now use `docker` in the build script (note the inclusion of the + `docker:dind` service): ```yaml image: docker:latest + # When using dind, it's wise to use the overlayfs driver for + # improved performance. + variables: + DOCKER_DRIVER: overlay + services: - docker:dind @@ -140,15 +147,21 @@ In order to do that, follow the steps: - docker run my-docker-image /script/to/run/tests ``` -Docker-in-Docker works well, and is the recommended configuration, but it is not without its own challenges: -* By enabling `--docker-privileged`, you are effectively disabling all of -the security mechanisms of containers and exposing your host to privilege -escalation which can lead to container breakout. For more information, check out the official Docker documentation on -[Runtime privilege and Linux capabilities][docker-cap]. -* Using docker-in-docker, each build is in a clean environment without the past -history. Concurrent builds work fine because every build gets it's own instance of docker engine so they won't conflict with each other. But this also means builds can be slower because there's no caching of layers. -* By default, `docker:dind` uses `--storage-driver vfs` which is the slowest form -offered. +Docker-in-Docker works well, and is the recommended configuration, but it is +not without its own challenges: + +- By enabling `--docker-privileged`, you are effectively disabling all of + the security mechanisms of containers and exposing your host to privilege + escalation which can lead to container breakout. For more information, check + out the official Docker documentation on + [Runtime privilege and Linux capabilities][docker-cap]. +- Using docker-in-docker, each build is in a clean environment without the past + history. Concurrent builds work fine because every build gets it's own + instance of Docker engine so they won't conflict with each other. But this + also means builds can be slower because there's no caching of layers. +- By default, `docker:dind` uses `--storage-driver vfs` which is the slowest + form offered. To use a different driver, see + [Using the overlayfs driver](#using-the-overlayfs-driver). An example project using this approach can be found here: https://gitlab.com/gitlab-examples/docker. @@ -221,6 +234,40 @@ work as expected since volume mounting is done in the context of the host machine, not the build container. e.g. `docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests` +## Using the OverlayFS driver + +By default, when using `docker:dind`, Docker uses the `vfs` storage driver which +copies the filesystem on every run. This is a very disk-intensive operation +which can be avoided if a different driver is used, for example `overlay`. + +1. Make sure a recent kernel is used, preferably `>= 4.2`. +1. Check whether the `overlay` module is loaded: + + ``` + sudo lsmod | grep overlay + ``` + + If you see no result, then it isn't loaded. To load it use: + + ``` + sudo modprobe overlay + ``` + + If everything went fine, you need to make sure module is loaded on reboot. + On Ubuntu systems, this is done by editing `/etc/modules`. Just add the + following line into it: + + ``` + overlay + ``` + +1. Use the driver by defining a variable at the top of your `.gitlab-ci.yml`: + + ``` + variables: + DOCKER_DRIVER: overlay + ``` + ## Using the GitLab Container Registry > **Note:** diff --git a/doc/development/README.md b/doc/development/README.md index bf1f054b7d5..f88456a7a7a 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -14,7 +14,7 @@ contributing to documentation. - [SQL Migration Style Guide](migration_style_guide.md) for creating safe SQL migrations - [Testing standards and style guidelines](testing.md) -- [UI guide](ui_guide.md) for building GitLab with existing CSS styles and elements +- [UX guide](ux_guide/index.md) for building GitLab with existing CSS styles and elements - [Frontend guidelines](frontend.md) - [SQL guidelines](sql.md) for working with SQL queries - [Sidekiq guidelines](sidekiq_style_guide.md) for working with Sidekiq workers diff --git a/doc/development/frontend.md b/doc/development/frontend.md index 1d7d9127a64..ec8f2d6531c 100644 --- a/doc/development/frontend.md +++ b/doc/development/frontend.md @@ -228,7 +228,7 @@ For our currently-supported browsers, see our [requirements][requirements]. [page-specific-js-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/13bb9ed77f405c5f6ee4fdbc964ecf635c9a223f/app/views/projects/graphs/_head.html.haml#L6-8 [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules -[observatory-cli]: https://github.com/mozilla/http-observatory-cli) +[observatory-cli]: https://github.com/mozilla/http-observatory-cli [qualys-ssl]: https://www.ssllabs.com/ssltest/analyze.html [secure_headers]: https://github.com/twitter/secureheaders [mdn-csp]: https://developer.mozilla.org/en-US/docs/Web/Security/CSP diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md index 105e2f1242a..b8669964c84 100644 --- a/doc/development/instrumentation.md +++ b/doc/development/instrumentation.md @@ -24,7 +24,7 @@ namespace you can use the `configure` class method. This method simply yields the supplied block while passing `Gitlab::Metrics::Instrumentation` as its argument. An example: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_method(Foo, :bar) conf.instrument_method(Foo, :baz) @@ -41,7 +41,7 @@ Method instrumentation should be added in the initializer Instrumenting a single method: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_method(User, :find_by) end @@ -49,7 +49,7 @@ end Instrumenting an entire class hierarchy: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_class_hierarchy(ActiveRecord::Base) end @@ -57,7 +57,7 @@ end Instrumenting all public class methods: -``` +```ruby Gitlab::Metrics::Instrumentation.configure do |conf| conf.instrument_methods(User) end @@ -68,7 +68,7 @@ end The easiest way to check if a method has been instrumented is to check its source location. For example: -``` +```ruby method = Rugged::TagCollection.instance_method(:[]) method.source_location diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 61b0fbc89c9..fd8335d251e 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -60,7 +60,7 @@ migration was tested. If you need to remove index, please add a condition like in following example: -``` +```ruby remove_index :namespaces, column: :name if index_exists?(:namespaces, :name) ``` @@ -75,7 +75,7 @@ need for downtime. To use this method you must disable transactions by calling the method `disable_ddl_transaction!` in the body of your migration class like so: -``` +```ruby class MyMigration < ActiveRecord::Migration include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -96,7 +96,7 @@ the `up` and `down` methods in your migration class. For example, to add the column `foo` to the `projects` table with a default value of `10` you'd write the following: -``` +```ruby class MyMigration < ActiveRecord::Migration include Gitlab::Database::MigrationHelpers disable_ddl_transaction! @@ -125,7 +125,7 @@ set the limit to 8-bytes. This will allow the column to hold a value up to Rails migration example: -``` +```ruby add_column_with_default(:projects, :foo, :integer, default: 10, limit: 8) # or @@ -145,7 +145,7 @@ Please prefer Arel and plain SQL over usual ActiveRecord syntax. In case of usin Example with Arel: -``` +```ruby users = Arel::Table.new(:users) users.group(users[:user_id]).having(users[:id].count.gt(5)) @@ -154,7 +154,7 @@ users.group(users[:user_id]).having(users[:id].count.gt(5)) Example with plain SQL and `quote_string` helper: -``` +```ruby select_all("SELECT name, COUNT(id) as cnt FROM tags GROUP BY name HAVING COUNT(id) > 1").each do |tag| tag_name = quote_string(tag["name"]) duplicate_ids = select_all("SELECT id FROM tags WHERE name = '#{tag_name}'").map{|tag| tag["id"]} diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index 65cdd74bdb6..73893f9dd46 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -129,7 +129,7 @@ Various methods for opening and reading files in Ruby can be used to read the standard output of a process instead of a file. The following two commands do roughly the same: -``` +```ruby `touch /tmp/pawned-by-backticks` File.read('|touch /tmp/pawned-by-file-read') ``` @@ -142,7 +142,7 @@ attacker cannot control the start of the filename string you are opening. For instance, the following is sufficient to protect against accidentally starting a shell command with `|`: -``` +```ruby # we assume repo_path is not controlled by the attacker (user) path = File.join(repo_path, user_input) # path cannot start with '|' now. @@ -160,7 +160,7 @@ Path traversal is a security where the program (GitLab) tries to restrict user access to a certain directory on disk, but the user manages to open a file outside that directory by taking advantage of the `../` path notation. -``` +```ruby # Suppose the user gave us a path and they are trying to trick us user_input = '../other-repo.git/other-file' @@ -177,7 +177,7 @@ File.open(full_path) do # Oops! A good way to protect against this is to compare the full path with its 'absolute path' according to Ruby's `File.absolute_path`. -``` +```ruby full_path = File.join(repo_path, user_input) if full_path != File.absolute_path(full_path) raise "Invalid path: #{full_path.inspect}" diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md new file mode 100644 index 00000000000..62ac56a6bce --- /dev/null +++ b/doc/development/ux_guide/basics.md @@ -0,0 +1,94 @@ +# Basics + +## Contents +* [Responsive](#responsive) +* [Typography](#typography) +* [Icons](#icons) +* [Color](#color) +* [Motion](#motion) +* [Voice and tone](#voice-and-tone) + +--- + +## Responsive +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. GitLab uses the OS default font. +- **Menlo** (Mac) +- **Consolas** (Windows) +- **Liberation Mono** (Linux) + + + +--- + +## Icons +GitLab uses Font Awesome icons throughout our interface. + + +The trash icon is used for destructive actions that deletes information. + + +The pencil icon is used for editing content such as comments. + + +The bell icon is for notifications, such as Todos. + + +The eye icon is for subscribing to updates. For example, you can subscribe to a label and get updated on issues with that label. + + +The standard RSS icon is used for linking to RSS/atom feeds. + + +An 'x' is used for closing UI elements such as dropdowns. + + +A plus is used when creating new objects, such as issues, projects, etc. + +> TODO: update this section, add more general guidance to icon usage and personality, etc. + +--- + +## Color + + +Blue is used to highlight primary active elements (such as current tab), as well as other organization and managing commands. + + +Green is for actions that create new objects. + + +Orange is used for warnings + + +Red is reserved for delete and other destructive commands + + +Grey, and white (depending on context) is used for netral, secondary elements + +> TODO: Establish a perspective for color in terms of our personality and rationalize with Marketing usage. + +--- + +## Motion + +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. + +> TODO: Determine a more concrete perspective on motion, create consistent easing/timing curves to follow. + +--- + +## Voice and tone + +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. diff --git a/doc/development/ux_guide/components.md b/doc/development/ux_guide/components.md new file mode 100644 index 00000000000..764c3355714 --- /dev/null +++ b/doc/development/ux_guide/components.md @@ -0,0 +1,254 @@ +# Components + +## Contents +* [Tooltips](#tooltips) +* [Anchor links](#anchor-links) +* [Buttons](#buttons) +* [Dropdowns](#dropdowns) +* [Counts](#counts) +* [Lists](#lists) +* [Tables](#tables) +* [Blocks](#blocks) +* [Panels](#panels) +* [Alerts](#alerts) +* [Forms](#forms) +* [File holders](#file-holders) +* [Data formats](#data-formats) + +--- + +## Tooltips + +### Usage +A tooltip should only be added if additional information is required. + + + +### Placement +By default, tooltips should be placed below the element that they refer to. However, if there is not enough space in the viewpoint, the tooltip should be moved to the side as needed. + + + +--- + +## 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 + +An underline should always be added on hover. A gray link becomes blue 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 an stroke, and no background fill. + + + +### Icon and text treatment +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 +Follow the color guidance on the [basics](basics.md#color) page. The default color treatment is the white/grey button. + +--- + +## 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. +>>> + + + + + +--- + +## 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. + + + +[number_with_delimiter]: http://api.rubyonrails.org/classes/ActionView/Helpers/NumberHelper.html#method-i-number_with_delimiter + +--- + +## Lists + +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 a 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 .well-list + + + +List inside panel + + + +--- + +## Tables + +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 botton 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 +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. + + + +--- + +## Panels + +>>> +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. + + + +--- + +## File holders +A file holder (`.file-holder`) is used to show the contents of a file inline on a page of GitLab. + + + +--- + +## Data formats + +### Dates + +#### Exact + +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. + + + +#### `%` Milestones + + + +#### `#` Issues + + + +#### `!` Merge Requests + + + +#### `~` Labels + + + +#### `@` People + + + +> TODO: Open issue: Some commit references use monospace fonts, but others don't. Need to standardize this. diff --git a/doc/development/ux_guide/features.md b/doc/development/ux_guide/features.md new file mode 100644 index 00000000000..9472995c68c --- /dev/null +++ b/doc/development/ux_guide/features.md @@ -0,0 +1,57 @@ +# Features + +## Contents +* [Navigation](#navigation) +* [Filtering](#filtering) +* [Search results](#search-results) +* [Conversations](#conversations) +* [Empty states](#empty-states) + +--- + +## Navigation + +### Global navigation + +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. + +--- + +## 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. + + diff --git a/doc/development/ux_guide/img/button-primary.png b/doc/development/ux_guide/img/button-primary.png Binary files differnew file mode 100644 index 00000000000..f4c673f5b88 --- /dev/null +++ b/doc/development/ux_guide/img/button-primary.png diff --git a/doc/development/ux_guide/img/button-secondary.png b/doc/development/ux_guide/img/button-secondary.png Binary files differnew file mode 100644 index 00000000000..57fa65b247c --- /dev/null +++ b/doc/development/ux_guide/img/button-secondary.png diff --git a/doc/development/ux_guide/img/color-blue.png b/doc/development/ux_guide/img/color-blue.png Binary files differnew file mode 100644 index 00000000000..6449613eb16 --- /dev/null +++ b/doc/development/ux_guide/img/color-blue.png diff --git a/doc/development/ux_guide/img/color-green.png b/doc/development/ux_guide/img/color-green.png Binary files differnew file mode 100644 index 00000000000..15475b36f02 --- /dev/null +++ b/doc/development/ux_guide/img/color-green.png diff --git a/doc/development/ux_guide/img/color-grey.png b/doc/development/ux_guide/img/color-grey.png Binary files differnew file mode 100644 index 00000000000..58c474d5ce9 --- /dev/null +++ b/doc/development/ux_guide/img/color-grey.png diff --git a/doc/development/ux_guide/img/color-orange.png b/doc/development/ux_guide/img/color-orange.png Binary files differnew file mode 100644 index 00000000000..f4fc09b2d9b --- /dev/null +++ b/doc/development/ux_guide/img/color-orange.png diff --git a/doc/development/ux_guide/img/color-red.png b/doc/development/ux_guide/img/color-red.png Binary files differnew file mode 100644 index 00000000000..6fbbf0a885d --- /dev/null +++ b/doc/development/ux_guide/img/color-red.png diff --git a/doc/development/ux_guide/img/components-alerts.png b/doc/development/ux_guide/img/components-alerts.png Binary files differnew file mode 100644 index 00000000000..0b2ecc16a5f --- /dev/null +++ b/doc/development/ux_guide/img/components-alerts.png diff --git a/doc/development/ux_guide/img/components-anchorlinks.png b/doc/development/ux_guide/img/components-anchorlinks.png Binary files differnew file mode 100644 index 00000000000..950f348277d --- /dev/null +++ b/doc/development/ux_guide/img/components-anchorlinks.png diff --git a/doc/development/ux_guide/img/components-contentblock.png b/doc/development/ux_guide/img/components-contentblock.png Binary files differnew file mode 100644 index 00000000000..31fc1eec9df --- /dev/null +++ b/doc/development/ux_guide/img/components-contentblock.png diff --git a/doc/development/ux_guide/img/components-counts.png b/doc/development/ux_guide/img/components-counts.png Binary files differnew file mode 100644 index 00000000000..19280e988a0 --- /dev/null +++ b/doc/development/ux_guide/img/components-counts.png diff --git a/doc/development/ux_guide/img/components-coverblock.png b/doc/development/ux_guide/img/components-coverblock.png Binary files differnew file mode 100644 index 00000000000..c8f1f87a108 --- /dev/null +++ b/doc/development/ux_guide/img/components-coverblock.png diff --git a/doc/development/ux_guide/img/components-dateexact.png b/doc/development/ux_guide/img/components-dateexact.png Binary files differnew file mode 100644 index 00000000000..8c0c5c1be40 --- /dev/null +++ b/doc/development/ux_guide/img/components-dateexact.png diff --git a/doc/development/ux_guide/img/components-daterelative.png b/doc/development/ux_guide/img/components-daterelative.png Binary files differnew file mode 100644 index 00000000000..1dc6d89e4ef --- /dev/null +++ b/doc/development/ux_guide/img/components-daterelative.png diff --git a/doc/development/ux_guide/img/components-dropdown.png b/doc/development/ux_guide/img/components-dropdown.png Binary files differnew file mode 100644 index 00000000000..5770a393b37 --- /dev/null +++ b/doc/development/ux_guide/img/components-dropdown.png diff --git a/doc/development/ux_guide/img/components-fileholder.png b/doc/development/ux_guide/img/components-fileholder.png Binary files differnew file mode 100644 index 00000000000..4b8962905d6 --- /dev/null +++ b/doc/development/ux_guide/img/components-fileholder.png diff --git a/doc/development/ux_guide/img/components-horizontalform.png b/doc/development/ux_guide/img/components-horizontalform.png Binary files differnew file mode 100644 index 00000000000..92e28cf9afc --- /dev/null +++ b/doc/development/ux_guide/img/components-horizontalform.png diff --git a/doc/development/ux_guide/img/components-listinsidepanel.png b/doc/development/ux_guide/img/components-listinsidepanel.png Binary files differnew file mode 100644 index 00000000000..30ceb3eaa08 --- /dev/null +++ b/doc/development/ux_guide/img/components-listinsidepanel.png diff --git a/doc/development/ux_guide/img/components-listwithavatar.png b/doc/development/ux_guide/img/components-listwithavatar.png Binary files differnew file mode 100644 index 00000000000..d3cb0ebc02b --- /dev/null +++ b/doc/development/ux_guide/img/components-listwithavatar.png diff --git a/doc/development/ux_guide/img/components-listwithhover.png b/doc/development/ux_guide/img/components-listwithhover.png Binary files differnew file mode 100644 index 00000000000..1484ecba6a0 --- /dev/null +++ b/doc/development/ux_guide/img/components-listwithhover.png diff --git a/doc/development/ux_guide/img/components-panels.png b/doc/development/ux_guide/img/components-panels.png Binary files differnew file mode 100644 index 00000000000..6e71d0ad9c9 --- /dev/null +++ b/doc/development/ux_guide/img/components-panels.png diff --git a/doc/development/ux_guide/img/components-referencehover.png b/doc/development/ux_guide/img/components-referencehover.png Binary files differnew file mode 100644 index 00000000000..e9fb27e2aa9 --- /dev/null +++ b/doc/development/ux_guide/img/components-referencehover.png diff --git a/doc/development/ux_guide/img/components-referenceissues.png b/doc/development/ux_guide/img/components-referenceissues.png Binary files differnew file mode 100644 index 00000000000..caf9477db38 --- /dev/null +++ b/doc/development/ux_guide/img/components-referenceissues.png diff --git a/doc/development/ux_guide/img/components-referencelabels.png b/doc/development/ux_guide/img/components-referencelabels.png Binary files differnew file mode 100644 index 00000000000..a122b45d1f1 --- /dev/null +++ b/doc/development/ux_guide/img/components-referencelabels.png diff --git a/doc/development/ux_guide/img/components-referencemilestone.png b/doc/development/ux_guide/img/components-referencemilestone.png Binary files differnew file mode 100644 index 00000000000..5aa9ecd1a78 --- /dev/null +++ b/doc/development/ux_guide/img/components-referencemilestone.png diff --git a/doc/development/ux_guide/img/components-referencemrs.png b/doc/development/ux_guide/img/components-referencemrs.png Binary files differnew file mode 100644 index 00000000000..6280243859a --- /dev/null +++ b/doc/development/ux_guide/img/components-referencemrs.png diff --git a/doc/development/ux_guide/img/components-referencepeople.png b/doc/development/ux_guide/img/components-referencepeople.png Binary files differnew file mode 100644 index 00000000000..99772a539cf --- /dev/null +++ b/doc/development/ux_guide/img/components-referencepeople.png diff --git a/doc/development/ux_guide/img/components-rowcontentblock.png b/doc/development/ux_guide/img/components-rowcontentblock.png Binary files differnew file mode 100644 index 00000000000..1c2d7096955 --- /dev/null +++ b/doc/development/ux_guide/img/components-rowcontentblock.png diff --git a/doc/development/ux_guide/img/components-simplelist.png b/doc/development/ux_guide/img/components-simplelist.png Binary files differnew file mode 100644 index 00000000000..892f507cfc2 --- /dev/null +++ b/doc/development/ux_guide/img/components-simplelist.png diff --git a/doc/development/ux_guide/img/components-table.png b/doc/development/ux_guide/img/components-table.png Binary files differnew file mode 100644 index 00000000000..7e964c885cf --- /dev/null +++ b/doc/development/ux_guide/img/components-table.png diff --git a/doc/development/ux_guide/img/components-verticalform.png b/doc/development/ux_guide/img/components-verticalform.png Binary files differnew file mode 100644 index 00000000000..38863ad3c1c --- /dev/null +++ b/doc/development/ux_guide/img/components-verticalform.png diff --git a/doc/development/ux_guide/img/features-contextualnav.png b/doc/development/ux_guide/img/features-contextualnav.png Binary files differnew file mode 100644 index 00000000000..df157f54c84 --- /dev/null +++ b/doc/development/ux_guide/img/features-contextualnav.png diff --git a/doc/development/ux_guide/img/features-emptystates.png b/doc/development/ux_guide/img/features-emptystates.png Binary files differnew file mode 100644 index 00000000000..3befc14588e --- /dev/null +++ b/doc/development/ux_guide/img/features-emptystates.png diff --git a/doc/development/ux_guide/img/features-filters.png b/doc/development/ux_guide/img/features-filters.png Binary files differnew file mode 100644 index 00000000000..281e55d590c --- /dev/null +++ b/doc/development/ux_guide/img/features-filters.png diff --git a/doc/development/ux_guide/img/features-globalnav.png b/doc/development/ux_guide/img/features-globalnav.png Binary files differnew file mode 100644 index 00000000000..3c0db2247ca --- /dev/null +++ b/doc/development/ux_guide/img/features-globalnav.png diff --git a/doc/development/ux_guide/img/icon-add.png b/doc/development/ux_guide/img/icon-add.png Binary files differnew file mode 100644 index 00000000000..0d4c1a7692a --- /dev/null +++ b/doc/development/ux_guide/img/icon-add.png diff --git a/doc/development/ux_guide/img/icon-close.png b/doc/development/ux_guide/img/icon-close.png Binary files differnew file mode 100644 index 00000000000..88d2b3b0c6d --- /dev/null +++ b/doc/development/ux_guide/img/icon-close.png diff --git a/doc/development/ux_guide/img/icon-edit.png b/doc/development/ux_guide/img/icon-edit.png Binary files differnew file mode 100644 index 00000000000..f73be7a10fb --- /dev/null +++ b/doc/development/ux_guide/img/icon-edit.png diff --git a/doc/development/ux_guide/img/icon-notification.png b/doc/development/ux_guide/img/icon-notification.png Binary files differnew file mode 100644 index 00000000000..4758632edd7 --- /dev/null +++ b/doc/development/ux_guide/img/icon-notification.png diff --git a/doc/development/ux_guide/img/icon-rss.png b/doc/development/ux_guide/img/icon-rss.png Binary files differnew file mode 100644 index 00000000000..c7ac9fb1349 --- /dev/null +++ b/doc/development/ux_guide/img/icon-rss.png diff --git a/doc/development/ux_guide/img/icon-subscribe.png b/doc/development/ux_guide/img/icon-subscribe.png Binary files differnew file mode 100644 index 00000000000..5cb277bfd5d --- /dev/null +++ b/doc/development/ux_guide/img/icon-subscribe.png diff --git a/doc/development/ux_guide/img/icon-trash.png b/doc/development/ux_guide/img/icon-trash.png Binary files differnew file mode 100644 index 00000000000..357289a6fff --- /dev/null +++ b/doc/development/ux_guide/img/icon-trash.png diff --git a/doc/development/ux_guide/img/monospacefont-sample.png b/doc/development/ux_guide/img/monospacefont-sample.png Binary files differnew file mode 100644 index 00000000000..1cd290b713c --- /dev/null +++ b/doc/development/ux_guide/img/monospacefont-sample.png diff --git a/doc/development/ux_guide/img/sourcesanspro-sample.png b/doc/development/ux_guide/img/sourcesanspro-sample.png Binary files differnew file mode 100644 index 00000000000..f7ecf0c7c66 --- /dev/null +++ b/doc/development/ux_guide/img/sourcesanspro-sample.png diff --git a/doc/development/ux_guide/img/surfaces-contentitemtitle.png b/doc/development/ux_guide/img/surfaces-contentitemtitle.png Binary files differnew file mode 100644 index 00000000000..2eb926c1c43 --- /dev/null +++ b/doc/development/ux_guide/img/surfaces-contentitemtitle.png diff --git a/doc/development/ux_guide/img/surfaces-header.png b/doc/development/ux_guide/img/surfaces-header.png Binary files differnew file mode 100644 index 00000000000..ab44d4de696 --- /dev/null +++ b/doc/development/ux_guide/img/surfaces-header.png diff --git a/doc/development/ux_guide/img/surfaces-systeminformationblock.png b/doc/development/ux_guide/img/surfaces-systeminformationblock.png Binary files differnew file mode 100644 index 00000000000..5d91e993e24 --- /dev/null +++ b/doc/development/ux_guide/img/surfaces-systeminformationblock.png diff --git a/doc/development/ux_guide/img/surfaces-ux.png b/doc/development/ux_guide/img/surfaces-ux.png Binary files differnew file mode 100644 index 00000000000..e692c51e8c0 --- /dev/null +++ b/doc/development/ux_guide/img/surfaces-ux.png diff --git a/doc/development/ux_guide/img/tooltip-placement.png b/doc/development/ux_guide/img/tooltip-placement.png Binary files differnew file mode 100644 index 00000000000..29a61c8400a --- /dev/null +++ b/doc/development/ux_guide/img/tooltip-placement.png diff --git a/doc/development/ux_guide/img/tooltip-usage.png b/doc/development/ux_guide/img/tooltip-usage.png Binary files differnew file mode 100644 index 00000000000..e8e4c6ded91 --- /dev/null +++ b/doc/development/ux_guide/img/tooltip-usage.png diff --git a/doc/development/ux_guide/index.md b/doc/development/ux_guide/index.md new file mode 100644 index 00000000000..1a61be4ed51 --- /dev/null +++ b/doc/development/ux_guide/index.md @@ -0,0 +1,53 @@ +# 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, color, and motion. + +--- + +### [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. + +--- + +### [Resources](resources.md) +Resources for GitLab UX diff --git a/doc/development/ux_guide/principles.md b/doc/development/ux_guide/principles.md new file mode 100644 index 00000000000..1a297cba2cc --- /dev/null +++ b/doc/development/ux_guide/principles.md @@ -0,0 +1,17 @@ +# Principles + +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 diff --git a/doc/development/ux_guide/resources.md b/doc/development/ux_guide/resources.md new file mode 100644 index 00000000000..2f760c94414 --- /dev/null +++ b/doc/development/ux_guide/resources.md @@ -0,0 +1,13 @@ +# Resources + +## GitLab UI development kit + +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.
\ No newline at end of file diff --git a/doc/development/ux_guide/surfaces.md b/doc/development/ux_guide/surfaces.md new file mode 100644 index 00000000000..881d6aa4cd6 --- /dev/null +++ b/doc/development/ux_guide/surfaces.md @@ -0,0 +1,47 @@ +# Surfaces + +## Contents +* [Header](#header) +* [Global menu](#global-menu) +* [Side pane](#side-pane) +* [Content area](#content-area) + +--- + + + +## Global menu + +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. + +--- + +## 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. + + diff --git a/doc/development/ux_guide/tips.md b/doc/development/ux_guide/tips.md new file mode 100644 index 00000000000..8348de4f8a2 --- /dev/null +++ b/doc/development/ux_guide/tips.md @@ -0,0 +1,44 @@ +# Tips + +## Contents +* [SVGs](#svgs) + +--- + +## SVGs + +When exporting SVGs, be sure to follow the following guidelines: + +1. Convert all strokes to outlines. +2. Use pathfinder tools to combine overlapping paths and create compound paths. +3. SVGs that are limited to one color should be exported without a fill color so the color can be set using CSS. +4. 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. +Incorrect files will look like this: + +```xml +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg width="16px" height="17px" viewBox="0 0 16 17" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <!-- Generator: Sketch 3.7.2 (28276) - http://www.bohemiancoding.com/sketch --> + <title>Group</title> + <desc>Created with Sketch.</desc> + <defs></defs> + <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd"> + <g id="Group" fill="#7E7C7C"> + <path d="M15.1111,1 L0.8891,1 C0.3981,1 0.0001,1.446 0.0001,1.996 L0.0001,15.945 C0.0001,16.495 0.3981,16.941 0.8891,16.941 L15.1111,16.941 C15.6021,16.941 16.0001,16.495 16.0001,15.945 L16.0001,1.996 C16.0001,1.446 15.6021,1 15.1111,1 L15.1111,1 L15.1111,1 Z M14.0001,6.0002 L14.0001,14.949 L2.0001,14.949 L2.0001,6.0002 L14.0001,6.0002 Z M14.0001,4.0002 L14.0001,2.993 L2.0001,2.993 L2.0001,4.0002 L14.0001,4.0002 Z" id="Combined-Shape"></path> + <polygon id="Fill-11" points="3 2.0002 5 2.0002 5 0.0002 3 0.0002"></polygon> + <polygon id="Fill-16" points="11 2.0002 13 2.0002 13 0.0002 11 0.0002"></polygon> + <path d="M5.37709616,11.5511984 L6.92309616,12.7821984 C7.35112915,13.123019 7.97359761,13.0565604 8.32002627,12.6330535 L10.7740263,9.63305349 C11.1237073,9.20557058 11.0606364,8.57555475 10.6331535,8.22587373 C10.2056706,7.87619272 9.57565475,7.93926361 9.22597373,8.36674651 L6.77197373,11.3667465 L8.16890384,11.2176016 L6.62290384,9.98660159 C6.19085236,9.6425813 5.56172188,9.71394467 5.21770159,10.1459962 C4.8736813,10.5780476 4.94504467,11.2071781 5.37709616,11.5511984 L5.37709616,11.5511984 Z" id="Stroke-21"></path> + </g> + </g> +</svg> +``` + +Correct file will look like this: + +```xml +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17" enable-background="new 0 0 16 17"><path d="m15.1 1h-2.1v-1h-2v1h-6v-1h-2v1h-2.1c-.5 0-.9.5-.9 1v14c0 .6.4 1 .9 1h14.2c.5 0 .9-.4.9-1v-14c0-.5-.4-1-.9-1m-1.1 14h-12v-9h12v9m0-11h-12v-1h12v1"/><path d="m5.4 11.6l1.5 1.2c.4.3 1.1.3 1.4-.1l2.5-3c.3-.4.3-1.1-.1-1.4-.5-.4-1.1-.3-1.5.1l-1.8 2.2-.8-.6c-.4-.3-1.1-.3-1.4.2-.3.4-.3 1 .2 1.4"/></svg> +``` + +> TODO: Checkout [https://github.com/svg/svgo](https://github.com/svg/svgo) diff --git a/doc/development/ux_guide/users.md b/doc/development/ux_guide/users.md new file mode 100644 index 00000000000..717a902c424 --- /dev/null +++ b/doc/development/ux_guide/users.md @@ -0,0 +1,16 @@ +# Users + +> TODO: Create personas. Understand the similarities and differences across the below spectrums. + +## Users by organization + +- Enterprise +- Medium company +- Small company +- Open source communities + +## Users by role + +- Admin +- Manager +- Developer diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index 2574c2c0472..bbcd26477f3 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -66,6 +66,12 @@ producing errors whenever it tries to use the `dummy` column. As a result of the above downtime _is_ required when removing a column, even when using PostgreSQL. +## Renaming Columns + +Renaming columns requires downtime as running GitLab instances will continue +using the old column name until a new version is deployed. This can result +in the instance producing errors, which in turn can impact the user experience. + ## Changing Column Constraints Generally changing column constraints requires checking all rows in the table to diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 3f45a631b3a..1c549844ee1 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -14,8 +14,8 @@ There are two ways to create a new project in GitLab. 1. Fill out the information: - 1. "Project name" is the name of your project (you can't use spaces, but you - can use hyphens or underscores). + 1. "Project name" is the name of your project (you can't use special characters, + but you can use spaces, hyphens, underscores or even emojis). 1. The "Project description" is optional and will be shown in your project's dashboard so others can briefly understand what your project is about. 1. Select a [visibility level](../public_access/public_access.md). diff --git a/doc/integration/README.md b/doc/integration/README.md index a928b74f9b8..ae4387e2577 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -5,7 +5,7 @@ trackers and external authentication. See the documentation below for details on how to configure these services. -- [JIRA](jira.md) Integrate with the JIRA issue tracker +- [Jira](../project_services/jira.md) Integrate with the JIRA issue tracker - [External issue tracker](external-issue-tracker.md) Redmine, JIRA, etc. - [LDAP](ldap.md) Set up sign in via LDAP - [OmniAuth](omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, Bitbucket, Facebook, Shibboleth, SAML, Crowd and Azure @@ -44,11 +44,15 @@ This [resource](http://kb.kerio.com/product/kerio-connect/server-configuration/s has all the information you need to add a certificate to the main trusted chain. This [answer](http://superuser.com/questions/437330/how-do-you-add-a-certificate-authority-ca-to-ubuntu) -at SuperUser also has relevant information. +at Super User also has relevant information. **Omnibus Trusted Chain** -It is enough to concatenate the certificate to the main trusted certificate: +[Install the self signed certificate or custom certificate authorities](http://docs.gitlab.com/omnibus/common_installation_problems/README.html#using-self-signed-certificate-or-custom-certificate-authorities) +in to GitLab Omnibus. + +It is enough to concatenate the certificate to the main trusted certificate +however it may be overwritten during upgrades: ```bash cat jira.pem >> /opt/gitlab/embedded/ssl/certs/cacert.pem diff --git a/doc/integration/jira.md b/doc/integration/jira.md index 2e31fd994de..78aa6634116 100644 --- a/doc/integration/jira.md +++ b/doc/integration/jira.md @@ -1,197 +1,3 @@ # GitLab JIRA integration -GitLab can be configured to interact with JIRA. Configuration happens via -user name and password. Connecting to a JIRA server via CAS is not possible. - -Each project can be configured to connect to a different JIRA instance, see the -[configuration](#configuration) section. If you have one JIRA instance you can -pre-fill the settings page with a default template. To configure the template -see the [Services Templates][services-templates] document. - -Once the project is connected to JIRA, you can reference and close the issues -in JIRA directly from GitLab. - -## Table of Contents -* [Referencing JIRA Issues from GitLab](#referencing-JIRA-issues) -* [Closing JIRA Issues from GitLab](#closing-JIRA-issues) -* [Configuration](#configuration) - -### Referencing JIRA Issues - -When GitLab project has JIRA issue tracker configured and enabled, mentioning -JIRA issue in GitLab will automatically add a comment in JIRA issue with the -link back to GitLab. This means that in comments in merge requests and commits -referencing an issue, eg. `PROJECT-7`, will add a comment in JIRA issue in the -format: - -``` - USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: - ENTITY_TITLE -``` - -* `USER` A user that mentioned the issue. This is the link to the user profile in GitLab. -* `LINK_TO_THE_COMMENT` Link to the origin of mention with a name of the entity where JIRA issue was mentioned. -* `RESOURCE_NAME` Kind of resource which referenced the issue. Can be a commit or merge request. -* `PROJECT_NAME` GitLab project name. -* `ENTITY_TITLE` Merge request title or commit message first line. - - - ---- - -### Closing JIRA Issues - -JIRA issues can be closed directly from GitLab by using trigger words, eg. -`Resolves PROJECT-1`, `Closes PROJECT-1` or `Fixes PROJECT-1`, in commits and -merge requests. When a commit which contains the trigger word in the commit -message is pushed, GitLab will add a comment in the mentioned JIRA issue. - -For example, for project named `PROJECT` in JIRA, we implemented a new feature -and created a merge request in GitLab. - -This feature was requested in JIRA issue `PROJECT-7`. Merge request in GitLab -contains the improvement and in merge request description we say that this -merge request `Closes PROJECT-7` issue. - -Once this merge request is merged, the JIRA issue will be automatically closed -with a link to the commit that resolved the issue. - - - ---- - - - ---- - -## Configuration - -### Configuring JIRA - -We need to create a user in JIRA which will have access to all projects that -need to integrate with GitLab. Login to your JIRA instance as admin and under -Administration go to User Management and create a new user. - -As an example, we'll create a user named `gitlab` and add it to `JIRA-developers` -group. - -**It is important that the user `GitLab` has write-access to projects in JIRA** - -We have split this stage in steps so it is easier to follow. - ---- - -1. Login to your JIRA instance as an administrator and under **Administration** - go to **User Management** to create a new user. - -  - - --- - -1. The next step is to create a new user (e.g., `gitlab`) who has write access - to projects in JIRA. Enter the user's name and a _valid_ e-mail address - since JIRA sends a verification e-mail to set-up the password. - _**Note:** JIRA creates the username automatically by using the e-mail - prefix. You can change it later if you want._ - -  - - --- - -1. Now, let's create a `gitlab-developers` group which will have write access - to projects in JIRA. Go to the **Groups** tab and select **Create group**. - -  - - --- - - Give it an optional description and hit **Create group**. - -  - - --- - -1. Give the newly-created group write access by going to - **Application access > View configuration** and adding the `gitlab-developers` - group to JIRA Core. - -  - - --- - -1. Add the `gitlab` user to the `gitlab-developers` group by going to - **Users > GitLab user > Add group** and selecting the `gitlab-developers` - group from the dropdown menu. Notice that the group says _Access_ which is - what we aim for. - -  - ---- - -The JIRA configuration is over. Write down the new JIRA username and its -password as they will be needed when configuring GitLab in the next section. - -### Configuring GitLab - -JIRA configuration in GitLab is done via a project's **Services**. - -#### GitLab 8.13.0 with JIRA v1000.x - -To enable JIRA integration in a project, navigate to the project's -and open the context menu clicking on the top right gear icon, then go to -**Services > JIRA**. - -Fill in the required details on the page as described in the table below. - -| Field | Description | -| ----- | ----------- | -| `URL` | The base URL to the JIRA project which is being linked to this GitLab project. Ex. https://JIRA.example.com | -| `Project key` | The short, all capital letter identifier for your JIRA project. | -| `Username` | The user name created in [configuring JIRA step](#configuring-JIRA). | -| `Password` |The password of the user created in [configuring JIRA step](#configuring-JIRA). | -| `JIRA issue transition` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). | - -After saving the configuration, your GitLab project will be able to interact -with the linked JIRA project. - - - ---- - -#### GitLab 6.x-7.7 with JIRA v6.x - -_**Note:** GitLab versions 8.13.0 and up contain various integration improvements. -We strongly recommend upgrading._ - -In `gitlab.yml` enable the JIRA issue tracker section by -[uncommenting these lines][JIRA-gitlab-yml]. This will make sure that all -issues within GitLab are pointing to the JIRA issue tracker. - -After you set this, you will be able to close issues in JIRA by a commit in -GitLab. - -Go to your project's **Settings** page and fill in the project name for the -JIRA project: - - - ---- - -You can also enable the JIRA service that will allow you to interact with JIRA -issues. Go to the **Settings > Services > JIRA** and: - -1. Tick the active check box to enable the service -1. Supply the URL to JIRA server, for example http://JIRA.example.com -1. Supply the username of a user we created under `Configuring JIRA` section, - for example `gitlab` -1. Supply the password of the user -1. Optional: supply the JIRA API version, default is version `2` -1. Optional: supply the JIRA issue transition ID (issue transition to closed). - This is dependent on JIRA settings, default is `2` -1. Hit save - - - - -[services-templates]: ../project_services/services_templates.md -[JIRA-gitlab-yml]: https://gitlab.com/subscribers/gitlab-ee/blob/6-8-stable-ee/config/gitlab.yml.example#L111-115 +This document was moved under [project_services/jira](../project_services/jira.md). diff --git a/doc/integration/shibboleth.md b/doc/integration/shibboleth.md index 5210ce0de9a..eb9bbb67e7d 100644 --- a/doc/integration/shibboleth.md +++ b/doc/integration/shibboleth.md @@ -10,7 +10,7 @@ To enable the Shibboleth OmniAuth provider you must: 1. Configure Apache shibboleth module. Installation and configuration of module it self is out of scope of this document. Check https://wiki.shibboleth.net/ for more info. -1. You can find Apache config in gitlab-recipes (https://github.com/gitlabhq/gitlab-recipes/blob/master/web-server/apache/gitlab-ssl.conf) +1. You can find Apache config in gitlab-recipes (https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache) Following changes are needed to enable shibboleth: diff --git a/doc/project_services/img/builds_emails_service.png b/doc/project_services/img/builds_emails_service.png Binary files differindex 440728795be..88943dc410e 100644 --- a/doc/project_services/img/builds_emails_service.png +++ b/doc/project_services/img/builds_emails_service.png diff --git a/doc/project_services/img/jira_add_gitlab_commit_message.png b/doc/project_services/img/jira_add_gitlab_commit_message.png Binary files differnew file mode 100644 index 00000000000..aec472b9118 --- /dev/null +++ b/doc/project_services/img/jira_add_gitlab_commit_message.png diff --git a/doc/project_services/img/jira_add_user_to_group.png b/doc/project_services/img/jira_add_user_to_group.png Binary files differnew file mode 100644 index 00000000000..0ba737bda9a --- /dev/null +++ b/doc/project_services/img/jira_add_user_to_group.png diff --git a/doc/project_services/img/jira_create_new_group.png b/doc/project_services/img/jira_create_new_group.png Binary files differnew file mode 100644 index 00000000000..0609060cb05 --- /dev/null +++ b/doc/project_services/img/jira_create_new_group.png diff --git a/doc/project_services/img/jira_create_new_group_name.png b/doc/project_services/img/jira_create_new_group_name.png Binary files differnew file mode 100644 index 00000000000..53d77b17df0 --- /dev/null +++ b/doc/project_services/img/jira_create_new_group_name.png diff --git a/doc/project_services/img/jira_create_new_user.png b/doc/project_services/img/jira_create_new_user.png Binary files differnew file mode 100644 index 00000000000..9eaa444ed25 --- /dev/null +++ b/doc/project_services/img/jira_create_new_user.png diff --git a/doc/project_services/img/jira_group_access.png b/doc/project_services/img/jira_group_access.png Binary files differnew file mode 100644 index 00000000000..8d4657427ae --- /dev/null +++ b/doc/project_services/img/jira_group_access.png diff --git a/doc/project_services/img/jira_issue_closed.png b/doc/project_services/img/jira_issue_closed.png Binary files differnew file mode 100644 index 00000000000..acdd83702d3 --- /dev/null +++ b/doc/project_services/img/jira_issue_closed.png diff --git a/doc/project_services/img/jira_issue_reference.png b/doc/project_services/img/jira_issue_reference.png Binary files differnew file mode 100644 index 00000000000..1a2d9f04a6c --- /dev/null +++ b/doc/project_services/img/jira_issue_reference.png diff --git a/doc/project_services/img/jira_issues_workflow.png b/doc/project_services/img/jira_issues_workflow.png Binary files differnew file mode 100644 index 00000000000..0703081d77b --- /dev/null +++ b/doc/project_services/img/jira_issues_workflow.png diff --git a/doc/project_services/img/jira_merge_request_close.png b/doc/project_services/img/jira_merge_request_close.png Binary files differnew file mode 100644 index 00000000000..47785e3ba27 --- /dev/null +++ b/doc/project_services/img/jira_merge_request_close.png diff --git a/doc/project_services/img/jira_project_name.png b/doc/project_services/img/jira_project_name.png Binary files differnew file mode 100644 index 00000000000..e785ec6140d --- /dev/null +++ b/doc/project_services/img/jira_project_name.png diff --git a/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png b/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png Binary files differnew file mode 100644 index 00000000000..fb270d85e3c --- /dev/null +++ b/doc/project_services/img/jira_reference_commit_message_in_jira_issue.png diff --git a/doc/project_services/img/jira_service.png b/doc/project_services/img/jira_service.png Binary files differnew file mode 100644 index 00000000000..13aefce6f84 --- /dev/null +++ b/doc/project_services/img/jira_service.png diff --git a/doc/project_services/img/jira_service_close_issue.png b/doc/project_services/img/jira_service_close_issue.png Binary files differnew file mode 100644 index 00000000000..eed69e80d2c --- /dev/null +++ b/doc/project_services/img/jira_service_close_issue.png diff --git a/doc/project_services/img/jira_service_page.png b/doc/project_services/img/jira_service_page.png Binary files differnew file mode 100644 index 00000000000..a5b49c501ba --- /dev/null +++ b/doc/project_services/img/jira_service_page.png diff --git a/doc/project_services/img/jira_submit_gitlab_merge_request.png b/doc/project_services/img/jira_submit_gitlab_merge_request.png Binary files differnew file mode 100644 index 00000000000..77630d39d39 --- /dev/null +++ b/doc/project_services/img/jira_submit_gitlab_merge_request.png diff --git a/doc/project_services/img/jira_user_management_link.png b/doc/project_services/img/jira_user_management_link.png Binary files differnew file mode 100644 index 00000000000..5f002b59bac --- /dev/null +++ b/doc/project_services/img/jira_user_management_link.png diff --git a/doc/project_services/img/jira_workflow_screenshot.png b/doc/project_services/img/jira_workflow_screenshot.png Binary files differnew file mode 100644 index 00000000000..937a50a77d9 --- /dev/null +++ b/doc/project_services/img/jira_workflow_screenshot.png diff --git a/doc/project_services/jira.md b/doc/project_services/jira.md index 2ea1c58cb31..b626c746c79 100644 --- a/doc/project_services/jira.md +++ b/doc/project_services/jira.md @@ -1 +1,246 @@ -GitLab JIRA integration documentation has moved to [here](../integration/jira.md). +# GitLab JIRA integration + +>**Note:** +Full JIRA integration was previously exclusive to GitLab Enterprise Edition. +With [GitLab 8.3 forward][8_3_post], this feature in now [backported][jira-ce] +to GitLab Community Edition as well. + +--- + +GitLab can be configured to interact with [JIRA Core] either using an +on-premises instance or the SaaS solution that Atlassian offers. Configuration +happens via username and password on a per-project basis. Connecting to a JIRA +server via CAS is not possible. + +Each project can be configured to connect to a different JIRA instance or, in +case you have a single JIRA instance, you can pre-fill the JIRA service +settings page in GitLab with a default template. To configure the JIRA template, +see the [Services Templates documentation][services-templates]. + +Once the GitLab project is connected to JIRA, you can reference and close the +issues in JIRA directly from GitLab's merge requests. + +## Configuration + +The configuration consists of two parts: + +- [JIRA configuration](#configuring-jira) +- [GitLab configuration](#configuring-gitlab) + +### Configuring JIRA + +First things first, we need to create a user in JIRA which will have access to +all projects that need to integrate with GitLab. + +We have split this stage in steps so it is easier to follow. + +--- + +1. Login to your JIRA instance as an administrator and under **Administration** + go to **User Management** to create a new user. + +  + + --- + +1. The next step is to create a new user (e.g., `gitlab`) who has write access + to projects in JIRA. Enter the user's name and a _valid_ e-mail address + since JIRA sends a verification e-mail to set-up the password. + _**Note:** JIRA creates the username automatically by using the e-mail + prefix. You can change it later if you want._ + +  + + --- + +1. Now, let's create a `gitlab-developers` group which will have write access + to projects in JIRA. Go to the **Groups** tab and select **Create group**. + +  + + --- + + Give it an optional description and hit **Create group**. + +  + + --- + +1. Give the newly-created group write access by going to + **Application access > View configuration** and adding the `gitlab-developers` + group to JIRA Core. + +  + + --- + +1. Add the `gitlab` user to the `gitlab-developers` group by going to + **Users > GitLab user > Add group** and selecting the `gitlab-developers` + group from the dropdown menu. Notice that the group says _Access_ which is + what we aim for. + +  + +--- + +The JIRA configuration is over. Write down the new JIRA username and its +password as they will be needed when configuring GitLab in the next section. + +### Configuring GitLab + +>**Note:** +The currently supported JIRA versions are v6.x and v7.x. and GitLab +7.8 or higher is required. + +--- + +Assuming you [have already configured JIRA](#configuring-jira), now it's time +to configure GitLab. + +JIRA configuration in GitLab is done via a project's +[**Services**](../project_services/project_services.md). + +To enable JIRA integration in a project, navigate to the project's +**Settings > Services > JIRA**. + +Fill in the required details on the page, as described in the table below. + +| Setting | Description | +| ------- | ----------- | +| `Description` | A name for the issue tracker (to differentiate between instances, for example). | +| `Project url` | The URL to the JIRA project which is being linked to this GitLab project. It is of the form: `https://<jira_host_url>/issues/?jql=project=<jira_project>`. | +| `Issues url` | The URL to the JIRA project issues overview for the project that is linked to this GitLab project. It is of the form: `https://<jira_host_url>/browse/:id`. Leave `:id` as-is, it gets replaced by GitLab at runtime. | +| `New issue url` | This is the URL to create a new issue in JIRA for the project linked to this GitLab project, and it is of the form: `https://<jira_host_url>/secure/CreateIssue.jspa` | +| `Api url` | The base URL of the JIRA API. It may be omitted, in which case GitLab will automatically use API version `2` based on the `project url`. It is of the form: `https://<jira_host_url>/rest/api/2`. | +| `Username` | The username of the user created in [configuring JIRA step](#configuring-jira). | +| `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | +| `JIRA issue transition` | This setting is very important to set up correctly. It is the ID of a transition that moves issues to a closed state. You can find this number under the JIRA workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column ([see screenshot][trans]). By default, this ID is set to `2`. | + +After saving the configuration, your GitLab project will be able to interact +with the linked JIRA project. + +For example, given the settings below: + +- the JIRA URL is `https://jira.example.com` +- the project is named `GITLAB` +- the user is named `gitlab` +- the JIRA issue transition is 151 (based on the [JIRA issue transition][trans]) + +the following screenshot shows how the JIRA service settings should look like. + + + +[trans]: img/jira_issues_workflow.png + +--- + +## JIRA issues + +By now you should have [configured JIRA](#configuring-jira) and enabled the +[JIRA service in GitLab](#configuring-gitlab). If everything is set up correctly +you should be able to reference and close JIRA issues by just mentioning their +ID in GitLab commits and merge requests. + +### Referencing JIRA Issues + +If you reference a JIRA issue, e.g., `GITLAB-1`, in a commit comment, a link +which points back to JIRA is created. + +The same works for comments in merge requests as well. + + + +--- + +The mentioning action is two-fold, so a comment with a JIRA issue in GitLab +will automatically add a comment in that particular JIRA issue with the link +back to GitLab. + + + + +--- + +The comment on the JIRA issue is of the form: + +> USER mentioned this issue in LINK_TO_THE_MENTION + +Where: + +| Format | Description | +| ------ | ----------- | +| `USER` | A user that mentioned the issue. This is the link to the user profile in GitLab. | +| `LINK_TO_THE_MENTION` | Link to the origin of mention with a name of the entity where JIRA issue was mentioned. Can be commit or merge request. | + +### Closing JIRA issues + +JIRA issues can be closed directly from GitLab by using trigger words in +commits and merge requests. When a commit which contains the trigger word +followed by the JIRA issue ID in the commit message is pushed, GitLab will +add a comment in the mentioned JIRA issue and immediately close it (provided +the transition ID was set up correctly). + +There are currently three trigger words, and you can use either one to achieve +the same goal: + +- `Resolves GITLAB-1` +- `Closes GITLAB-1` +- `Fixes GITLAB-1` + +where `GITLAB-1` the issue ID of the JIRA project. + +### JIRA issue closing example + +Let's say for example that we submitted a bug fix and created a merge request +in GitLab. The workflow would be something like this: + +1. Create a new branch +1. Fix the bug +1. Commit the changes and push branch to GitLab +1. Open a new merge request and reference the JIRA issue including one of the + trigger words, e.g.: `Fixes GITLAB-1`, in the description +1. Submit the merge request +1. Ask someone to review +1. Merge the merge request +1. The JIRA issue is automatically closed + +--- + +In the following screenshot you can see what the link references to the JIRA +issue look like. + + + +--- + +Once this merge request is merged, the JIRA issue will be automatically closed +with a link to the commit that resolved the issue. + + + +--- + +You can see from the above image that there are four references to GitLab: + +- The first is from a comment in a specific commit +- The second is from the JIRA issue reference in the merge request description +- The third is from the actual commit that solved the issue +- And the fourth is from the commit that the merge request created + +[services-templates]: ../project_services/services_templates.md "Services templates documentation" +[JIRA Core]: https://www.atlassian.com/software/jira/core "The JIRA Core website" +[jira-ce]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2146 "MR - Backport JIRA service" +[8_3_post]: https://about.gitlab.com/2015/12/22/gitlab-8-3-released/ "GitLab 8.3 release post" + +## Troubleshooting + +### GitLab is unable to comment on a ticket + +Make sure that the user you set up for GitLab to communicate with JIRA has the +correct access permission to post comments on a ticket and to also transition the +ticket, if you'd like GitLab to also take care of closing them. + +### GitLab is unable to close a ticket + +Make sure the the `Transition ID` you set within the JIRA settings matches the +one your project needs to close a ticket. diff --git a/doc/project_services/project_services.md b/doc/project_services/project_services.md index 8116a1ce976..4442b7c1742 100644 --- a/doc/project_services/project_services.md +++ b/doc/project_services/project_services.md @@ -40,7 +40,7 @@ further configuration instructions and details. Contributions are welcome. | Gemnasium | Gemnasium monitors your project dependencies and alerts you about updates and security vulnerabilities | | [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | -| [JIRA](../integration/jira.md) | JIRA issue tracker | +| [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | | PivotalTracker | Project Management Software (Source Commits Endpoint) | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | diff --git a/doc/raketasks/check.md b/doc/raketasks/check.md index 3ff3fee6a40..f7f6a40cd04 100644 --- a/doc/raketasks/check.md +++ b/doc/raketasks/check.md @@ -1,63 +1,3 @@ # Check Rake Tasks -## Repository Integrity - -Even though Git is very resilient and tries to prevent data integrity issues, -there are times when things go wrong. The following Rake tasks intend to -help GitLab administrators diagnose problem repositories so they can be fixed. - -There are 3 things that are checked to determine integrity. - -1. Git repository file system check ([git fsck](https://git-scm.com/docs/git-fsck)). - This step verifies the connectivity and validity of objects in the repository. -1. Check for `config.lock` in the repository directory. -1. Check for any branch/references lock files in `refs/heads`. - -It's important to note that the existence of `config.lock` or reference locks -alone do not necessarily indicate a problem. Lock files are routinely created -and removed as Git and GitLab perform operations on the repository. They serve -to prevent data integrity issues. However, if a Git operation is interrupted these -locks may not be cleaned up properly. - -The following symptoms may indicate a problem with repository integrity. If users -experience these symptoms you may use the rake tasks described below to determine -exactly which repositories are causing the trouble. - -- Receiving an error when trying to push code - `remote: error: cannot lock ref` -- A 500 error when viewing the GitLab dashboard or when accessing a specific project. - -### Check all GitLab repositories - -This task loops through all repositories on the GitLab server and runs the -3 integrity checks described previously. - -``` -# omnibus-gitlab -sudo gitlab-rake gitlab:repo:check - -# installation from source -bundle exec rake gitlab:repo:check RAILS_ENV=production -``` - -### Check repositories for a specific user - -This task checks all repositories that a specific user has access to. This is important -because sometimes you know which user is experiencing trouble but you don't know -which project might be the cause. - -If the rake task is executed without brackets at the end, you will be prompted -to enter a username. - -```bash -# omnibus-gitlab -sudo gitlab-rake gitlab:user:check_repos -sudo gitlab-rake gitlab:user:check_repos[<username>] - -# installation from source -bundle exec rake gitlab:user:check_repos RAILS_ENV=production -bundle exec rake gitlab:user:check_repos[<username>] RAILS_ENV=production -``` - -Example output: - - +This document was moved to [administration/raketasks/check](../administration/raketasks/check.md). diff --git a/doc/university/README.md b/doc/university/README.md index 49714e4fb59..4569bc72797 100644 --- a/doc/university/README.md +++ b/doc/university/README.md @@ -212,5 +212,8 @@ The curriculum is composed of GitLab videos, screencasts, presentations, project 1. [Support Path](support/README.md) 1. [Sales Path (redirect to sales handbook)](https://about.gitlab.com/handbook/sales-onboarding/) +1. [User Training](training/user_training.md) +1. [GitLab Flow Training](training/gitlab_flow.md) +1. [Training Topics](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/university/training/topics/) 1. [GitLab architecture for noobs](https://dev.gitlab.org/gitlab/gitlabhq/blob/master/doc/development/architecture.md) 1. [Client Assessment of GitLab versus GitHub](https://docs.google.com/a/gitlab.com/spreadsheets/d/18cRF9Y5I6I7Z_ab6qhBEW55YpEMyU4PitZYjomVHM-M/edit?usp=sharing) diff --git a/doc/university/training/gitlab_flow.md b/doc/university/training/gitlab_flow.md new file mode 100755 index 00000000000..a7db1f2e069 --- /dev/null +++ b/doc/university/training/gitlab_flow.md @@ -0,0 +1,53 @@ +# GitLab Flow + +- A simplified branching strategy +- All features and fixes first go to master +- Allows for 'production' or 'stable' branches +- Bug fixes/hot fix patches are cherry-picked from master + +--- + +# Feature branches + +- Create a feature/bugfix branch to do all work +- Use merge requests to merge to master + + + +--- + +# Production branch + +- One, long-running production release branch + as opposed to individual stable branches +- Consider creating a tag for each version that gets deployed + +--- + +# Production branch + + + +--- + +# Release branch + +- Useful if you release software to customers +- When preparing a new release, create stable branch + from master +- Consider creating a tag for each version +- Cherry-pick critical bug fixes to stable branch for patch release +- Never commit bug fixes directly to stable branch + +--- + +# Release branch + + + +--- + +# More details + +Blog post on 'GitLab Flow' at +[http://doc.gitlab.com/ee/workflow/gitlab_flow.html](http://doc.gitlab.com/ee/workflow/gitlab_flow.html) diff --git a/doc/university/training/gitlab_flow/feature_branches.png b/doc/university/training/gitlab_flow/feature_branches.png Binary files differnew file mode 100644 index 00000000000..88addb623ee --- /dev/null +++ b/doc/university/training/gitlab_flow/feature_branches.png diff --git a/doc/university/training/gitlab_flow/production_branch.png b/doc/university/training/gitlab_flow/production_branch.png Binary files differnew file mode 100644 index 00000000000..33fb26dd621 --- /dev/null +++ b/doc/university/training/gitlab_flow/production_branch.png diff --git a/doc/university/training/gitlab_flow/release_branches.png b/doc/university/training/gitlab_flow/release_branches.png Binary files differnew file mode 100644 index 00000000000..da7ae53413a --- /dev/null +++ b/doc/university/training/gitlab_flow/release_branches.png diff --git a/doc/university/training/index.md b/doc/university/training/index.md new file mode 100755 index 00000000000..03179ff5a77 --- /dev/null +++ b/doc/university/training/index.md @@ -0,0 +1,6 @@ +# GitLab Training Material + +All GitLab training material is stored in markdown format. Slides are +generated using [Deskset](http://www.decksetapp.com/). + +All training material is open to public contribution. diff --git a/doc/university/training/logo.png b/doc/university/training/logo.png Binary files differnew file mode 100644 index 00000000000..cc831790405 --- /dev/null +++ b/doc/university/training/logo.png diff --git a/doc/university/training/topics/additional_resources.md b/doc/university/training/topics/additional_resources.md new file mode 100755 index 00000000000..1ee615432aa --- /dev/null +++ b/doc/university/training/topics/additional_resources.md @@ -0,0 +1,8 @@ +## Additional Resources + +1. GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/) +2. GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis) +3. Pro git book [http://git-scm.com/book](http://git-scm.com/book) +4. Platzi Course [https://courses.platzi.com/courses/git-gitlab/](https://courses.platzi.com/courses/git-gitlab/) +5. Code School tutorial [http://try.github.io/](http://try.github.io/) +6. Contact Us - [subscribers@gitlab.com](subscribers@gitlab.com) diff --git a/doc/university/training/topics/agile_git.md b/doc/university/training/topics/agile_git.md new file mode 100755 index 00000000000..e6e4fea9b51 --- /dev/null +++ b/doc/university/training/topics/agile_git.md @@ -0,0 +1,33 @@ +# Agile and Git + +---------- + +## Agile + +Lean software development methods focused on collaboration and interaction +with fast and smaller deployment cycles. + +---------- + +## Where Git comes in + +Git is an excellent tool for an Agile team considering that it allows +decentralized and simultaneous development. + +---------- + +### Branching And Workflows + +Branching in an Agile environment usually happens around user stories with one +or more developers working on it. + +If more than one developer then another branch for each developer is also used +with his/her initials, and US id. + +After its tested merge into master and remove the branch. + +---------- + +## What about GitLab +Tools like GitLab enhance collaboration by adding dialog around code mainly +through issues and merge requests. diff --git a/doc/university/training/topics/bisect.md b/doc/university/training/topics/bisect.md new file mode 100755 index 00000000000..a60c4365e0c --- /dev/null +++ b/doc/university/training/topics/bisect.md @@ -0,0 +1,81 @@ +# Bisect + +---------- + +## Bisect + +- Find a commit that introduced a bug +- Works through a process of elimination +- Specify a known good and bad revision to begin + +---------- + +## Bisect + +1. Start the bisect process +2. Enter the bad revision (usually latest commit) +3. Enter a known good revision (commit/branch) +4. Run code to see if bug still exists +5. Tell bisect the result +6. Repeat the previous 2 items until you find the offending commit + +---------- + +## Setup + +``` + mkdir bisect-ex + cd bisect-ex + touch index.html + git add -A + git commit -m "starting out" + vi index.html + # Add all good + git add -A + git commit -m "second commit" + vi index.html + # Add all good 2 + git add -A + git commit -m "third commit" + vi index.html +``` + +---------- + +``` + # Add all good 3 + git add -A + git commit -m "fourth commit" + vi index.html + # This looks bad + git add -A + git commit -m "fifth commit" + vi index.html + # Really bad + git add -A + git commit -m "sixth commit" + vi index.html + # again just bad + git add -A + git commit -m "seventh commit" +``` + +---------- + +## Commands + +``` + git bisect start + # Test your code + git bisect bad + git bisect next + # Say yes to the warning + # Test + git bisect good + # Test + git bisect bad + # Test + git bisect good + # done + git bisect reset +``` diff --git a/doc/university/training/topics/cherry_picking.md b/doc/university/training/topics/cherry_picking.md new file mode 100755 index 00000000000..af7a70a2818 --- /dev/null +++ b/doc/university/training/topics/cherry_picking.md @@ -0,0 +1,39 @@ +# Cherry Pick + +---------- + +## Cherry Pick + +- Given an existing commit on one branch, apply the change to another branch +- Useful for backporting bug fixes to previous release branches +- Make the commit on the master branch and pick in to stable + +---------- + +## Cherry Pick + +1. Check out a new 'stable' branch from 'master' +1. Change back to 'master' +1. Edit '`cherry_pick.rb`' and commit the changes. +1. Check commit log to get the commit SHA +1. Check out the 'stable' branch +1. Cherry pick the commit using the SHA obtained earlier + +---------- + +## Commands + +```bash +git checkout master +git checkout -b stable +git checkout master + +# Edit `cherry_pick.rb` +git add cherry_pick.rb +git commit -m 'Fix bugs in cherry_pick.rb' +git log +# Copy commit SHA +git checkout stable + +git cherry-pick <commit SHA> +``` diff --git a/doc/university/training/topics/env_setup.md b/doc/university/training/topics/env_setup.md new file mode 100755 index 00000000000..8149379b36f --- /dev/null +++ b/doc/university/training/topics/env_setup.md @@ -0,0 +1,60 @@ +# Configure your environment + +---------- +## Install + +- **Windows** + - Install 'Git for Windows' from https://git-for-windows.github.io + +- **Mac** + - Type '`git`' in the Terminal application. + - If it's not installed, it will prompt you to install it. + +- **Linux** + ```bash + sudo yum install git-all + ``` + ```bash + sudo apt-get install git-all + ``` + +---------- + +## Configure Git + +One-time configuration of the Git client + +```bash +git config --global user.name "Your Name" +git config --global user.email you@example.com +``` + +---------- + +## Configure SSH Key + +```bash +ssh-keygen -t rsa -b 4096 -C "you@computer-name" +``` + +```bash +# You will be prompted for the following information. Press enter to accept the defaults. Defaults appear in parentheses. +Generating public/private rsa key pair. +Enter file in which to save the key (/Users/you/.ssh/id_rsa): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /Users/you/.ssh/id_rsa. +Your public key has been saved in /Users/you/.ssh/id_rsa.pub. +The key fingerprint is: +39:fc:ce:94:f4:09:13:95:64:9a:65:c1:de:05:4d:01 you@computer-name +``` + +Copy your public key and add it to your GitLab profile + +```bash +cat ~/.ssh/id_rsa.pub +``` + +```bash +ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com +``` diff --git a/doc/university/training/topics/explore_gitlab.md b/doc/university/training/topics/explore_gitlab.md new file mode 100755 index 00000000000..b65457728c0 --- /dev/null +++ b/doc/university/training/topics/explore_gitlab.md @@ -0,0 +1,10 @@ +# Explore GitLab projects + +---------- + +- Dashboard +- User Preferences +- Issues +- Milestones and Labels +- Manage project members +- Project settings diff --git a/doc/university/training/topics/feature_branching.md b/doc/university/training/topics/feature_branching.md new file mode 100755 index 00000000000..4b34406ea75 --- /dev/null +++ b/doc/university/training/topics/feature_branching.md @@ -0,0 +1,32 @@ +# Feature branching + +---------- + +- Efficient parallel workflow for teams +- Develop each feature in a branch +- Keeps changes isolated +- Consider a 1-to-1 link to issues +- Push branches to the server frequently + - Hint: This is a cheap backup for your work-in-progress code + +---------- + +## Feature branching + +1. Create a new feature branch called 'squash_some_bugs' +1. Edit '`bugs.rb`' and remove all the bugs. +1. Commit +1. Push + +---------- + +## Commands + +``` +git checkout -b squash_some_bugs +# Edit `bugs.rb` +git status +git add bugs.rb +git commit -m 'Fix some buggy code' +git push origin squash_some_bugs +``` diff --git a/doc/university/training/topics/getting_started.md b/doc/university/training/topics/getting_started.md new file mode 100755 index 00000000000..ec7bb2631aa --- /dev/null +++ b/doc/university/training/topics/getting_started.md @@ -0,0 +1,95 @@ +# Getting Started + +---------- + +## Instantiating Repositories + +* Create a new repository by instantiating it through +```bash +git init +``` +* Copy an existing project by cloning the repository through +```bash +git clone <url> +``` + +---------- + +## Central Repos + +* To instantiate a central repository a `--bare` flag is required. +* Bare repositories don't allow file editing or committing changes. +* Create a bare repo with +```bash +git init --bare project-name.git +``` + +---------- + +## Instantiate workflow with clone + +1. Create a project in your user namespace + - Choose to import from 'Any Repo by URL' and use + https://gitlab.com/gitlab-org/training-examples.git +2. Create a '`Workspace`' directory in your home directory. +3. Clone the '`training-examples`' project + +---------- + +## Commands + +``` +mkdir ~/workspace +cd ~/workspace + +git clone git@gitlab.example.com:<username>/training-examples.git +cd training-examples +``` +---------- + +## Git concepts + +**Untracked files** + +New files that Git has not been told to track previously. + +**Working area** + +Files that have been modified but are not committed. + +**Staging area** + +Modified files that have been marked to go in the next commit. + +---------- + +## Committing Workflow + +1. Edit '`edit_this_file.rb`' in '`training-examples`' +1. See it listed as a changed file (working area) +1. View the differences +1. Stage the file +1. Commit +1. Push the commit to the remote +1. View the git log + +---------- + +## Commands + +``` +# Edit `edit_this_file.rb` +git status +git diff +git add <file> +git commit -m 'My change' +git push origin master +git log +``` + +---------- + +## Note + +* git fetch vs pull +* Pull is git fetch + git merge diff --git a/doc/university/training/topics/git_add.md b/doc/university/training/topics/git_add.md new file mode 100755 index 00000000000..9ffb4b9c859 --- /dev/null +++ b/doc/university/training/topics/git_add.md @@ -0,0 +1,33 @@ +# Git Add + +---------- + +## Git Add + +Adds content to the index or staging area. + +* Adds a list of file +```bash +git add <files> +``` +* Adds all files including deleted ones +```bash +git add -A +``` + +---------- + +## Git add continued + +* Add all text files in current dir +```bash +git add *.txt +``` +* Add all text file in the project +```bash +git add "*.txt*" +``` +* Adds all files in directory +```bash +git add views/layouts/ +``` diff --git a/doc/university/training/topics/git_intro.md b/doc/university/training/topics/git_intro.md new file mode 100755 index 00000000000..ca1ff29d93b --- /dev/null +++ b/doc/university/training/topics/git_intro.md @@ -0,0 +1,24 @@ +# Git introduction + +---------- + +## Intro + +https://git-scm.com/about + +- Distributed version control + - Does not rely on connection to a central server + - Many copies of the complete history +- Powerful branching and merging +- Adapts to nearly any workflow +- Fast, reliable and stable file format + +---------- + +## Help! + +Use the tools at your disposal when you get stuck. + +- Use '`git help <command>`' command +- Use Google +- Read documentation at https://git-scm.com diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md new file mode 100755 index 00000000000..32ebceff491 --- /dev/null +++ b/doc/university/training/topics/git_log.md @@ -0,0 +1,57 @@ +# Git Log + +---------- + +Git log lists commit history. It allows searching and filtering. + +* Initiate log +``` +git log +``` + +* Retrieve set number of records: +``` +git log -n 2 +``` + +* Search commits by author. Allows user name or a regular expression. +``` +git log --author="user_name" +``` + +---------- + +* Search by comment message. +``` +git log --grep="<pattern>" +``` + +* Search by date +``` +git log --since=1.month.ago --until=3.weeks.ago +``` + + +---------- + +## Git Log Workflow + +1. Change to workspace directory +2. Clone the multi runner projects +3. Change to project dir +4. Search by author +5. Search by date +6. Combine + +---------- + +## Commands + +``` +cd ~/workspace +git clone git@gitlab.com:gitlab-org/gitlab-ci-multi-runner.git +cd gitlab-ci-multi-runner +git log --author="Travis" +git log --since=1.month.ago --until=3.weeks.ago +git log --since=1.month.ago --until=1.day.ago --author="Travis" +``` diff --git a/doc/university/training/topics/gitlab_flow.md b/doc/university/training/topics/gitlab_flow.md new file mode 100755 index 00000000000..8e5d3baf959 --- /dev/null +++ b/doc/university/training/topics/gitlab_flow.md @@ -0,0 +1,53 @@ +# GitLab Flow + +---------- + +- A simplified branching strategy +- All features and fixes first go to master +- Allows for 'production' or 'stable' branches +- Bug fixes/hot fix patches are cherry-picked from master + +---------- + +### Feature branches + +- Create a feature/bugfix branch to do all work +- Use merge requests to merge to master + + + +---------- + +## Production branch + +- One, long-running production release branch + as opposed to individual stable branches +- Consider creating a tag for each version that gets deployed + +---------- + +## Production branch + + + +---------- + +## Release branch + +- Useful if you release software to customers +- When preparing a new release, create stable branch + from master +- Consider creating a tag for each version +- Cherry-pick critical bug fixes to stable branch for patch release +- Never commit bug fixes directly to stable branch + +---------- + + + +---------- + +## More details + +Blog post on 'GitLab Flow' at +[http://doc.gitlab.com/ee/workflow/gitlab_flow.html](http://doc.gitlab.com/ee/workflow/gitlab_flow.html) diff --git a/doc/university/training/topics/merge_conflicts.md b/doc/university/training/topics/merge_conflicts.md new file mode 100755 index 00000000000..77807b3e7ef --- /dev/null +++ b/doc/university/training/topics/merge_conflicts.md @@ -0,0 +1,70 @@ +# Merge conflicts + +---------- + +- Happen often +- Learning to fix conflicts is hard +- Practice makes perfect +- Force push after fixing conflicts. Be careful! + +---------- + +## Merge conflicts + +1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'. +2. Commit and push +3. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. +4. Commit and push to master +5. Create a merge request and watch it fail +6. Rebase our new branch with master +7. Fix conflicts on the `conflicts.rb` file. +8. Stage the file and continue rebasing +9. Force push the changes +10. Finally continue with the Merge Request + +---------- + +## Commands + +``` +git checkout -b conflicts_branch + +# vi conflicts.rb +# Add 'Line4' and 'Line5' + +git commit -am "add line4 and line5" +git push origin conflicts_branch + +git checkout master + +# vi conflicts.rb +# Add 'Line6' and 'Line7' +git commit -am "add line6 and line7" +git push origin master +``` + +Create a merge request on the GitLab web UI. You'll see a conflict warning. + +``` +git checkout conflicts_branch +git fetch +git rebase master + +# Fix conflicts by editing the files. + +git add conflicts.rb +# No need to commit this file + +git rebase --continue + +# Remember that we have rewritten our commit history so we +# need to force push so that our remote branch is restructured +git push origin conflicts_branch -f +``` +---------- + +## Note +* When to use 'git merge' and when to use 'git rebase' +* Rebase when updating your branch with master +* Merge when bringing changes from feature to master +* Reference: https://www.atlassian.com/git/tutorials/merging-vs-rebasing/ diff --git a/doc/university/training/topics/merge_requests.md b/doc/university/training/topics/merge_requests.md new file mode 100755 index 00000000000..5b446f02f63 --- /dev/null +++ b/doc/university/training/topics/merge_requests.md @@ -0,0 +1,43 @@ +# Merge requests + +---------- + +- When you want feedback create a merge request +- Target is the default branch (usually master) +- Assign or mention the person you would like to review +- Add 'WIP' to the title if it's a work in progress +- When accepting, always delete the branch +- Anyone can comment, not just the assignee +- Push corrections to the same branch + +---------- + +## Merge requests + +**Create your first merge request** + +1. Use the blue button in the activity feed +1. View the diff (changes) and leave a comment +1. Push a new commit to the same branch +1. Review the changes again and notice the update + +---------- + +## Feedback and Collaboration + +- Merge requests are a time for feedback and collaboration +- Giving feedback is hard +- Be as kind as possible +- Receiving feedback is hard +- Be as receptive as possible +- Feedback is about the best code, not the person. You are not your code + +---------- + +## Feedback and Collaboration + +Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests: +[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) + +See GitLab merge requests for examples: +[https://gitlab.com/gitlab-org/gitlab-ce/merge_requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests) diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md new file mode 100755 index 00000000000..cf647284604 --- /dev/null +++ b/doc/university/training/topics/rollback_commits.md @@ -0,0 +1,81 @@ +# Rollback Commits + +---------- + +## Undo Commits + +* Undo last commit putting everything back into the staging area. +``` +git reset --soft HEAD^ +``` + +* Add files and change message with: +``` +git commit --amend -m "New Message" +``` + +---------- + +* Undo last and remove changes +``` +git reset --hard HEAD^ +``` + +* Same as last one but for two commits back +``` +git reset --hard HEAD^^ +``` + +** Don't reset after pushing ** + +---------- + +## Reset Workflow + +1. Edit file again 'edit_this_file.rb' +2. Check status +3. Add and commit with wrong message +4. Check log +5. Amend commit +6. Check log +7. Soft reset +8. Check log +9. Pull for updates +10. Push changes + + +---------- + +## Commands + +``` +# Change file edit_this_file.rb +git status +git commit -am "kjkfjkg" +git log +git commit --amend -m "New comment added" +git log +git reset --soft HEAD^ +git log +git pull origin master +git push origin master +``` + +---------- + +## Note + +* git revert vs git reset +* Reset removes the commit while revert removes the changes but leaves the commit +* Revert is safer considering we can revert a revert + +``` +# Changed file +git commit -am "bug introduced" +git revert HEAD +# New commit created reverting changes +# Now we want to re apply the reverted commit +git log # take hash from the revert commit +git revert <rev commit hash> +# reverted commit is back (new commit created again) +``` diff --git a/doc/university/training/topics/stash.md b/doc/university/training/topics/stash.md new file mode 100755 index 00000000000..c1bdda32645 --- /dev/null +++ b/doc/university/training/topics/stash.md @@ -0,0 +1,86 @@ +# Git Stash + +---------- + +We use git stash to store our changes when they are not ready to be committed +and we need to change to a different branch. + +* Stash +``` +git stash save +# or +git stash +# or with a message +git stash save "this is a message to display on the list" +``` + +* Apply stash to keep working on it +``` +git stash apply +# or apply a specific one from out stack +git stash apply stash@{3} +``` + +---------- + +* Every time we save a stash it gets stacked so by using list we can see all our +stashes. + +``` +git stash list +# or for more information (log methods) +git stash list --stat +``` + +* To clean our stack we need to manually remove them. + +``` +# drop top stash +git stash drop +# or +git stash drop <name> +# to clear all history we can use +git stash clear +``` + +---------- + +* Apply and drop on one command + +``` + git stash pop +``` + +* If we meet conflicts we need to either reset or commit our changes. + +* Conflicts through `pop` will not drop a stash afterwards. + +---------- + +## Git Stash + +1. Modify a file +2. Stage file +3. Stash it +4. View our stash list +5. Confirm no pending changes through status +5. Apply with pop +6. View list to confirm changes + +---------- + +## Commands + +``` +# Modify edit_this_file.rb file +git add . + +git stash save "Saving changes from edit this file" + +git stash list +git status + +git stash pop +git stash list +git status +``` diff --git a/doc/university/training/topics/subtree.md b/doc/university/training/topics/subtree.md new file mode 100755 index 00000000000..5d869af64c1 --- /dev/null +++ b/doc/university/training/topics/subtree.md @@ -0,0 +1,55 @@ +## Subtree + +---------- + +## Subtree + +* Used when there are nested repositories. +* Not recommended when the amount of dependencies is too large +* For these cases we need a dependency control system +* Command are painfully long so aliases are necessary + +---------- + +## Subtree Aliases + +* Add: git subtree add --prefix <target-folder> <url> <branch> --squash +* Pull: git subtree add --prefix <target-folder> <url> <branch> --squash +* Push: git subtree add --prefix <target-folder> <url> <branch> +* Ex: git config alias.sbp 'subtree pull --prefix st / + git@gitlab.com:balameb/subtree-nested-example.git master --squash' + +---------- + +``` + # Add an alias + # Add + git config alias.sba 'subtree add --prefix st / + git@gitlab.com:balameb/subtree-nested-example.git master --squash' + # Pull + git config alias.sbpl 'subtree pull --prefix st / + git@gitlab.com:balameb/subtree-nested-example.git master --squash' + # Push + git config alias.sbph 'subtree push --prefix st / + git@gitlab.com:balameb/subtree-nested-example.git master' + + # Adding this subtree adds a st dir with a readme + git sba + vi st/README.md + # Edit file + git status shows differences + +``` + +---------- + +``` + # Adding, or committing won't change the sub repo at remote + # even if we push + git add -A + git commit -m "Adding to subtree readme" + + # Push to subtree repo + git sbph + # now we can check our remote sub repo +``` diff --git a/doc/university/training/topics/tags.md b/doc/university/training/topics/tags.md new file mode 100755 index 00000000000..e9607b5a875 --- /dev/null +++ b/doc/university/training/topics/tags.md @@ -0,0 +1,38 @@ +# Tags + +---------- + +- Useful for marking deployments and releases +- Annotated tags are an unchangeable part of Git history +- Soft/lightweight tags can be set and removed at will +- Many projects combine an anotated release tag with a stable branch +- Consider setting deployment/release tags automatically + +---------- + +# Tags + +- Create a lightweight tag +- Create an annotated tag +- Push the tags to the remote repository + +**Additional resources** + +[http://git-scm.com/book/en/Git-Basics-Tagging](http://git-scm.com/book/en/Git-Basics-Tagging) + +---------- + +# Commands + +``` +git checkout master + +# Lightweight tag +git tag my_lightweight_tag + +# Annotated tag +git tag -a v1.0 -m ‘Version 1.0’ +git tag + +git push origin --tags +``` diff --git a/doc/university/training/topics/unstage.md b/doc/university/training/topics/unstage.md new file mode 100755 index 00000000000..17dbb64b9e6 --- /dev/null +++ b/doc/university/training/topics/unstage.md @@ -0,0 +1,31 @@ +# Unstage + +---------- + +## Unstage + +* To remove files from stage use reset HEAD. Where HEAD is the last commit of the current branch. + +```bash +git reset HEAD <file> +``` + +* This will unstage the file but maintain the modifications. To revert the file back to the state it was in before the changes we can use: + +```bash +git checkout -- <file> +``` + +---------- + +* To remove a file from disk and repo use 'git rm' and to rm a dir use the '-r' flag. +``` +git rm '*.txt' +git rm -r <dirname> +``` + + +* If we want to remove a file from the repository but keep it on disk, say we forgot to add it to our `.gitignore` file then use `--cache`. +``` +git rm <filename> --cache +``` diff --git a/doc/university/training/user_training.md b/doc/university/training/user_training.md new file mode 100755 index 00000000000..35afe73708f --- /dev/null +++ b/doc/university/training/user_training.md @@ -0,0 +1,392 @@ +# GitLab Git Workshop + +--- + +# Agenda + +1. Brief history of Git +1. GitLab walkthrough +1. Configure your environment +1. Workshop + +--- + +# Git introduction + +https://git-scm.com/about + +- Distributed version control + - Does not rely on connection to a central server + - Many copies of the complete history +- Powerful branching and merging +- Adapts to nearly any workflow +- Fast, reliable and stable file format + +--- + +# Help! + +Use the tools at your disposal when you get stuck. + +- Use '`git help <command>`' command +- Use Google +- Read documentation at https://git-scm.com + +--- + +# GitLab Walkthrough + + + +--- + +# Configure your environment + +- Windows: Install 'Git for Windows' + +> https://git-for-windows.github.io + +- Mac: Type '`git`' in the Terminal application. + +> If it's not installed, it will prompt you to install it. + +- Debian: '`sudo apt-get install git-all`' +or Red Hat '`sudo yum install git-all`' + +--- + +# Git Workshop + +## Overview + +1. Configure Git +1. Configure SSH Key +1. Create a project +1. Committing +1. Feature branching +1. Merge requests +1. Feedback and Collaboration + +--- + +# Configure Git + +One-time configuration of the Git client + +```bash +git config --global user.name "Your Name" +git config --global user.email you@example.com +``` + +--- + +# Configure SSH Key + +```bash +ssh-keygen -t rsa -b 4096 -C "you@computer-name" +``` + +```bash +# You will be prompted for the following information. Press enter to accept the defaults. Defaults appear in parentheses. +Generating public/private rsa key pair. +Enter file in which to save the key (/Users/you/.ssh/id_rsa): +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /Users/you/.ssh/id_rsa. +Your public key has been saved in /Users/you/.ssh/id_rsa.pub. +The key fingerprint is: +39:fc:ce:94:f4:09:13:95:64:9a:65:c1:de:05:4d:01 you@computer-name +``` + +Copy your public key and add it to your GitLab profile + +```bash +cat ~/.ssh/id_rsa.pub +``` + +```bash +ssh-rsa AAAAB3NzaC1yc2EAAAADAQEL17Ufacg8cDhlQMS5NhV8z3GHZdhCrZbl4gz you@example.com +``` + +--- + +# Create a project + +- Create a project in your user namespace + - Choose to import from 'Any Repo by URL' and use + https://gitlab.com/gitlab-org/training-examples.git +- Create a '`development`' or '`workspace`' directory in your home directory. +- Clone the '`training-examples`' project + +--- + +# Commands + +``` +mkdir ~/development +cd ~/development + +-or- + +mkdir ~/workspace +cd ~/workspace + +git clone git@gitlab.example.com:<username>/training-examples.git +cd training-examples +``` + +--- + +# Git concepts + +**Untracked files** + +New files that Git has not been told to track previously. + +**Working area** + +Files that have been modified but are not committed. + +**Staging area** + +Modified files that have been marked to go in the next commit. + +--- + +# Committing + +1. Edit '`edit_this_file.rb`' in '`training-examples`' +1. See it listed as a changed file (working area) +1. View the differences +1. Stage the file +1. Commit +1. Push the commit to the remote +1. View the git log + +--- + +# Commands + +``` +# Edit `edit_this_file.rb` +git status +git diff +git add <file> +git commit -m 'My change' +git push origin master +git log +``` + +--- + +# Feature branching + +- Efficient parallel workflow for teams +- Develop each feature in a branch +- Keeps changes isolated +- Consider a 1-to-1 link to issues +- Push branches to the server frequently + - Hint: This is a cheap backup for your work-in-progress code + +--- + +# Feature branching + +1. Create a new feature branch called 'squash_some_bugs' +1. Edit '`bugs.rb`' and remove all the bugs. +1. Commit +1. Push + +--- + +# Commands + +``` +git checkout -b squash_some_bugs +# Edit `bugs.rb` +git status +git add bugs.rb +git commit -m 'Fix some buggy code' +git push origin squash_some_bugs +``` + +--- + +# Merge requests + +- When you want feedback create a merge request +- Target is the ‘default’ branch (usually master) +- Assign or mention the person you would like to review +- Add 'WIP' to the title if it's a work in progress +- When accepting, always delete the branch +- Anyone can comment, not just the assignee +- Push corrections to the same branch + +--- + +# Merge requests + +**Create your first merge request** + +1. Use the blue button in the activity feed +1. View the diff (changes) and leave a comment +1. Push a new commit to the same branch +1. Review the changes again and notice the update + +--- + +# Feedback and Collaboration + +- Merge requests are a time for feedback and collaboration +- Giving feedback is hard +- Be as kind as possible +- Receiving feedback is hard +- Be as receptive as possible +- Feedback is about the best code, not the person. You are not your code + +--- + +# Feedback and Collaboration + +Review the Thoughtbot code-review guide for suggestions to follow when reviewing merge requests: +[https://github.com/thoughtbot/guides/tree/master/code-review](https://github.com/thoughtbot/guides/tree/master/code-review) + +See GitLab merge requests for examples: +[https://gitlab.com/gitlab-org/gitlab-ce/merge_requests](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests) + +--- + +# Explore GitLab projects + + + +- Dashboard +- User Preferences +- ReadMe, Changelog, License shortcuts +- Issues +- Milestones and Labels +- Manage project members +- Project settings + +--- + +# Tags + +- Useful for marking deployments and releases +- Annotated tags are an unchangeable part of Git history +- Soft/lightweight tags can be set and removed at will +- Many projects combine an anotated release tag with a stable branch +- Consider setting deployment/release tags automatically + +--- + +# Tags + +- Create a lightweight tag +- Create an annotated tag +- Push the tags to the remote repository + +**Additional resources** + +[http://git-scm.com/book/en/Git-Basics-Tagging](http://git-scm.com/book/en/Git-Basics-Tagging) + +--- + +# Commands + +``` +git checkout master + +# Lightweight tag +git tag my_lightweight_tag + +# Annotated tag +git tag -a v1.0 -m ‘Version 1.0’ +git tag + +git push origin --tags +``` + +--- + +# Merge conflicts + +- Happen often +- Learning to fix conflicts is hard +- Practice makes perfect +- Force push after fixing conflicts. Be careful! + +--- + +# Merge conflicts + +1. Checkout a new branch and edit `conflicts.rb`. Add 'Line4' and 'Line5'. +1. Commit and push +1. Checkout master and edit `conflicts.rb`. Add 'Line6' and 'Line7' below 'Line3'. +1. Commit and push to master +1. Create a merge request + +--- + +# Merge conflicts + +After creating a merge request you should notice that conflicts exist. Resolve +the conflicts locally by rebasing. + +``` +git rebase master + +# Fix conflicts by editing the files. + +git add conflicts.rb +git commit -m 'Fix conflicts' +git rebase --continue +git push origin <branch> -f +``` + +--- + +# Rebase with squash + +You may end up with a commit log that looks like this: + +``` +Fix issue #13 +Test +Fix +Fix again +Test +Test again +Does this work? +``` + +Squash these in to meaningful commits using an interactive rebase. + +--- + +# Rebase with squash + +Squash the commits on the same branch we used for the merge conflicts step. + +``` +git rebase -i master +``` + +In the editor, leave the first commit as 'pick' and set others to 'fixup'. + +--- + +# Questions? + + + +Thank you for your hard work! + +**Additional Resources** + +GitLab Documentation [http://docs.gitlab.com](http://docs.gitlab.com/) +GUI Clients [http://git-scm.com/downloads/guis](http://git-scm.com/downloads/guis) +Pro git book [http://git-scm.com/book](http://git-scm.com/book) +Platzi Course [https://courses.platzi.com/courses/git-gitlab/](https://courses.platzi.com/courses/git-gitlab/) +Code School tutorial [http://try.github.io/](http://try.github.io/) +Contact Us - [subscribers@gitlab.com](subscribers@gitlab.com) diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 7a7a0b864bd..dbc7e0f14e3 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -590,7 +590,7 @@ Quote break. You can also use raw HTML in your Markdown, and it'll mostly work pretty well. -See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` whitelist, GitLab allows `span` elements. +See the documentation for HTML::Pipeline's [SanitizationFilter](http://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant) class for the list of allowed HTML tags and attributes. In addition to the default `SanitizationFilter` whitelist, GitLab allows `span` elements. ```no-highlight <dl> diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 1b49a5c385f..c936e8833c6 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -66,6 +66,7 @@ Below is the table of events users can be notified of: In all of the below cases, the notification will be sent to: - Participants: - the author and assignee of the issue/merge request + - the author of the pipeline - authors of comments on the issue/merge request - anyone mentioned by `@username` in the issue/merge request title or description - anyone mentioned by `@username` in any of the comments on the issue/merge request @@ -88,6 +89,8 @@ In all of the below cases, the notification will be sent to: | Reopen merge request | | | Merge merge request | | | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | +| Failed pipeline | The above, plus the author of the pipeline | +| Successful pipeline | The above, plus the author of the pipeline | In addition, if the title or description of an Issue or Merge Request is |
