diff options
Diffstat (limited to 'doc')
37 files changed, 476 insertions, 237 deletions
diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index b5e2b5448f7..e1b2a0a24eb 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -25,15 +25,13 @@ gitaly['prometheus_listen_addr'] = 'localhost:9236' ``` To change a Gitaly setting in installations from source you can edit -`/home/git/gitaly/config.toml`. +`/home/git/gitaly/config.toml`. Changes will be applied when you run +`service gitlab restart`. ```toml prometheus_listen_addr = "localhost:9236" ``` -Changes to `/home/git/gitaly/config.toml` are applied when you run `service -gitlab restart`. - ## Client-side GRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index ebc4c1c1c2d..040c9ecae55 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -3,6 +3,11 @@ You can view information and options set for each of the mounted NFS file systems by running `nfsstat -m` and `cat /etc/fstab`. +NOTE: **Note:** Filesystem performance has a big impact on overall GitLab +performance, especially for actions that read or write to Git repositories. See +[Filesystem Performance Benchmarking](../operations/filesystem_benchmarking.md) +for steps to test filesystem performance. + ## NFS Server features ### Required features diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 293036f2f4b..b61c5409a56 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -80,10 +80,10 @@ our AsciiDoc snippets, wikis and repos using delimited blocks: ``` [plantuml, format="png", id="myDiagram", width="200px"] - -- + ---- Bob->Alice : hello Alice -> Bob : Go Away - -- + ---- ``` - **reStructuredText** diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 757865ea2c5..2feac1fd3b0 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -98,7 +98,7 @@ _The artifacts are stored by default in If you don't want to use the local disk where GitLab is installed to store the artifacts, you can use an object storage like AWS S3 instead. This configuration relies on valid AWS credentials to be configured already. -Use an [Object storage option][os] like AWS S3 to store job artifacts. +Use an object storage option like AWS S3 to store job artifacts. ### Object Storage Settings @@ -315,4 +315,3 @@ memory and disk I/O. [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" [gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository" -[os]: https://docs.gitlab.com/administration/job_artifacts.html#using-object-storage diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md new file mode 100644 index 00000000000..44018e966e0 --- /dev/null +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -0,0 +1,55 @@ +# Filesystem Performance Benchmarking + +Filesystem performance has a big impact on overall GitLab performance, +especially for actions that read or write to Git repositories. This information +will help benchmark filesystem performance against known good and bad real-world +systems. + +Normally when talking about filesystem performance the biggest concern is +with Network Filesystems (NFS). However, even some local disks can have slow +IO. The information on this page can be used for either scenario. + +## Write Performance + +The following one-line command is a quick benchmark for filesystem write +performance. This will write 1,000 small files to the directory in which it is +executed. + +1. Change into the root of the appropriate + [repository storage path](../repository_storage_paths.md). +1. Create a temporary directory for the test so it's easy to remove the files later: + + ```sh + mkdir test; cd test + ``` +1. Run the command: + + ```sh + time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done + ``` +1. Remove the test files: + + ```sh + cd ../; rm -rf test + ``` + +The output of the `time for ...` command will look similar to the following. The +important metric is the `real` time. + +```sh +$ time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done + +real 0m0.116s +user 0m0.025s +sys 0m0.091s +``` + +From experience with multiple customers, the following are ranges that indicate +whether your filesystem performance is satisfactory or less than ideal: + +| Rating | Benchmark result | +|:----------|:------------------------| +| Best | Less than 10 seconds | +| OK | 10-18 seconds | +| Poor | 18-25 seconds | +| Very poor | Greater than 25 seconds | diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index dea98cb8197..a16fc7ae74f 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -16,3 +16,7 @@ to restart Sidekiq. indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or by [doing away with user SSH keys stored on GitLab entirely in favor of SSH certificates](ssh_certificates.md). +- [Filesystem Performance Benchmarking](filesystem_benchmarking.md): Filesystem +performance can have a big impact on GitLab performance, especially for actions +that read or write Git repositories. This information will help benchmark +filesystem performance against known good and bad real-world systems. diff --git a/doc/api/events.md b/doc/api/events.md index cd84b32029e..ccac5b8bb60 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -71,7 +71,7 @@ Parameters: Example request: ``` -curl --header "PRIVATE-TOKEN 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 ``` Example response: @@ -276,7 +276,7 @@ Parameters: Example request: ``` -curl --header "PRIVATE-TOKEN 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:project_id/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:project_id/events&target_type=issue&action=created&after=2017-01-31&before=2017-03-01 ``` Example response: diff --git a/doc/api/settings.md b/doc/api/settings.md index 4482030888d..dfdb7cd38de 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,3 +1,7 @@ +--- +table_display_block: true +--- + # Application settings API These API calls allow you to read and modify GitLab instance diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index ab429e0ded3..70020d461d9 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -125,7 +125,7 @@ They can be added per project by navigating to the project's **Settings** > **CI To the field **KEY**, add the name `SSH_PRIVATE_KEY`, and to the **VALUE** field, paste the private key you've copied earlier. We'll use this variable in the `.gitlab-ci.yml` later, to easily connect to our remote server as the deployer user without entering its password. -We also need to add the public key to **Project** > **Settings** > **Repository** as [Deploy Keys](../../../ssh/README.md/#deploy-keys), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md/#start-working-on-your-project). +We also need to add the public key to **Project** > **Settings** > **Repository** as [Deploy Keys](../../../ssh/README.md#deploy-keys), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). ```bash @@ -378,7 +378,7 @@ These are persistent data and will be shared to every new release. Now, we would need to deploy our app by running `envoy run deploy`, but it won't be necessary since GitLab can handle that for us with CI's [environments](../../environments.md), which will be described [later](#setting-up-gitlab-ci-cd) in this tutorial. Now it's time to commit [Envoy.blade.php](https://gitlab.com/mehranrasulian/laravel-sample/blob/master/Envoy.blade.php) and push it to the `master` branch. -To keep things simple, we commit directly to `master`, without using [feature-branches](../../../workflow/gitlab_flow.md/#github-flow-as-a-simpler-alternative) since collaboration is beyond the scope of this tutorial. +To keep things simple, we commit directly to `master`, without using [feature-branches](../../../workflow/gitlab_flow.md#github-flow-as-a-simpler-alternative) since collaboration is beyond the scope of this tutorial. In a real world project, teams may use [Issue Tracker](../../../user/project/issues/index.md) and [Merge Requests](../../../user/project/merge_requests/index.md) to move their code across branches: ```bash @@ -398,7 +398,7 @@ In the case you're not familiar with Docker, refer to [How to Automate Docker De To be able to build, test, and deploy our app with GitLab CI/CD, we need to prepare our work environment. To do that, we'll use a Docker image which has the minimum requirements that a Laravel app needs to run. -[There are other ways](../php.md/#test-php-projects-using-the-docker-executor) to do that as well, but they may lead our builds run slowly, which is not what we want when there are faster options to use. +[There are other ways](../php.md#test-php-projects-using-the-docker-executor) to do that as well, but they may lead our builds run slowly, which is not what we want when there are faster options to use. With Docker images our builds run incredibly faster! @@ -536,7 +536,7 @@ That's a lot to take in, isn't it? Let's run through it step by step. [GitLab Runners](../../runners/README.md) run the script defined by `.gitlab-ci.yml`. The `image` keyword tells the Runners which image to use. -The `services` keyword defines additional images [that are linked to the main image](../../docker/using_docker_images.md/#what-is-a-service). +The `services` keyword defines additional images [that are linked to the main image](../../docker/using_docker_images.md#what-is-a-service). Here we use the container image we created before as our main image and also use MySQL 5.7 as a service. ```yaml @@ -560,7 +560,7 @@ So we should adjust the configuration of MySQL instance by defining `MYSQL_DATAB Find out more about MySQL variables at the [official MySQL Docker Image](https://hub.docker.com/r/_/mysql/). Also set the variables `DB_HOST` to `mysql` and `DB_USERNAME` to `root`, which are Laravel specific variables. -We define `DB_HOST` as `mysql` instead of `127.0.0.1`, as we use MySQL Docker image as a service which [is linked to the main Docker image](../../docker/using_docker_images.md/#how-services-are-linked-to-the-build). +We define `DB_HOST` as `mysql` instead of `127.0.0.1`, as we use MySQL Docker image as a service which [is linked to the main Docker image](../../docker/using_docker_images.md#how-services-are-linked-to-the-build). ```yaml ... @@ -602,7 +602,7 @@ unit_test: #### Deploy to production The job `deploy_production` will deploy the app to the production server. -To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable as an [SSH private key](../../ssh_keys/README.md/#ssh-keys-when-using-the-docker-executor). +To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable as an [SSH private key](../../ssh_keys/README.md#ssh-keys-when-using-the-docker-executor). If the SSH keys have added successfully, we can run Envoy. As mentioned before, GitLab supports [Continuous Delivery](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) methods as well. diff --git a/doc/ci/examples/php.md b/doc/ci/examples/php.md index df4805ea7ac..c1048f3d2e3 100644 --- a/doc/ci/examples/php.md +++ b/doc/ci/examples/php.md @@ -20,7 +20,7 @@ build environment. Let's first specify the PHP image that will be used for the job process (you can read more about what an image means in the Runner's lingo reading -about [Using Docker images](../docker/using_docker_images.md#what-is-image)). +about [Using Docker images](../docker/using_docker_images.md#what-is-an-image)). Start by adding the image to your `.gitlab-ci.yml`: diff --git a/doc/ci/img/pipeline_incremental_rollout.png b/doc/ci/img/pipeline_incremental_rollout.png Binary files differnew file mode 100644 index 00000000000..b3498e9a5a5 --- /dev/null +++ b/doc/ci/img/pipeline_incremental_rollout.png diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index ea47d676edb..44589500eb0 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -193,6 +193,18 @@ stage has a job with a manual action.  +### Delay a particular job in the pipeline graph + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4. + +When you do not want to run a job immediately, you can [delay the job to run after a certain period](yaml/README.md#delayed). +This is especially useful for timed incremental rollout that new code is rolled out gradually. +For example, if you start rolling out new code and users do not experience trouble, GitLab automatically completes the deployment from 0% to 100%. +Alternatively, if you start rolling out and you noticed that a few users experience trouble with the version, +you can stop the timed incremental rollout by canceling the pipeline, and [rolling](environments.md#rolling-back-changes) it back to the stable version. + + + ### Ordering of jobs in pipeline graphs **Regular pipeline graph** @@ -211,6 +223,7 @@ by name. The order of severity is: - pending - running - manual +- scheduled - canceled - success - skipped diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index cf92d90ba30..bffb0121603 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -2,7 +2,7 @@ > **Notes**: > -> - [Introduced][ci-229] in GitLab CE 7.14. +> - [Introduced](https://about.gitlab.com/2015/08/22/gitlab-7-14-released/) in GitLab 7.14. > - GitLab 8.12 has a completely redesigned job permissions system. Read all > about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). @@ -154,10 +154,10 @@ This information is also exposed in the UI. Using trigger variables can be proven useful for a variety of reasons: -* Identifiable jobs. Since the variable is exposed in the UI you can know +- Identifiable jobs. Since the variable is exposed in the UI you can know why the rebuild was triggered if you pass a variable that explains the purpose. -* Conditional job processing. You can have conditional jobs that run whenever +- Conditional job processing. You can have conditional jobs that run whenever a certain variable is present. Consider the following `.gitlab-ci.yml` where we set three @@ -221,7 +221,6 @@ removed with one of the future versions of GitLab. You are advised to [take ownership](#taking-ownership) of any legacy triggers. [ee-2017]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2017 -[ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 [ee]: https://about.gitlab.com/pricing/ [variables]: ../variables/README.md [predef]: ../variables/README.md#predefined-variables-environment-variables diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 8b770495853..24d60a0cdcc 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -415,7 +415,7 @@ Four keys are now available: `refs`, `kubernetes` and `variables` and `changes`. Refs strategy equals to simplified only/except configuration, whereas kubernetes strategy accepts only `active` keyword. -### `variables` +### `only:variables` `variables` keyword is used to define variables expressions. In other words you can use predefined variables / project / group or @@ -460,7 +460,7 @@ end-to-end: Learn more about variables expressions on [a separate page][variables-expressions]. -### `changes` +### `only:changes` Using `changes` keyword with `only` or `except` makes it possible to define if a job should be created based on files modified by a git push event. @@ -673,6 +673,42 @@ user wants to trigger an action. In other words, in order to trigger a manual action assigned to a branch that the pipeline is running for, user needs to have ability to merge to this branch. +### `when:delayed` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21767) in GitLab 11.4. + +Delayed job are for executing scripts after a certain period. +This is useful if you want to avoid jobs entering `pending` state immediately. + +You can set the period with `start_in` key. The value of `start_in` key is an elapsed time in seconds, unless a unit is +provided. `start_key` must be less than or equal to one hour. Examples of valid values include: + +- `10 seconds` +- `30 minutes` +- `1 hour` + +When there is a delayed job in a stage, the pipeline will not progress until the delayed job has finished. +This means this keyword can also be used for inserting delays between different stages. + +The timer of a delayed job starts immediately after the previous stage has completed. +Similar to other types of jobs, a delayed job's timer will not start unless the previous stage passed. + +The following example creates a job named `timed rollout 10%` that is executed 30 minutes after the previous stage has completed: + +```yaml +timed rollout 10%: + stage: deploy + script: echo 'Rolling out 10% ...' + when: delayed + start_in: 30 minutes +``` + +You can stop the active timer of a delayed job by clicking the **Unschedule** button. +This job will never be executed in the future unless you execute the job manually. + +You can start a delayed job immediately by clicking the **Play** button. +GitLab runner will pick your job soon and start the job. + ## `environment` > **Notes:** diff --git a/doc/development/README.md b/doc/development/README.md index 43d3865da0e..14dfe8eb1f3 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -8,7 +8,7 @@ description: 'Learn how to contribute to GitLab.' ## Get started! - Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md) -- [GitLab contributing guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md) +- [GitLab contributing guide](contributing/index.md) - [Architecture](architecture.md) of GitLab - [Rake tasks](rake_tasks.md) for development @@ -50,6 +50,7 @@ description: 'Learn how to contribute to GitLab.' - [Permissions](permissions.md) - [Prometheus metrics](prometheus_metrics.md) - [Guidelines for reusing abstractions](reusing_abstractions.md) +- [DeclarativePolicy framework](policies.md) ## Performance guides diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index c508969f7f4..b9c369286d2 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -9,4 +9,8 @@ GitLab community members and their privileges/responsibilities. | Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) | | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | -[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce)
\ No newline at end of file +[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce). + +--- + +[Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index be7891061f9..79750878aac 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -13,7 +13,10 @@ There is a special type label called ~"product discovery". It represents a disco ~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone. -The initial issue should be about the problem we are solving. If a separate [product discovery issue](#product-discovery-issues) is needed for additional research and design work, it will be created by a PM or UX person. Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and use a title that makes it clear that the scheduled issue is product discovery +The initial issue should be about the problem we are solving. If a separate [product discovery issue](https://about.gitlab.com/handbook/engineering/ux/ux-department-workflow/#how-we-use-labels) +is needed for additional research and design work, it will be created by a PM or UX person. +Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and +use a title that makes it clear that the scheduled issue is product discovery (e.g. `Product discovery for XYZ`). In order to complete a product discovery issue in a release, you must complete the following: @@ -23,34 +26,6 @@ In order to complete a product discovery issue in a release, you must complete t 1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth. 1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage. -## Style guides - -1. [Ruby](https://github.com/bbatsov/ruby-style-guide). - Important sections include [Source Code Layout][rss-source] and - [Naming][rss-naming]. Use: - - multi-line method chaining style **Option A**: dot `.` on the second line - - string literal quoting style **Option A**: single quoted by default -1. [Rails](https://github.com/bbatsov/rails-style-guide) -1. [Newlines styleguide][newlines-styleguide] -1. [Testing][testing] -1. [JavaScript styleguide][js-styleguide] -1. [SCSS styleguide][scss-styleguide] -1. [Shell commands](../shell_commands.md) created by GitLab - contributors to enhance security -1. [Database Migrations](../migration_style_guide.md) -1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) -1. [Documentation styleguide](https://docs.gitlab.com/ee/development/documentation/styleguide.html) -1. Interface text should be written subjectively instead of objectively. It - should be the GitLab core team addressing a person. It should be written in - present time and never use past tense (has been/was). For example instead - of _prohibited this user from being saved due to the following errors:_ the - text should be _sorry, we could not create your account because:_ -1. Code should be written in [US English][us-english] - -This is also the style used by linting tools such as -[RuboCop](https://github.com/bbatsov/rubocop), -[PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com). - --- [Return to Contributing documentation](index.md) diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index f4486ae3549..29af8dcb9bb 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -1,22 +1,24 @@ # Contribute to GitLab -For a first-time step-by-step guide to the contribution process, see -["Contributing to GitLab"](https://about.gitlab.com/contributing/). - Thank you for your interest in contributing to GitLab. This guide details how -to contribute to GitLab in a way that is efficient for everyone. +to contribute to GitLab in a way that is easy for everyone. + +For a first-time step-by-step guide to the contribution process, please see +["Contributing to GitLab"](https://about.gitlab.com/contributing/). -Looking for something to work on? Look for issues with the label [Accepting Merge Requests](#i-want-to-contribute). +Looking for something to work on? Look for issues in the [Backlog (Accepting merge requests) milestone](#i-want-to-contribute). -GitLab comes into two flavors, GitLab Community Edition (CE) our free and open +GitLab comes in two flavors, GitLab Community Edition (CE) our free and open source edition, and GitLab Enterprise Edition (EE) which is our commercial edition. Throughout this guide you will see references to CE and EE for abbreviation. -If you have read this guide and want to know how the GitLab [core team] +To get an overview of GitLab community membership including those that would be reviewing or merging your contributions, please visit [the community roles page](community_roles.md). + +If you want to know how the GitLab [core team] operates please see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md). -- [GitLab Inc engineers should refer to the engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/) +[GitLab Inc engineers should refer to the engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/) ## Security vulnerability disclosure @@ -28,33 +30,77 @@ vulnerabilities. ## Code of conduct -As contributors and maintainers of this project, we pledge to respect all -people who contribute through reporting issues, posting feature requests, -updating documentation, submitting pull requests or patches, and other -activities. +### Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +### Our Standards -We are committed to making participation in this project a harassment-free -experience for everyone, regardless of level of experience, gender, gender -identity and expression, sexual orientation, disability, personal appearance, -body size, race, ethnicity, age, or religion. +Examples of behavior that contributes to creating a positive environment +include: -Examples of unacceptable behavior by participants include the use of sexual -language or imagery, derogatory comments or personal attacks, trolling, public -or private harassment, insults, or other unprofessional conduct. +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +### Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct. Project maintainers who do not -follow the Code of Conduct may be removed from the project team. +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +### Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +### Enforcement -This code of conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at conduct@gitlab.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. -Instances of abusive, harassing, or otherwise unacceptable behavior can be -reported by emailing `contact@gitlab.com`. +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. -This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant], version 1.1.0, -available at [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/). +### Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org ## Closing policy for issues and merge requests @@ -87,8 +133,8 @@ the remaining issues on the GitHub issue tracker. ## I want to contribute! -If you want to contribute to GitLab [issues with the label `Accepting Merge Requests` and small weight][accepting-mrs-weight] -is a great place to start. Issues with a lower weight (1 or 2) are deemed +If you want to contribute to GitLab, [issues in the `Backlog (Accepting merge requests)` milestone][accepting-mrs-weight] +are a great place to start. Issues with a lower weight (1 or 2) are deemed suitable for beginners. These issues will be of reasonable size and challenge, for anyone to start contributing to GitLab. If you have any questions or need help visit [Getting Help](https://about.gitlab.com/getting-help/#discussion) to learn how to communicate with GitLab. If you're looking for a Gitter or Slack channel @@ -117,93 +163,39 @@ When your code contains more than 500 changes, any major breaking changes, or an This [documentation](issue_workflow.md) outlines the current workflow labels. -### Type labels - -This [documentation](issue_workflow.md) outlines the current type labels. - -### Subject labels - -This [documentation](issue_workflow.md) outlines the current subject labels. - -### Team labels - -This [documentation](issue_workflow.md) outlines the current team labels. - -### Milestone labels - -This [documentation](issue_workflow.md) outlines the current milestone labels. - -### Bug Priority labels - -This [documentation](issue_workflow.md) outlines the current bug priority labels. - -### Bug Severity labels - -This [documentation](issue_workflow.md) outlines the current severity labels. - -#### Severity impact guidance - -This [documentation](issue_workflow.md) outlines the current severity impact guidance. - -### Label for community contributors - -This [documentation](issue_workflow.md) outlines the current policy regarding community contributor issues. - -## Implement design & UI elements - -This [documentation](design.md) outlines the current design and UI guidelines. - -## Issue tracker - -This [documentation](issue_workflow.md) outlines the issue tracker process. - -### Issue triaging - -This [documentation](issue_workflow.md) outlines the current issue triaging process. - -### Feature proposals - -This [documentation](issue_workflow.md) outlines the feature proposal process. - -### Issue tracker guidelines - -This [documentation](issue_workflow.md) outlines the issue tracker guidelines. - -### Issue weight - -This [documentation](issue_workflow.md) outlines the issue weight guidelines. - -### Regression issues - -This [documentation](issue_workflow.md) outlines the regression issue process. - -### Technical and UX debt - -This [documentation](issue_workflow.md) about technical and UX debt has been moved. - -### Stewardship - -This [documentation](issue_workflow.md) outlines the stewardship process. +* [Type labels](issue_workflow.md#type-labels) +* [Subject labels](issue_workflow.md#subject-labels) +* [Team labels](issue_workflow.md#team-labels) +* [Release Scoping labels](issue_workflow.md#release-scoping-labels) +* [Priority labels](issue_workflow.md#priority-labels) +* [Severity labels](issue_workflow.md#severity-labels) +* [Label for community contributors](issue_workflow.md#label-for-community-contributors) +* [Issue triaging](issue_workflow.md#issue-triaging) +* [Feature proposals](issue_workflow.md#feature-proposals) +* [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines) +* [Issue weight](issue_workflow.md#issue-weight) +* [Regression issues](issue_workflow.md#regression-issues) +* [Technical and UX debt](issue_workflow.md#technical-and-ux-debt) +* [Stewardship](issue_workflow.md#stewardship) ## Merge requests This [documentation](merge_request_workflow.md) outlines the current merge request process. -### Merge request guidelines - -This [documentation](merge_request_workflow.md) outlines the current merge request guidelines. - -### Contribution acceptance criteria - -This [documentation](merge_request_workflow.md) outlines the current acceptance criteria for contributions. - -## Definition of done - -This [documentation](merge_request_workflow.md) outlines the definition of done. +* [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines) +* [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria) +* [Definition of done](merge_request_workflow.md#definition-of-done) ## Style guides -This [documentation](design.md) outlines the current style guidelines. + +This [documentation](style_guides.md) outlines the current style guidelines. --- [Return to Development documentation](../README.md) + +[core team]: https://about.gitlab.com/core-team/ +[team]: https://about.gitlab.com/team/ +[getting-help]: https://about.gitlab.com/getting-help/ +[codetriage]: http://www.codetriage.com/gitlabhq/gitlabhq +[accepting-mrs-weight]: https://gitlab.com/gitlab-org/gitlab-ce/issues?scope=all&utf8=✓&state=opened&assignee_id=0&milestone_title=Backlog%20(Accepting%20merge%20requests) diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 1b25a5a2fb7..c0a635db12f 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -20,7 +20,6 @@ If you come across an issue that has none of these, and you're allowed to set labels, you can _always_ add the team and type, and often also the subject. [milestones-page]: https://gitlab.com/gitlab-org/gitlab-ce/milestones -[labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels ## Type labels @@ -208,6 +207,7 @@ project. [GitLab Triage]: https://gitlab.com/gitlab-org/gitlab-triage [scheduled pipeline]: https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/edit [quality/triage-ops]: https://gitlab.com/gitlab-org/quality/triage-ops +[team]: https://about.gitlab.com/team/ ## Feature proposals @@ -235,6 +235,8 @@ need to ask one of the [core team] members to add the label, if you do not have If you want to create something yourself, consider opening an issue first to discuss whether it is interesting to include this in GitLab. +[fpl]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=feature+proposal + ## Issue tracker guidelines **[Search the issue tracker][ce-tracker]** for similar entries before @@ -331,3 +333,7 @@ A recent example of this was the issue for --- [Return to Contributing documentation](index.md) + +[labels-page]: https://gitlab.com/gitlab-org/gitlab-ce/labels +[ce-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues +[ee-tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index a286e74908c..cc7d8a1e1db 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -2,9 +2,9 @@ We welcome merge requests with fixes and improvements to GitLab code, tests, and/or documentation. The issues that are specifically suitable for -community contributions are listed with the label -[`Accepting Merge Requests` on our issue tracker for CE][accepting-mrs-ce] -and [EE][accepting-mrs-ee], but you are free to contribute to any other issue +community contributions are listed with the +[`Backlog (Accepting merge requests)` milestone in the CE issue tracker][accepting-mrs-ce] +and [EE issue tracker][accepting-mrs-ee], but you are free to contribute to any other issue you want. Please note that if an issue is marked for the current milestone either before @@ -19,11 +19,16 @@ wireframes if the feature will also change the UI. Merge requests should be opened at [GitLab.com][gitlab-mr-tracker]. If you are new to GitLab development (or web development in general), see the -[I want to contribute!](#i-want-to-contribute) section to get you started with +[I want to contribute!](index.md#i-want-to-contribute) section to get you started with some potentially easy issues. To start with GitLab development download the [GitLab Development Kit][gdk] and -see the [Development section](../README.md) for some guidelines. +see the [Development section](../../README.md) for some guidelines. + +[accepting-mrs-ce]: https://gitlab.com/gitlab-org/gitlab-ce/issues?milestone_title=Backlog%20(Accepting%20merge%20requests) +[accepting-mrs-ee]: https://gitlab.com/gitlab-org/gitlab-ee/issues?milestone_title=Backlog%20(Accepting%20merge%20requests) +[gitlab-mr-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests +[gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit ## Merge request guidelines @@ -103,6 +108,10 @@ Please ensure that your merge request meets the contribution acceptance criteria When having your code reviewed and when reviewing merge requests please take the [code review guidelines](../code_review.md) into account. +[git-squash]: https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits +[closed-merge-requests]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests?assignee_id=&label_name=&milestone_id=&scope=&sort=&state=closed +[team]: https://about.gitlab.com/team/ + ## Contribution acceptance criteria 1. The change is as small as possible @@ -133,7 +142,7 @@ When having your code reviewed and when reviewing merge requests please take the [polling with ETag caching][polling-etag]. 1. Changes after submitting the merge request should be in separate commits (no squashing). -1. It conforms to the [style guides](#style-guides) and the following: +1. It conforms to the [style guides](style_guides.md) and the following: - If your change touches a line that does not follow the style, modify the entire line to follow it. This prevents linting tools from generating warnings. - Don't touch neighbouring lines. As an exception, automatic mass @@ -144,6 +153,9 @@ When having your code reviewed and when reviewing merge requests please take the "license-finder" test with a "Dependencies that need approval" error. 1. The merge request meets the [definition of done](#definition-of-done). +[license-finder-doc]: ../licensing.md +[polling-etag]: ../polling.md + ## Definition of done If you contribute to GitLab please know that changes involve more than just @@ -156,7 +168,7 @@ the feature you contribute through all of these steps. 1. Performance/scalability implications have been considered, addressed, and tested 1. [Documented][doc-guidelines] in the `/doc` directory 1. [Changelog entry added][changelog], if necessary -1. Reviewed and any concerns are addressed +1. Reviewed by UX/FE/BE and any concerns are addressed 1. Merged by a project maintainer 1. Added to the release blog article, if relevant 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/), if relevant @@ -175,6 +187,12 @@ merge request: 1. Test suite https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/prepare_build.sh 1. Omnibus package creator https://gitlab.com/gitlab-org/omnibus-gitlab +[definition-of-done]: http://guide.agilealliance.org/guide/definition-of-done.html +[testing]: ../testing_guide/index.md + --- [Return to Contributing documentation](index.md) + +[changelog]: ../changelog.md "Generate a changelog entry" +[doc-guidelines]: ../documentation/index.md "Documentation guidelines" diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md new file mode 100644 index 00000000000..fb0454db7d2 --- /dev/null +++ b/doc/development/contributing/style_guides.md @@ -0,0 +1,40 @@ +# Style guides + +1. [Ruby](https://github.com/bbatsov/ruby-style-guide). + Important sections include [Source Code Layout][rss-source] and + [Naming][rss-naming]. Use: + - multi-line method chaining style **Option A**: dot `.` on the second line + - string literal quoting style **Option A**: single quoted by default +1. [Rails](https://github.com/bbatsov/rails-style-guide) +1. [Newlines styleguide][newlines-styleguide] +1. [Testing][testing] +1. [JavaScript styleguide][js-styleguide] +1. [SCSS styleguide][scss-styleguide] +1. [Shell commands](../shell_commands.md) created by GitLab + contributors to enhance security +1. [Database Migrations](../migration_style_guide.md) +1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) +1. [Documentation styleguide](../documentation/styleguide.md) +1. Interface text should be written subjectively instead of objectively. It + should be the GitLab core team addressing a person. It should be written in + present time and never use past tense (has been/was). For example instead + of _prohibited this user from being saved due to the following errors:_ the + text should be _sorry, we could not create your account because:_ +1. Code should be written in [US English][us-english] + +This is also the style used by linting tools such as +[RuboCop](https://github.com/bbatsov/rubocop), +[PullReview](https://www.pullreview.com/) and [Hound CI](https://houndci.com). + +--- + +[Return to Contributing documentation](index.md) + +[rss-source]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#source-code-layout +[rss-naming]: https://github.com/bbatsov/ruby-style-guide/blob/master/README.md#naming +[doc-guidelines]: ../documentation/index.md "Documentation guidelines" +[js-styleguide]: ../fe_guide/style_guide_js.md "JavaScript styleguide" +[scss-styleguide]: ../fe_guide/style_guide_scss.md "SCSS styleguide" +[newlines-styleguide]: ../newlines_styleguide.md "Newlines styleguide" +[testing]: ../testing_guide/index.md +[us-english]: https://en.wikipedia.org/wiki/American_English diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 2db78e4a365..1dcdf788a3e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -321,7 +321,7 @@ The following sample `markdownlint` configuration modifies the available default } ``` -For [`markdownlint`](https://gitahub.com/DavidAnson/markdownlint/), this configuration must be +For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For example, `~/.markdownlintrc`. @@ -414,7 +414,7 @@ to EE only. NOTE: **Note:** To preview your changes to documentation locally, follow this -[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development). +[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). The live preview is currently enabled for the following projects: diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 656ddd868cd..1e0529262ad 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -1,11 +1,13 @@ # Style guides and linting + See the relevant style guides for our guidelines and for information on linting: ## JavaScript + We defer to [Airbnb][airbnb-js-style-guide] on most style-related conventions and enforce them with eslint. -See [our current .eslintrc][eslintrc] for specific rules and patterns. +See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc.yml) for specific rules and patterns. ### Common @@ -21,10 +23,10 @@ refactor an existing one, you should abide by the eslint rules. ```javascript // bad /* eslint-disable */ - + // better /* eslint-disable some-rule, some-other-rule */ - + // best // nothing :) ``` @@ -34,14 +36,14 @@ refactor an existing one, you should abide by the eslint rules. ```javascript // bad /* eslint-disable no-new */ - + import Foo from 'foo'; - + new Foo(); - + // better import Foo from 'foo'; - + // eslint-disable-next-line no-new new Foo(); ``` @@ -58,11 +60,11 @@ followed by any global declarations, then a blank newline prior to any imports o /* global Foo */ /* eslint-disable no-new */ import Bar from './bar'; - + // good /* eslint-disable no-new */ /* global Foo */ - + import Bar from './bar'; ``` @@ -73,7 +75,7 @@ followed by any global declarations, then a blank newline prior to any imports o ```javascript // bad /* globals Flash, Cookies, jQuery */ - + // good /* global Flash */ /* global Cookies */ @@ -85,7 +87,7 @@ followed by any global declarations, then a blank newline prior to any imports o ```javascript // bad fn(p1, p2, p3, p4) {} - + // good fn(options) {} ``` @@ -191,28 +193,28 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript // bad const values = {foo: 1}; - + function impureFunction(items) { const bar = 1; - + items.foo = items.a * bar + 2; - + return items.a; } - + const c = impureFunction(values); - + // good var values = {foo: 1}; - + function pureFunction (foo) { var bar = 1; - + foo = foo * bar + 2; - + return foo; } - + var c = pureFunction(values.foo); ``` @@ -231,10 +233,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod document.addEventListener('click', this.handleCallback) }, handleCallback() { - + } } - + // Good export class Foo { constructor() { @@ -253,12 +255,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript const users = [ { name: 'Foo' }, { name: 'Bar' } ]; - + // bad users.forEach((user, index) => { user.id = index; }); - + // good const usersWithId = users.map((user, index) => { return Object.assign({}, user, { id: index }); @@ -272,10 +274,10 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ```javascript // bad +'10' // 10 - + // good Number('10') // 10 - + // better parseInt('10', 10); ``` @@ -289,7 +291,7 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod <button class="add-user"> Add User </button> - + // good <button class="js-add-user"> Add User @@ -299,10 +301,12 @@ Do not use them anymore and feel free to remove them when refactoring legacy cod ### Vue.js #### `eslint-vue-plugin` + We default to [eslint-vue-plugin][eslint-plugin-vue], with the `plugin:vue/recommended`. Please check this [rules][eslint-plugin-vue-rules] for more documentation. #### Basic Rules + 1. The service has it's own file 1. The store has it's own file 1. Use a function in the bundle file to instantiate the Vue component: @@ -314,7 +318,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. new Component({}) } } - + // good document.addEventListener('DOMContentLoaded', () => new Vue({ el: '#element', @@ -336,7 +340,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. } } } - + // good class Store { constructor() { @@ -354,14 +358,14 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad import cardBoard from 'cardBoard.vue' - + components: { cardBoard, }; - + // good import CardBoard from 'cardBoard.vue' - + components: { CardBoard, }; @@ -373,13 +377,13 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad <component class="btn"> - + // good <component css-class="btn"> - + // bad <component myProp="prop" /> - + // good <component my-prop="prop" /> ``` @@ -387,6 +391,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. [#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 #### Alignment + 1. Follow these alignment styles for the template method: 1. With more than one attribute, all attributes should be on a new line: @@ -395,31 +400,31 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. // bad <component v-if="bar" param="baz" /> - + <button class="btn">Click me</button> - + // good <component v-if="bar" param="baz" /> - + <button class="btn"> Click me </button> ``` - + 1. The tag can be inline if there is only one attribute: ```javascript // good <component bar="bar" /> - + // good <component bar="bar" /> - + // bad <component bar="bar" /> @@ -434,7 +439,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. template: ` <button :class='style'>Button</button> ` - + // good template: ` <button :class="style">Button</button> @@ -447,7 +452,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. ```javascript // bad props: ['foo'] - + // good props: { foo: { @@ -467,7 +472,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. type: String, } } - + // good props: { foo: { @@ -490,7 +495,7 @@ On those a default key should not be provided. required: false, } } - + // good props: { foo: { @@ -499,7 +504,7 @@ On those a default key should not be provided. default: 'bar' } } - + // good props: { foo: { @@ -534,7 +539,7 @@ On those a default key should not be provided. ```javascript // bad <component v-on:click="eventHandler"/> - + // good <component @click="eventHandler"/> ``` @@ -544,7 +549,7 @@ On those a default key should not be provided. ```javascript // bad <component v-bind:class="btn"/> - + // good <component :class="btsn"/> ``` @@ -556,7 +561,7 @@ On those a default key should not be provided. ```javascript // bad <component></component> - + // good <component /> ``` @@ -650,7 +655,7 @@ Useful links: title="Some tooltip text"> Text </span> - + // good <span v-tooltip @@ -666,10 +671,10 @@ Useful links: ```javascript // bad <span data-original-title="tooltip text">Foo</span> - + // good <span title="tooltip text">Foo</span> - + $('span').tooltip('_fixTitle'); ``` diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index 417298205f5..0f1f079bdb4 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -69,6 +69,37 @@ For more information about rolling out changes using feature flags, refer to the [Rolling out changes using feature flags](rolling_out_changes_using_feature_flags.md) guide. +### Frontend + +For frontend code you can use the method `push_frontend_feature_flag`, which is +available to all controllers that inherit from `ApplicationController`. Using +this method you can expose the state of a feature flag as follows: + +```ruby +before_action do + push_frontend_feature_flag(:vim_bindings) +end + +def index + # ... +end + +def edit + # ... +end +``` + +You can then check for the state of the feature flag in JavaScript as follows: + +```javascript +if ( gon.features.vimBindings ) { + // ... +} +``` + +The name of the feature flag in JavaScript will always be camelCased, meaning +that checking for `gon.features.vim_bindings` would not work. + ### Specs In the test environment `Feature.enabled?` is stubbed to always respond to `true`, diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index 78931defa24..bfcca9cec7b 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -19,6 +19,10 @@ Guidance on topics related to development. Learn about all the dependencies that make up our frontend, including some of our own custom built libraries. +## [Modules](modules/index.md) + +Learn about all the internal JavaScript modules that make up our frontend. + ## [Style guides](style/index.md) Style guides to keep our code consistent. diff --git a/doc/development/new_fe_guide/modules/dirty_submit.md b/doc/development/new_fe_guide/modules/dirty_submit.md new file mode 100644 index 00000000000..6c03958b463 --- /dev/null +++ b/doc/development/new_fe_guide/modules/dirty_submit.md @@ -0,0 +1,23 @@ +# Dirty Submit + +> [Introduced][ce-21115] in GitLab 11.3. +> [dirty_submit][dirty-submit] + +## Summary + +Prevent submitting forms with no changes. + +Currently handles `input`, `textarea` and `select` elements. + +## Usage + +```js +import dirtySubmitFactory from './dirty_submit/dirty_submit_form'; + +new DirtySubmitForm(document.querySelector('form')); +// or +new DirtySubmitForm(document.querySelectorAll('form')); +``` + +[ce-21115]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21115 +[dirty-submit]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/dirty_submit/
\ No newline at end of file diff --git a/doc/development/new_fe_guide/modules/index.md b/doc/development/new_fe_guide/modules/index.md new file mode 100644 index 00000000000..0a7f2dbd819 --- /dev/null +++ b/doc/development/new_fe_guide/modules/index.md @@ -0,0 +1,5 @@ +# Modules + +* [DirtySubmit](dirty_submit.md) + + Disable form submits until there are unsaved changes.
\ No newline at end of file diff --git a/doc/install/installation.md b/doc/install/installation.md index 25aa5d3369d..9e2e58657f1 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -103,7 +103,7 @@ Is the system packaged Git too old? Remove it and compile from source. # When editing config/gitlab.yml (Step 5), change the git -> bin_path to /usr/local/bin/git -**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://github.com/gitlabhq/gitlabhq/issues/4866#issuecomment-32726573) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: +**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://gitlab.com/gitlab-org/gitlab-ce/issues/12754) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: sudo apt-get install -y postfix diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index fc7b97b3cc2..03f08abca7a 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -75,7 +75,8 @@ Please see the table below for some examples: | Latest stable version | Your version | Recommended upgrade path | Note | | -------------- | ------------ | ------------------------ | ---------------- | | 9.4.5 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.4.5` | `8.17.7` is the last version in version `8` | -| 10.1.4 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.5.8` -> `10.1.4` | `8.17.7` is the last version in version `8`, `9.5.8` is the last version in version `9` | +| 10.1.4 | 8.13.4 | `8.13.4 -> 8.17.7 -> 9.5.8 -> 10.1.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9` | +| 11.3.4 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9`, `10.8.7` is the last version in version `10` | More information about the release procedures can be found in our [release-tools documentation][rel]. You may also want to read our diff --git a/doc/update/11.3-to-11.4.md b/doc/update/11.3-to-11.4.md index 985239369d7..b50e21f27dd 100644 --- a/doc/update/11.3-to-11.4.md +++ b/doc/update/11.3-to-11.4.md @@ -80,8 +80,8 @@ More information can be found on the [yarn website](https://yarnpkg.com/en/docs/ ### 5. Update Go -NOTE: GitLab 11.0 and higher only supports Go 1.9.x and newer, and dropped support for Go -1.5.x through 1.8.x. Be sure to upgrade your installation if necessary. +NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go +1.9.x. Be sure to upgrade your installation if necessary. You can check which version you are running with `go version`. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 1b3fb9db4ec..097b18ad496 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -281,7 +281,7 @@ Additionally locked issues can not be reopened. [ce-14053]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14053 [ce-14061]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14061 [ce-14531]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14531 -[ce-31847]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/31847 +[ce-31847]: https://gitlab.com/gitlab-org/gitlab-ce/issues/31847 [resolve-discussion-button]: img/resolve_discussion_button.png [resolve-comment-button]: img/resolve_comment_button.png [discussion-view]: img/discussion_view.png diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 22ef11e4049..06b3779668b 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -12,9 +12,11 @@ to cherry-pick the changes introduced by that merge request.  -After you click that button, a modal will appear where you can choose to -cherry-pick the changes directly into the selected branch or you can opt to -create a new merge request with the cherry-pick changes +After you click that button, a modal will appear showing a [branch filter search box](../repository/branches/index.md#branch-filter-search-box) +where you can choose to either: + +- Cherry-pick the changes directly into the selected branch. +- Create a new merge request with the cherry-picked changes. ## Cherry-picking a Commit diff --git a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png Binary files differindex ac766c99935..3b3bf88df31 100644 --- a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png +++ b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 43ca498d006..f9ebf277125 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -205,9 +205,9 @@ have been marked as a **Work In Progress**. ## Merge request diff file navigation -The diff view has a persistent dropdown for file navigation. As you scroll through -diffs with a large number of files and/or many changes in those files, you can -easily jump to any changed file through the dropdown navigation. +The diff view has a file tree for file navigation. As you scroll through +diffs with a large number of files, you can easily jump to any changed file +using the file tree.  diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box.png b/doc/user/project/repository/branches/img/branch_filter_search_box.png Binary files differnew file mode 100644 index 00000000000..c4364ef39f4 --- /dev/null +++ b/doc/user/project/repository/branches/img/branch_filter_search_box.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 19417d91fec..e1d8345f415 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -6,6 +6,7 @@ Read through GiLab's branching documentation: - [Default branch](#default-branch) - [Protected branches](../../protected_branches.md#protected-branches) - [Delete merged branches](#delete-merged-branches) +- [Branch filter search box](#branch-filter-search-box) See also: @@ -40,5 +41,22 @@ this operation. It's particularly useful to clean up old branches that were not deleted automatically when a merge request was merged. + +## Branch filter search box + +> [Introduced][https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22166] in GitLab 11.5. + + + +This feature allows you to search and select branches quickly. Search results appear in the following order: + +- Branches with names that matched search terms exactly. +- Other branches with names that include search terms, sorted alphabetically. + +Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following: + +- `^feature` will only match branch names that begin with 'feature'. +- `feature$` will only match branch names that end with 'feature'. + [ce-6449]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6449 "Add button to delete all merged branches" [protected]: ../../protected_branches.md diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 4d016277824..ce79bfc0a03 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -85,12 +85,13 @@ You can live preview changes submitted to a new branch with With [GitLab Starter](https://about.gitlab.com/pricing/), you can also request [approval](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) from your managers. -To create, delete, and [branches](branches/index.md) via GitLab's UI: +To create, delete, and view [branches](branches/index.md) via GitLab's UI: - [Default branches](branches/index.md#default-branch) - [Create a branch](web_editor.md#create-a-new-branch) - [Protected branches](../protected_branches.md#protected-branches) - [Delete merged branches](branches/index.md#delete-merged-branches) +- [Branch filter search box](branches/index.md#branch-filter-search-box) Alternatively, you can use the [command line](../../../gitlab-basics/start-using-git.md#create-a-branch). @@ -169,7 +170,7 @@ vendored code, and most markup languages are excluded. ## Compare -Select branches to compare and view the changes inline: +Select branches to compare using the [branch filter search box](branches/index.md#branch-filter-search-box), then click the **Compare** button to view the changes inline:  |
