diff options
Diffstat (limited to 'doc/development/contributing')
| -rw-r--r-- | doc/development/contributing/community_roles.md | 11 | ||||
| -rw-r--r-- | doc/development/contributing/design.md | 6 | ||||
| -rw-r--r-- | doc/development/contributing/first_contribution.md | 340 | ||||
| -rw-r--r-- | doc/development/contributing/img/bot_ready.png | bin | 0 -> 9367 bytes | |||
| -rw-r--r-- | doc/development/contributing/img/changes_tab.png | bin | 0 -> 49899 bytes | |||
| -rw-r--r-- | doc/development/contributing/img/gdk_home.png | bin | 0 -> 16636 bytes | |||
| -rw-r--r-- | doc/development/contributing/img/mr_button.png | bin | 0 -> 14900 bytes | |||
| -rw-r--r-- | doc/development/contributing/img/new_merge_request.png | bin | 0 -> 9302 bytes | |||
| -rw-r--r-- | doc/development/contributing/img/ui_text_after.png | bin | 0 -> 4446 bytes | |||
| -rw-r--r-- | doc/development/contributing/img/ui_text_before.png | bin | 0 -> 5243 bytes | |||
| -rw-r--r-- | doc/development/contributing/index.md | 203 | ||||
| -rw-r--r-- | doc/development/contributing/issue_workflow.md | 324 | ||||
| -rw-r--r-- | doc/development/contributing/merge_request_workflow.md | 126 | ||||
| -rw-r--r-- | doc/development/contributing/style_guides.md | 24 |
14 files changed, 533 insertions, 501 deletions
diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md deleted file mode 100644 index 3c9362138c2..00000000000 --- a/doc/development/contributing/community_roles.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: 'index.md' -remove_date: '2023-05-08' ---- - -This document was moved to [another location](index.md). - -<!-- This redirect file can be deleted after <2023-05-08>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index aec487ed184..d68bc194266 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -12,7 +12,7 @@ Follow these guidelines when contributing or reviewing design and user interface advice and best practices for code review in general. The basis for most of these guidelines is [Pajamas](https://design.gitlab.com/), -GitLab design system. We encourage you to [contribute to Pajamas](https://design.gitlab.com/get-started/contribute/) +GitLab design system. We encourage you to [contribute to Pajamas](https://design.gitlab.com/get-started/contributing/) with additions and improvements. ## Merge request reviews @@ -73,7 +73,7 @@ Check visual design properties using your browser's _elements inspector_ ([Chrom guidelines. - _Optionally_ consider [dark mode](../../user/profile/preferences.md#dark-mode). [^1] - [^1]: You're not required to design for [dark mode](../../user/profile/preferences.md#dark-mode) while the feature is in [alpha](../../policy/alpha-beta-support.md#alpha-features). The [UX Foundations team](https://about.gitlab.com/direction/manage/foundations/) plans to improve the dark mode in the future. Until we integrate [Pajamas](https://design.gitlab.com/) components into the product and the underlying design strategy is in place to support dark mode, we cannot guarantee that we won't introduce bugs and debt to this mode. At your discretion, evaluate the need to create dark mode patches. + [^1]: You're not required to design for [dark mode](../../user/profile/preferences.md#dark-mode) while the feature is an [Experiment](../../policy/alpha-beta-support.md#experiment). The [UX Foundations team](https://about.gitlab.com/direction/manage/foundations/) plans to improve the dark mode in the future. Until we integrate [Pajamas](https://design.gitlab.com/) components into the product and the underlying design strategy is in place to support dark mode, we cannot guarantee that we won't introduce bugs and debt to this mode. At your discretion, evaluate the need to create dark mode patches. ### States @@ -127,7 +127,7 @@ At any moment, but usually _during_ or _after_ the design's implementation: - Contribute [issues to Pajamas](https://design.gitlab.com/get-started/contributing#contribute-an-issue) for additions or enhancements to the design system. -- Create issues with the [`~UX debt`](issue_workflow.md#technical-and-ux-debt) +- Create issues with the [`~UX debt`](../labels/index.md#technical-and-ux-debt) label for intentional deviations from the agreed-upon UX requirements due to time or feasibility challenges, linking back to the corresponding issues or merge requests. diff --git a/doc/development/contributing/first_contribution.md b/doc/development/contributing/first_contribution.md new file mode 100644 index 00000000000..0c4b5b21171 --- /dev/null +++ b/doc/development/contributing/first_contribution.md @@ -0,0 +1,340 @@ +--- +stage: none +group: Development +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tutorial: Make a GitLab contribution + +Anyone can contribute to the development of GitLab. + +Maybe you want to add functionality that you feel is missing. Or maybe +you noticed some UI text that you want to improve. + +This tutorial will walk you through the process of updating UI text +and related files by using the GitLab Development Kit and the GitLab community fork. +You can follow this example exactly to familiarize yourself with the process, +or you can choose other UI text to update. + +## Steps + +To make a contribution, you will: + +1. [Configure the GitLab Development Kit](#step-1-configure-the-gitlab-development-kit) +1. [Make your code updates](#step-2-change-the-code) +1. [Push your changes to the community fork](#step-3-push-your-changes-to-the-community-fork) +1. [Create a merge request](#step-4-create-a-merge-request) + +## Prerequisites + +On your local machine: + +- Ensure Git is installed. + (From the command line, type `git -v`. If you get a result, you have Git installed.) +- Install a source code editor, or decide which tool you're going to use to edit files. + +On GitLab.com: + +- Create an account. Ensure you can successfully sign in. +- Go to the [`gitlab-community/community-members` group](https://gitlab.com/gitlab-community/community-members) + and select **Request access**. This action will give you access to the GitLab + community fork, where you'll author your changes. + +## Step 1: Configure the GitLab Development Kit + +The GitLab Development Kit (GDK) is a local version of GitLab that's yours to play with. +It's just like an installation of self-managed GitLab. It includes sample projects you +can use to test functionality, and it gives you access to administrator functionality. +You can run it on your local machine, or use GitPod to run a remote version. + + + +If you've never used the GDK before, and you think you might contribute +more than once, you should install it. +If you already have a working GDK, you should +[update it to use the community fork](#an-existing-gdk-installation). + +### A new GDK installation + +Set aside about two hours to install the GDK. If all goes smoothly, it +should take about an hour to install. + +Sometimes the installation needs some tweaks to make it work, so you should +also set aside some time for troubleshooting. +It might seem like a lot of work, but after you have the GDK running, +you'll be able to contribute much more often and more easily. + +To install the GDK: + +1. Ensure you're on + [one of the supported platforms](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/#supported-platforms) + (macOS, Ubuntu, etc.). +1. Choose the directory where you want to install the GDK. + In this location, a repository called `gitlab-development-kit` will be created, + and the application will be installed. +1. From the command line, go to that directory. + In this example, we will use the `development` directory. + + ```shell + cd development + ``` + +1. Run the one-line installation command: + + ```shell + curl "https://gitlab.com/gitlab-org/gitlab-development-kit/-/raw/main/support/install" | bash + ``` + +1. For the message `Where would you like to install the GDK? [./gitlab-development-kit]`, + press Enter to accept the default location. + +1. For the message `Which GitLab repo URL would you like to clone?`, enter the GitLab community fork: + + ```shell + https://gitlab.com/gitlab-community/gitlab.git + ``` + +While the installation is running, copy any messages that are displayed. +If you have any problems with the installation, you can use this output as +part of troubleshooting. + +When the installation is complete: + +1. Go to the directory where the GDK was installed: + + ```shell + cd gitlab-development-kit + ``` + +1. Start the GDK: + + ```shell + gdk start + ``` + +1. Connect to the GDK by using the URL provided. It should be something like <http://127.0.0.1:3000>. +1. Use the username `root` and the password `5iveL!fe`. You will be prompted + to reset your password the first time you sign in. + +If you have any problems, try going to the `gitlab-development-kit/gitlab` +directory and running these commands: + +```shell +yarn install && bundle install +bundle exec rails db:migrate RAILS_ENV=development +``` + +From the `gitlab-development-kit` folder, you can also try running `gdk doctor`. + +For more advanced troubleshooting, see +[the troubleshooting docs](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/doc/troubleshooting). + +### An existing GDK installation + +If you have an existing GDK installation, you should update it so it's +using the community fork. + +1. Delete the existing `gitlab-development-kit/gitlab` directory. +1. Clone the community fork into that location: + + ```shell + cd gitlab-development-kit + git clone https://gitlab.com/gitlab-community/gitlab.git + ``` + +To confirm it was successful: + +1. Ensure the `gitlab-development-kit/gitlab` directory exists. +1. Go to the top `gitlab-development-kit` directory and run `gdk stop` and `gdk start`. + +If you get errors, run `gdk doctor` to troubleshoot. For more advanced troubleshooting, see +[the troubleshooting docs](https://gitlab.com/gitlab-org/gitlab-development-kit/-/tree/main/doc/troubleshooting). + +## Step 2: Change the code + +Now for the fun part. Let's edit some code. + +In this example, I found some UI text I'd like to change. +In the upper-right corner in GitLab, I selected my avatar and then **Preferences**. +I want to change this text: + + + +Other settings on the page start with the word `Customize` and skip the `This setting allows you to` part. +I'll update this phrase to match the others. + +1. Search the `gitlab-development-kit/gitlab` directory for the string `This setting allows you to customize`. + + The results show one `.haml` file, two `.md` files, one `.pot` file, and + several `.po` files. + +1. Open the `.haml` file. This file is where the UI text resides. +1. Update the string. In this case, I'll remove the words before `customize` + and start the word `customize` with a capital `C`. +1. Save the file. + +You can check that you were successful: + +- In the `gitlab-development-kit/gitlab` directory, type `git status` + to show the file you modified: + + ```shell + modified: app/views/profiles/preferences/show.html.haml + ``` + +- Refresh the web browser where you're viewing the GDK. + The changes should be displayed. Take a screenshot. + +  + +### Update the translation files + +English UI strings are localized into many languages. +These strings are saved in a `.pot` file, which you must update +any time you update UI text. + +To generate the localization file: + +1. Ensure you are in the `gitlab-development-kit/gitlab` directory. +1. Run the following command: + + ```shell + bin/rake gettext:compile + ``` + + After several minutes, a `.pot` file is generated in the `/locale` directory. + +Now, in the `gitlab-development-kit/gitlab` directory, if you type `git status` +you should have both files listed: + +```shell + modified: app/views/profiles/preferences/show.html.haml + modified: locale/gitlab.pot +``` + +For more information about localization, see [internationalization](../i18n/externalization.md). + +### Update the documentation + +Documentation for GitLab is published on <https://docs.gitlab.com>. +When you add or update a feature, you must update the docs as well. + +1. To find the documentation for a feature, the easiest thing is to search the + docs site. In this case, the setting is described on this documentation page: + + ```plaintext + https://docs.gitlab.com/ee/user/profile/preferences.html + ``` + +1. The URL shows you the location of the file in the `/doc` directory. + In this case, the location is: + + ```plaintext + doc/user/profile/preferences.md + ``` + +1. Go to this location in your local `gitlab` repository and update the `.md` file + and any related images. + +Now when you run `git status`, you should have something like: + +```plaintext + modified: app/views/profiles/preferences/show.html.haml + modified: doc/user/profile/img/profile-preferences-syntax-themes.png + modified: doc/user/profile/preferences.md + modified: locale/gitlab.pot +``` + +To view these changes in action, you can +[check out a merge request where these changes have already been made](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/116472). + +## Step 3: Push your changes to the community fork + +Now you're going to push your changes to the community fork. This is the next step +in getting your changes put into the main GitLab repository. + +1. Ensure you are in the `gitlab-development-kit/gitlab` directory. +1. Create a branch. You don't want to work in the `master` branch. + Instead, you want to create a branch for your work. In this example, + we're going to call the branch `ui-updates`. + + ```shell + git checkout -b ui-updates + ``` + +1. Add the files to the staging area. + + ```shell + git add . + ``` + +1. Provide a commit message. GitLab has somewhat strict + [commit message guidelines](merge_request_workflow.md#commit-messages-guidelines). + To be safe, a general rule is to use three to five words, start with a capital letter, + and do **not** end with a period. + + ```shell + git commit -m "Updating UI text + + Standardizing the text on this page so + that each area uses consistent language. + + Changelog: changed" + ``` + + The `Changelog: changed` is because we're changing an existing feature. If we were adding a feature, we'd + use `Changelog: added`. For details, see [changelog entries](../changelog.md). + +1. Push the changes to the community fork. At the same time, set the fork as your upstream, + so that it will be in sync for any future contributions. + + ```shell + git push --set-upstream origin ui-updates + ``` + +## Step 4: Create a merge request + +Now you're ready to push changes from the community fork to the main GitLab repository! + +1. Go to [the community fork on GitLab.com](https://gitlab.com/gitlab-community/gitlab). + You should see a message like this one: + +  + + Select **Create merge request**. + If you don't see this message, on the left sidebar, select **Merge requests > New merge request**. + +1. Take a look at the branch names. You should be merging from your branch + in the community fork to the `master` branch in the GitLab repository. + +  + +1. Fill out the information and then select **Save changes**. + Don't worry if your merge request is not complete. If you don't want anyone + from GitLab to review it, you can select the **Mark as draft** checkbox. + If you're not happy with the merge request after you create it, you can + close it, no harm done. + +1. Select the **Changes** tab. It should look something like this: + +  + + The red text shows the code before you made changes. The green shows what + the code looks like now. + +1. If you're happy with this merge request and want to start the review process, type + `@gitlab-bot ready` in a comment and then select **Comment**. + +  + +Someone from GitLab will look at your request and let you know what the next steps are. + +Now, any time you want to make a contribution to GitLab, you can just +go to the `gitlab-development-kit` folder and run `gdk update`. Then make +your changes in the `gitlab` directory and push them to the fork. + +If you need help at any point in the process, type `@gitlab-bot help` in a comment +or initiate a [mentor session](https://about.gitlab.com/community/contribute/mentor-sessions/) +on [Discord](https://discord.gg/gitlab). + +Congratulations on submitting your request, and thank you for your contribution! diff --git a/doc/development/contributing/img/bot_ready.png b/doc/development/contributing/img/bot_ready.png Binary files differnew file mode 100644 index 00000000000..85116c8957b --- /dev/null +++ b/doc/development/contributing/img/bot_ready.png diff --git a/doc/development/contributing/img/changes_tab.png b/doc/development/contributing/img/changes_tab.png Binary files differnew file mode 100644 index 00000000000..2158e9dd183 --- /dev/null +++ b/doc/development/contributing/img/changes_tab.png diff --git a/doc/development/contributing/img/gdk_home.png b/doc/development/contributing/img/gdk_home.png Binary files differnew file mode 100644 index 00000000000..7be4b9cd329 --- /dev/null +++ b/doc/development/contributing/img/gdk_home.png diff --git a/doc/development/contributing/img/mr_button.png b/doc/development/contributing/img/mr_button.png Binary files differnew file mode 100644 index 00000000000..5bf08b44412 --- /dev/null +++ b/doc/development/contributing/img/mr_button.png diff --git a/doc/development/contributing/img/new_merge_request.png b/doc/development/contributing/img/new_merge_request.png Binary files differnew file mode 100644 index 00000000000..34512d06dd2 --- /dev/null +++ b/doc/development/contributing/img/new_merge_request.png diff --git a/doc/development/contributing/img/ui_text_after.png b/doc/development/contributing/img/ui_text_after.png Binary files differnew file mode 100644 index 00000000000..3a54e7ef653 --- /dev/null +++ b/doc/development/contributing/img/ui_text_after.png diff --git a/doc/development/contributing/img/ui_text_before.png b/doc/development/contributing/img/ui_text_before.png Binary files differnew file mode 100644 index 00000000000..afd75a11ac2 --- /dev/null +++ b/doc/development/contributing/img/ui_text_before.png diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 55827e00e43..82a08246503 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -5,25 +5,23 @@ group: Development info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Contribute to GitLab +# Contribute to GitLab development Thank you for your interest in contributing to GitLab. This guide details how -to contribute to GitLab in a way that is easy for everyone. +to contribute to the development of GitLab. -For a first-time step-by-step guide to the contribution process, see our -[Contributing to GitLab](https://about.gitlab.com/community/contribute/) page. +For a first-time step-by-step guide, see [Tutorial: Make a GitLab contribution](first_contribution.md). -Looking for something to work on? See the -[How to contribute](#how-to-contribute) section for more information. - -GitLab comes in two flavors: +## How to contribute -- GitLab Community Edition (CE), our free and open source edition. -- GitLab Enterprise Edition (EE), which is our commercial edition. +1. Read the code of conduct. +1. Choose or create an issue to work on. +1. Set up the GitLab Development Kit. +1. Open your merge request. -Throughout this guide you will see references to CE and EE for abbreviation. +Your merge request is triaged, reviewed, and can then be incorporated into the product. -## Code of conduct +### Code of conduct We want to create a welcoming environment for everyone who is interested in contributing. For more information about our commitment to an open and welcoming environment, see our [Code of Conduct page](https://about.gitlab.com/community/contribute/code-of-conduct/). @@ -31,37 +29,83 @@ For more information about our commitment to an open and welcoming environment, Issues and merge requests should be in English and contain appropriate language for audiences of all ages. -## How to contribute +### Choose or create an issue + +If you know what you're going to work on, see if an issue exists. If it doesn't, +open a [new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue%5Bmilestone_id%5D=). +Select the appropriate template, and add all the necessary information about the work you are planning on doing. +That way you can get more guidance and support from GitLab team members. + +If you're not sure what to work on, you can: + +- View issues with the + [`~Seeking community contributions` label](../labels/index.md#label-for-community-contributors). +- Optimize tests. Use [RSpec profiling statistics](https://gitlab-org.gitlab.io/rspec_profiling_stats/) + to identify the slowest tests. These tests are good candidates for improving and checking if any + [best practices](../testing_guide/best_practices.md) can speed them up. + +When you find an issue, leave a comment on the issue you want to work on. +This helps the GitLab team and members of the wider GitLab community know that you will be working on that issue. + +For details, see [the issues workflow](issue_workflow.md). + +### Set up the GitLab Development Kit + +To write and test your code, you will use the GitLab Development Kit. -If you would like to contribute to GitLab: - -- Issues with the - [`~Seeking community contributions` label](issue_workflow.md#label-for-community-contributors) - are a great place to start. -- Optimizing our tests is another great opportunity to contribute. You can use - [RSpec profiling statistics](https://gitlab-org.gitlab.io/rspec_profiling_stats/) to identify - slowest tests. These tests are good candidates for improving and checking if any of - [best practices](../testing_guide/best_practices.md) - could speed them up. -- Consult the [Contribution Flow](#contribution-flow) section to learn the process. - -### Contribution flow - -The general flow of contributing to GitLab is: - -1. [Create a fork](../../user/project/repository/forking_workflow.md#creating-a-fork) - of GitLab. In some cases, you will want to set up the - [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) to - [develop against your fork](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/index.md#develop-in-your-own-gitlab-fork). -1. Make your changes in your fork. -1. When you're ready, [create a new merge request](../../user/project/merge_requests/creating_merge_requests.md). -1. In the merge request's description: - - Ensure you provide complete and accurate information. - - Review the provided checklist. -1. Once you're ready, mark your MR as ready for review with `@gitlab-bot ready`. - - This will add the `~"workflow::ready for review"` label, and then automatically assign a merge request coach as reviewer. - - If you know a relevant reviewer (for example, someone that was involved a related issue), you can also - assign them directly with `@gitlab-bot ready @username`. +1. [Request access](https://gitlab.com/gitlab-community/meta#request-access-to-community-forks) to the [GitLab Community fork](https://gitlab.com/gitlab-community/meta). Alternatively, you can create your own public fork, but will miss out on the [benefits of the community forks](https://gitlab.com/gitlab-community/meta#why). +1. Some GitLab projects have a detailed contributing guide located in the README or CONTRIBUTING files in the repo. Reviewing these files before setting up your development environment will help ensure you get off to a good start. +1. Do one of the following: + - To run the development environment locally, download and set up the + [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit). + See the [GDK README](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/README.md) for setup instructions + and [Troubleshooting](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/troubleshooting.md) if you get stuck. + + - GDK is heavy. If you need to build something fast, by trial and error, + consider doing so with an empty rails app and port it to GDK after. + + - To run a pre-configured GDK instance in the cloud, use [GDK with Gitpod](../../integration/gitpod.md). + From a project's repository, select the caret (angle-down) next to **Web IDE**, + and select **Gitpod** from the list. +1. If you want to contribute to the [website](https://about.gitlab.com/) or the [handbook](https://about.gitlab.com/handbook/), + go to the footer of any page and select **Edit in Web IDE** to open the [Web IDE](../../user/project/web_ide/index.md). + +### Open a merge request + +Now [Open a merge request](../../user/project/merge_requests/creating_merge_requests.md) +to merge your code and its documentation. The earlier you open a merge request, the sooner +you can get feedback. You can [mark it as a draft](../../user/project/merge_requests/drafts.md) +to signal that you’re not done yet. + +1. In the merge request, fill out all the information requested in the template, + like why you are introducing these changes and a link to the issue this merge request is attempting to close/fix. +1. [Add tests if needed](../testing_guide/best_practices.md), as well as [a changelog entry](../changelog.md). +1. If the change impacts users or admins, [update the documentation](../documentation/index.md). + +For details, see the [merge request workflow](merge_request_workflow.md). + +#### How community merge requests are triaged + +1. When you create a merge request, the [`@gitlab-bot`](https://gitlab.com/gitlab-bot) automatically applies + the ["~Community contribution"](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#ensure-quick-feedback-for-community-contributions) label. +1. In the 24-48 hours after you create the merge request, a + [Merge Request Coach](https://about.gitlab.com/handbook/marketing/community-relations/contributor-success/merge-request-coach-lifecycle.html) + will review your merge request and apply stage, group, and type labels. +1. If a merge request was not automatically assigned, ask for a review by typing `@gitlab-bot ready` in a comment. + If your code has not been assigned a reviewer within two working days of its initial submission, you can ask + for help with `@gitlab-bot help`. +1. The Merge Request Coach will assign the relevant reviewers or tackle the review themselves if possible. + +The goal is to have a merge request reviewed within a week after a reviewer is assigned. At times this may take longer due to high workload, holidays, or other reasons. +If you need to, look at the [team page](https://about.gitlab.com/company/team/) for the merge request coach who specializes in +the type of code you have written and mention them in the merge request. For example, if you have +written some front-end code, you should mention the frontend merge request coach. If +your code has multiple disciplines, you can mention multiple merge request coaches. + +For details about timelines and how you can request help or escalate a merge request, +see the [Wider Community Merge Request guide](https://about.gitlab.com/handbook/engineering/quality/merge-request-triage/). + +After your merge request is reviewed and merged, your changes will be deployed to GitLab.com and included in the next release! #### Review process @@ -95,64 +139,33 @@ Lastly, keep the following in mind when submitting merge requests: be merged, as well as some guidance. The maintainers will be open to discussion about how to change the code so it can be approved and merged in the future. -#### Getting attention on your merge request - -GitLab will do its best to review community contributions as quickly as possible. Specially -appointed developers review community contributions daily. Look at the -[team page](https://about.gitlab.com/company/team/) for the merge request coach who specializes in -the type of code you have written and mention them in the merge request. For example, if you have -written some front-end code, you should mention the frontend merge request coach. If -your code has multiple disciplines, you may mention multiple merge request coaches. - -GitLab receives a lot of community contributions. If your code has not been reviewed within two -working days of its initial submission, you can ask for help with `@gitlab-bot help`. - -#### Addition of external libraries - -When submitting code to GitLab, you may feel that your contribution requires the aid of an external -library. If your code includes an external library, please provide a link to the library, as well as -reasons for including it. - -Mention a maintainer in merge requests that contain: - -- More than 500 changes. -- Any major [breaking changes](../deprecation_guidelines/index.md). -- External libraries. - -If you are not sure who to mention, the reviewer will do this for you early in the merge request process. - -#### Issues workflow - -This [documentation](issue_workflow.md) outlines the current issue workflow: - -- [Issue triaging](issue_workflow.md#issue-triaging) -- [Labels](issue_workflow.md#labels) -- [Feature proposals](issue_workflow.md#feature-proposals) -- [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) -- [Technical debt in follow-up issues](issue_workflow.md#technical-debt-in-follow-up-issues) - -#### Merge requests workflow - -This [documentation](merge_request_workflow.md) outlines the current merge request process. - -- [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines-for-contributors) -- [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria) -- [Definition of done](merge_request_workflow.md#definition-of-done) -- [Dependencies](merge_request_workflow.md#dependencies) - ## Closing policy for issues and merge requests - For the criteria for closing issues, see [the Issue Triage handbook page](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#outdated-issues). - For the criteria for closing merge requests, see [the Merge Request Workflow](merge_request_workflow.md). -## Getting an Enterprise Edition License +## Getting an Enterprise Edition license -If you need a license for contributing to an EE-feature, see -[relevant information](https://about.gitlab.com/handbook/marketing/community-relations/code-contributor-program/operations/#contributing-to-the-gitlab-enterprise-edition-ee). +GitLab has two development platforms: -## Finding help +- GitLab Community Edition (CE), our free and open source edition. +- GitLab Enterprise Edition (EE), which is our commercial edition. -- [Get help](https://about.gitlab.com/get-help/). -- Join the community-run [Discord server](https://discord.com/invite/gitlab) and find other contributors in the `#contribute` channel. +If you need a license for contributing to an EE-feature, see +[relevant information](https://about.gitlab.com/handbook/marketing/community-relations/contributor-success/community-contributors-workflows.html#contributing-to-the-gitlab-enterprise-edition-ee). + +## Get help + +If you need any help while contributing to GitLab: + +- If you need help with a merge request or need help finding a reviewer: + - Don't hesitate to ask for help by typing `@gitlab-bot help` in a comment. + - Find reviewers and maintainers of GitLab projects in our + [handbook](https://about.gitlab.com/handbook/engineering/projects/) and + [mention](../../user/group/subgroups/index.md#mention-subgroups) them in a comment. +- Join the community on the [GitLab Community Discord](https://discord.com/invite/gitlab) and find other + contributors in the `#contribute` channel or [initiate a mentor session](https://about.gitlab.com/community/contribute/mentor-sessions/). +- For any other questions or feedback on contributing: + - Ping `@gitlab-org/community-relations/contributor-success` in a comment on your merge request or issue. + - Feel free to [make a new issue with the Contributor Success team](https://gitlab.com/gitlab-org/community-relations/contributor-success/team-task/-/issues/) sharing your experience. +- Did you run out of compute credits for your GitLab merge requests? Join the [GitLab community forks](https://gitlab.com/gitlab-community/meta) project. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index b55fef25302..50e87fc5341 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w **Before you submit an issue, [search the issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues)** for similar entries. Someone else might have already had the same bug or feature proposal. -If you find an existing issue, show your support with an award emoji and add your notes to the discussion. +If you find an existing issue, show your support with an emoji reaction and add your notes to the discussion. To submit a bug: @@ -37,300 +37,7 @@ the affected files to find someone. We also have triage automation in place, described [in our handbook](https://about.gitlab.com/handbook/engineering/quality/triage-operations/). -## Labels - -To allow for asynchronous issue handling, we use [milestones](https://gitlab.com/groups/gitlab-org/-/milestones) -and [labels](https://gitlab.com/gitlab-org/gitlab/-/labels). Leads and product managers handle most of the -scheduling into milestones. Labeling is a task for everyone. (For some projects, labels can be set only by GitLab team members and not by community contributors). - -Most issues will have labels for at least one of the following: - -- Type. For example: `~"type::feature"`, `~"type::bug"`, or `~"type::maintenance"`. -- Stage. For example: `~"devops::plan"` or `~"devops::create"`. -- Group. For example: `~"group::source code"`, `~"group::knowledge"`, or `~"group::editor"`. -- Category. For example: `~"Category:Code Analytics"`, `~"Category:DevOps Reports"`, or `~"Category:Templates"`. -- Feature. For example: `~wiki`, `~ldap`, `~api`, `~issues`, or `~"merge requests"`. -- Department: `~UX`, `~Quality` -- Team: `~"Technical Writing"`, `~Delivery` -- Specialization: `~frontend`, `~backend`, `~documentation` -- Release Scoping: `~Deliverable`, `~Stretch`, `~"Next Patch Release"` -- Priority: `~"priority::1"`, `~"priority::2"`, `~"priority::3"`, `~"priority::4"` -- Severity: `~"severity::1"`, `~"severity::2"`, `~"severity::3"`, `~"severity::4"` - -Please add `~"breaking change"` label if the issue can be considered as a [breaking change](../deprecation_guidelines/index.md). - -Please add `~security` label if the issue is related to application security. - -All labels, their meaning and priority are defined on the -[labels page](https://gitlab.com/gitlab-org/gitlab/-/labels). - -If you come across an issue that has none of these, and you're allowed to set -labels, you can _always_ add the type, stage, group, and often the category/feature labels. - -### Type labels - -Type labels are very important. They define what kind of issue this is. Every -issue should have one and only one. - -The SSOT for type and subtype labels is [available in the handbook](https://about.gitlab.com/handbook/engineering/metrics/#work-type-classification). - -A number of type labels have a priority assigned to them, which automatically -makes them float to the top, depending on their importance. - -Type labels are always lowercase, and can have any color, besides blue (which is -already reserved for category labels). - -The descriptions on the [labels page](https://gitlab.com/groups/gitlab-org/-/labels) -explain what falls under each type label. - -The GitLab handbook documents [when something is a bug](https://about.gitlab.com/handbook/product/product-processes/#bug-issues) and [when it is a feature request](https://about.gitlab.com/handbook/product/product-processes/#feature-issues). - -### Stage labels - -Stage labels specify which [stage](https://about.gitlab.com/handbook/product/categories/#hierarchy) the issue belongs to. - -#### Naming and color convention - -Stage labels respects the `devops::<stage_key>` naming convention. -`<stage_key>` is the stage key as it is in the single source of truth for stages at -<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml> -with `_` replaced with a space. - -For instance, the "Manage" stage is represented by the `~"devops::manage"` label in -the `gitlab-org` group since its key under `stages` is `manage`. - -The current stage labels can be found by [searching the labels list for `devops::`](https://gitlab.com/groups/gitlab-org/-/labels?search=devops::). - -These labels are [scoped labels](../../user/project/labels.md#scoped-labels) -and thus are mutually exclusive. - -The Stage labels are used to generate the [direction pages](https://about.gitlab.com/direction/) automatically. - -### Group labels - -Group labels specify which [groups](https://about.gitlab.com/company/team/structure/#product-groups) the issue belongs to. - -It's highly recommended to add a group label, as it's used by our triage -automation to -[infer the correct stage label](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues-and-merge-requests). - -#### Naming and color convention - -Group labels respects the `group::<group_key>` naming convention and -their color is `#A8D695`. -`<group_key>` is the group key as it is in the single source of truth for groups at -<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml>, -with `_` replaced with a space. - -For instance, the "Pipeline Execution" group is represented by the -~"group::pipeline execution" label in the `gitlab-org` group since its key -under `stages.manage.groups` is `pipeline_execution`. - -The current group labels can be found by [searching the labels list for `group::`](https://gitlab.com/groups/gitlab-org/-/labels?search=group::). - -These labels are [scoped labels](../../user/project/labels.md#scoped-labels) -and thus are mutually exclusive. - -You can find the groups listed in the [Product Stages, Groups, and Categories](https://about.gitlab.com/handbook/product/categories/) page. - -We use the term group to map down product requirements from our product stages. -As a team needs some way to collect the work their members are planning to be assigned to, we use the `~group::` labels to do so. - -### Category labels - -From the handbook's -[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy) -page: - -> Categories are high-level capabilities that may be a standalone product at -another company, such as Portfolio Management, for example. - -It's highly recommended to add a category label, as it's used by our triage -automation to -[infer the correct group and stage labels](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues). - -If you are an expert in a particular area, it makes it easier to find issues to -work on. You can also subscribe to those labels to receive an email each time an -issue is labeled with a category label corresponding to your expertise. - -#### Naming and color convention - -Category labels respects the `Category:<Category Name>` naming convention and -their color is `#428BCA`. -`<Category Name>` is the category name as it is in the single source of truth for categories at -<https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>. - -For instance, the "DevOps Reports" category is represented by the -~"Category:DevOps Reports" label in the `gitlab-org` group since its -`devops_reports.name` value is "DevOps Reports". - -If a category's label doesn't respect this naming convention, it should be specified -with [the `label` attribute](https://about.gitlab.com/handbook/marketing/digital-experience/website/#category-attributes) -in <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>. - -### Feature labels - -From the handbook's -[Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy) -page: - -> Features: Small, discrete functionalities, for example Issue weights. Some common -features are listed within parentheses to facilitate finding responsible PMs by keyword. - -It's highly recommended to add a feature label if no category label applies, as -it's used by our triage automation to -[infer the correct group and stage labels](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-labelling-of-issues). - -If you are an expert in a particular area, it makes it easier to find issues to -work on. You can also subscribe to those labels to receive an email each time an -issue is labeled with a feature label corresponding to your expertise. - -Examples of feature labels are `~wiki`, `~ldap`, `~api`, `~issues`, and `~"merge requests"`. - -#### Naming and color convention - -Feature labels are all-lowercase. - -### Facet labels - -To track additional information or context about created issues, developers may -add _facet labels_. Facet labels are also sometimes used for issue prioritization -or for measurements (such as time to close). An example of a facet label is the -~customer label, which indicates customer interest. - -### Department labels - -The current department labels are: - -- ~UX -- ~Quality - -### Team labels - -**Important**: Most of the historical team labels (like Manage or Plan) are -now deprecated in favor of [Group labels](#group-labels) and [Stage labels](#stage-labels). - -Team labels specify what team is responsible for this issue. -Assigning a team label makes sure issues get the attention of the appropriate -people. - -The current team labels are: - -- ~Delivery -- ~"Technical Writing" - -#### Naming and color convention - -Team labels are always capitalized so that they show up as the first label for -any issue. - -### Specialization labels - -These labels narrow the [specialization](https://about.gitlab.com/company/team/structure/#specialist) on a unit of work. - -- ~frontend -- ~backend -- ~documentation - -### Release scoping labels - -Release Scoping labels help us clearly communicate expectations of the work for the -release. There are three levels of Release Scoping labels: - -- ~Deliverable: Issues that are expected to be delivered in the current - milestone. -- ~Stretch: Issues that are a stretch goal for delivering in the current - milestone. If these issues are not done in the current release, they will - strongly be considered for the next release. -- ~"Next Patch Release": Issues to put in the next patch release. Work on these - first, and add the `~"Pick into X.Y"` label to the merge request, along with the - appropriate milestone. - -Each issue scheduled for the current milestone should be labeled ~Deliverable -or ~"Stretch". Any open issue for a previous milestone should be labeled -~"Next Patch Release", or otherwise rescheduled to a different milestone. - -### Priority labels - -We have the following priority labels: - -- ~"priority::1" -- ~"priority::2" -- ~"priority::3" -- ~"priority::4" - -Please refer to the issue triage [priority label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#priority) section in our handbook to see how it's used. - -### Severity labels - -We have the following severity labels: - -- ~"severity::1" -- ~"severity::2" -- ~"severity::3" -- ~"severity::4" - -Please refer to the issue triage [severity label](https://about.gitlab.com/handbook/engineering/quality/issue-triage/#severity) section in our handbook to see how it's used. - -### Label for community contributors - -There are many issues that have a clear solution with uncontroversial benefit to GitLab users. -However, GitLab might not have the capacity for all these proposals in the current roadmap. -These issues are labeled ~"Seeking community contributions" because we welcome merge requests to resolve them. - -Community contributors can submit merge requests for any issue they want, but -the ~"Seeking community contributions" label has a special meaning. It points to -changes that: - -1. We already agreed on, -1. Are well-defined, -1. Are likely to get accepted by a maintainer. - -We want to avoid a situation when a contributor picks an -~"Seeking community contributions" issue and then their merge request gets closed, -because we realize that it does not fit our vision, or we want to solve it in a -different way. - -We manually add the ~"Seeking community contributions" label to issues -that fit the criteria described above. -We do not automatically add this label, because it requires human evaluation. - -We recommend people that have never contributed to any open source project to -look for issues labeled `~"Seeking community contributions"` with a -[weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?sort=created_date&state=opened&label_name[]=Seeking+community+contributions&assignee_id=None&weight=1) or the `~"good for new contributors"` -[label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=good%20for%20new%20contributors&assignee_id=None) -attached to it. -More experienced contributors are very welcome to tackle -[any of them](https://gitlab.com/groups/gitlab-org/-/issues?sort=created_date&state=opened&label_name[]=Seeking+community+contributions&assignee_id=None). - -For more complex features that have a weight of 2 or more and clear scope, we recommend looking at issues -with the [label `~"Community Challenge"`](https://gitlab.com/gitlab-org/gitlab/-/issues?sort=created_date&state=opened&label_name[]=Seeking+community+contributions&label_name[]=Community+challenge). -If your MR for the `~"Community Challenge"` issue gets merged, you will also have a chance to win a custom -GitLab merchandise. - -If you've decided that you would like to work on an issue, please @-mention -the [appropriate product manager](https://about.gitlab.com/handbook/product/#who-to-talk-to-for-what) -as soon as possible. The product manager will then pull in appropriate GitLab team -members to further discuss scope, design, and technical considerations. This will -ensure that your contribution is aligned with the GitLab product and minimize -any rework and delay in getting it merged into main. - -GitLab team members who apply the ~"Seeking community contributions" label to an issue -should update the issue description with a responsible product manager, inviting -any potential community contributor to @-mention per above. - -### Stewardship label - -For issues related to the open source stewardship of GitLab, -there is the ~"stewardship" label. - -This label is to be used for issues in which the stewardship of GitLab -is a topic of discussion. For instance if GitLab Inc. is planning to add -features from GitLab EE to GitLab CE, related issues would be labeled with -~"stewardship". - -A recent example of this was the issue for -[bringing the time tracking API to GitLab CE](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/25517#note_20019084). +For information about which labels to apply to issues, see [Labels](../labels/index.md). ## Feature proposals @@ -399,31 +106,6 @@ The release manager will [update the notes](https://gitlab.com/gitlab-org/release-tools/blob/master/doc/pro-tips.md#update-the-regression-issue) in the regression issue as fixes are addressed. -## Technical and UX debt - -In order to track things that can be improved in the GitLab codebase, -we use the ~"technical debt" label in the [GitLab issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues). -We use the ~"UX debt" label when we choose to deviate from the MVC, in a way that harms the user experience. - -These labels should be added to issues that describe things that can be improved, -shortcuts that have been taken, features that need additional attention, and all -other things that have been left behind due to high velocity of development. -For example, code that needs refactoring should use the ~"technical debt" label, -something that didn't ship according to our Design System guidelines should -use the ~"UX debt" label. - -Everyone can create an issue, though you may need to ask for adding a specific -label, if you do not have permissions to do it by yourself. Additional labels -can be combined with these labels, to make it easier to schedule -the improvements for a release. - -Issues tagged with these labels have the same priority like issues -that describe a new feature to be introduced in GitLab, and should be scheduled -for a release by the appropriate person. - -Make sure to mention the merge request that the ~"technical debt" issue or -~"UX debt" issue is associated with in the description of the issue. - ## Technical debt in follow-up issues It's common to discover technical debt during development of a new feature. In @@ -459,6 +141,6 @@ and assignee. The maintainer must always agree before an outstanding discussion is resolved in this manner, and will be the one to create the issue. The title and description should be of the same quality as those created -[in the usual manner](#technical-and-ux-debt) - in particular, the issue title +[in the usual manner](../labels/index.md#technical-and-ux-debt) - in particular, the issue title **must not** begin with `Follow-up`! The creating maintainer should also expect to be involved in some capacity when work begins on the follow-up issue. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 01bfdae5999..7a0269e551d 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -9,11 +9,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w We welcome merge requests from everyone, with fixes and improvements to GitLab code, tests, and documentation. The issues that are specifically suitable -for community contributions have the [`Seeking community contributions`](issue_workflow.md#label-for-community-contributors) +for community contributions have the +[`Seeking community contributions`](../labels/index.md#label-for-community-contributors) label, but you are free to contribute to any issue you want. +## Working from issues + +If you find an issue, please submit a merge request with a fix or improvement, +if you can, and include tests. + +If you want to add a new feature that is not labeled, it is best to first create +an issue (if there isn't one already) and leave a comment asking for it +to be labeled as `Seeking community contributions`. See the [feature proposals](issue_workflow.md#feature-proposals) +section. + +If you don't know how to fix the issue but can write a test that exposes the +issue, we will accept that as well. In general, bug fixes that include a +regression test are merged quickly. New features without proper tests +might be slower to receive feedback. + +If you are new to GitLab development (or web development in general), see the +[how to contribute](index.md#how-to-contribute) section to get started with +some potentially easy issues. + +## Merge request ownership + If an issue is marked for the current milestone at any time, even -when you are working on it, a GitLab team member may take over the merge request to ensure the work is finished before the release date. +when you are working on it, a GitLab team member may take over the merge request to ensure the work is finished before the release date. If a contributor is no longer actively working on a submitted merge request, we can: @@ -31,79 +53,27 @@ we credit the original author by adding a changelog entry crediting the author and optionally include the original author on at least one of the commits within the MR. -If you want to add a new feature that is not labeled, it is best to first create -an issue (if there isn't one already) and leave a comment asking for it -to be labeled as `Seeking community contributions`. See the [feature proposals](issue_workflow.md#feature-proposals) -section. - -Merge requests should be submitted to the appropriate project at GitLab.com, for example -[GitLab](https://gitlab.com/gitlab-org/gitlab/-/merge_requests), -[GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests), or -[Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests). - -If you are new to GitLab development (or web development in general), see the -[how to contribute](index.md#how-to-contribute) section to get started with -some potentially easy issues. - -To start developing GitLab, download the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) -and see the [Development section](../../index.md) for the required guidelines. - ## Merge request guidelines for contributors -If you find an issue, please submit a merge request with a fix or improvement, -if you can, and include tests. +For a walkthrough of the contribution process, see [Tutorial: Make a GitLab contribution](first_contribution.md). -NOTE: -Consider placing your code behind a feature flag if you think it might affect production availability. -Not sure? Read [When to use feature flags](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags). +### Best practices -If the change is non-trivial, we encourage you to -start a discussion with [a product manager or a member of the team](https://about.gitlab.com/handbook/product/categories/). -You can do -this by tagging them in an MR before submitting the code for review. Talking -to team members can be helpful when making design decisions. Communicating the -intent behind your changes can also help expedite merge request reviews. +- If the change is non-trivial, we encourage you to start a discussion with + [a product manager or a member of the team](https://about.gitlab.com/handbook/product/categories/). + You can do this by tagging them in an MR before submitting the code for review. Talking + to team members can be helpful when making design decisions. Communicating the + intent behind your changes can also help expedite merge request reviews. -If -you don't know how to fix the issue but can write a test that exposes the -issue, we will accept that as well. In general, bug fixes that include a -regression test are merged quickly. New features without proper tests -might be slower to receive feedback. +- Consider placing your code behind a feature flag if you think it might affect production availability. + Not sure? Read [When to use feature flags](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#when-to-use-feature-flags). -To create a merge request: - -1. [Fork](../../user/project/repository/forking_workflow.md) the project into - your personal namespace (or group) on GitLab.com. -1. Create a feature branch in your fork (don't work off your [default branch](../../user/project/repository/branches/default.md)). -1. Follow the [commit messages guidelines](#commit-messages-guidelines). -1. If you have multiple commits, combine them into a few logically organized commits. -1. Push the commits to your working branch in your fork. -1. Submit a merge request (MR) against the default branch of the upstream project. -1. The MR title should describe the change you want to make. -1. The MR description should give a reason for your change. - 1. If you are contributing code, fill in the description according to the default - template already provided in the "Description" field. - 1. If you are contributing documentation, choose `Documentation` from the - "Choose a template" menu and fill in the description according to the template. - 1. Use the syntax `Solves #XXX`, `Closes #XXX`, or `Refs #XXX` to mention the issues your merge - request addresses. Referenced issues do not [close automatically](../../user/project/issues/managing_issues.md#closing-issues-automatically). - You must close them manually once the merge request is merged. -1. If you're allowed to, set a relevant milestone and [labels](issue_workflow.md). - MR labels should generally match the corresponding issue (if there is one). - The group label should reflect the group that executed or coached the work, - not necessarily the group that owns the feature. -1. Read and adhere to - [The responsibility of the merge request author](../code_review.md#the-responsibility-of-the-merge-request-author). -1. Read and follow - [Having your merge request reviewed](../code_review.md#having-your-merge-request-reviewed). -1. Make sure the merge request meets the [Definition of done](#definition-of-done). - -If you would like quick feedback on your merge request feel free to mention someone -from the [core team](https://about.gitlab.com/community/core-team/) or one of the -[merge request coaches](https://about.gitlab.com/company/team/). When having your code reviewed -and when reviewing merge requests, please keep the [code review guidelines](../code_review.md) -in mind. And if your code also makes changes to the database, or does expensive queries, -check the [database review guidelines](../database_review.md). +- If you would like quick feedback on your merge request feel free to mention someone + from the [core team](https://about.gitlab.com/community/core-team/) or one of the + [merge request coaches](https://about.gitlab.com/company/team/). When having your code reviewed + and when reviewing merge requests, please keep the [code review guidelines](../code_review.md) + in mind. And if your code also makes changes to the database, or does expensive queries, + check the [database review guidelines](../database_review.md). ### Keep it simple @@ -191,6 +161,10 @@ To make sure that your merge request can be approved, please ensure that it meet the contribution acceptance criteria below: 1. The change is as small as possible. +1. If the merge request contains more than 500 changes: + - Explain the reason + - Mention a maintainer +1. Mention any major [breaking changes](../deprecation_guidelines/index.md). 1. Include proper tests and make all tests pass (unless it contains a test exposing a bug in existing code). Every new class should have corresponding unit tests, even if the class is exercised at a higher level, such as a feature test. @@ -268,6 +242,15 @@ requirements. There isn't a way to know anything about our customers' data on their [self-managed instances](../../subscriptions/self_managed/index.md), so keep that in mind for any data implications with your merge request. +1. Consider self-managed functionality and upgrade paths. The change should consider both: + + - If additional work needs to be done for self-managed availability, and + - If the change requires a [required stop](../database/required_stops.md) when upgrading GitLab versions. + + Upgrade stops are sometimes requested when a GitLab code change is dependent + upon a background migration being already complete. Ideally, changes causing required + upgrade stops should be held for the next major release, or + [at least a 3 milestones notice in advance if unavoidable](../../update/index.md#upgrade-paths). ### Testing @@ -366,3 +349,8 @@ issue) that are incremental improvements, such as: Tag a merge request with ~"Stuff that should Just Work" to track work in this area. + +## Related topics + +- [The responsibility of the merge request author](../code_review.md#the-responsibility-of-the-merge-request-author) +- [Having your merge request reviewed](../code_review.md#having-your-merge-request-reviewed) diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 28ce8e6ff4b..d24875e559a 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -5,7 +5,7 @@ group: Development info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Style guides +# Development style guides ## Editor/IDE styling standardization @@ -30,7 +30,9 @@ We were using Overcommit prior to Lefthook, so you may want to uninstall it firs ### Install Lefthook -1. Install the `lefthook` Ruby gem: +1. You can install lefthook in [different ways](https://github.com/evilmartians/lefthook/blob/master/docs/install.md#install-lefthook). + If you do not choose to install it globally (e.g. via Homebrew or package managers), and only want to use it for the GitLab project, + you can install the Ruby gem via: ```shell bundle install @@ -39,12 +41,18 @@ We were using Overcommit prior to Lefthook, so you may want to uninstall it firs 1. Install Lefthook managed Git hooks: ```shell + # If installed globally + lefthook install + # Or if installed via ruby gem bundle exec lefthook install ``` 1. Test Lefthook is working by running the Lefthook `pre-push` Git hook: ```shell + # If installed globally + lefthook run pre-push + # Or if installed via ruby gem bundle exec lefthook run pre-push ``` @@ -57,6 +65,18 @@ Lefthook is configured with a combination of: - Project configuration in [`lefthook.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lefthook.yml). - Any [local configuration](https://github.com/evilmartians/lefthook/blob/master/README.md#local-config). +### Lefthook auto-fixing files + +We have a custom lefthook target to run all the linters with auto-fix capabilities, +but just on the files which changed in your branch. + +```shell +# If installed globally +lefthook run auto-fix +# Or if installed via ruby gem +bundle exec lefthook run auto-fix +``` + ### Disable Lefthook temporarily To disable Lefthook temporarily, you can set the `LEFTHOOK` environment variable to `0`. For instance: |
