summaryrefslogtreecommitdiff
path: root/doc/development/contributing
diff options
context:
space:
mode:
authorGitLab Bot <gitlab-bot@gitlab.com>2023-04-20 11:43:17 +0000
committerGitLab Bot <gitlab-bot@gitlab.com>2023-04-20 11:43:17 +0000
commitdfc94207fec2d84314b1a5410cface22e8b369bd (patch)
treec54022f61ced104305889a64de080998a0dc773b /doc/development/contributing
parentb874efeff674f6bf0355d5d242ecf81c6f7155df (diff)
downloadgitlab-ce-dfc94207fec2d84314b1a5410cface22e8b369bd.tar.gz
Add latest changes from gitlab-org/gitlab@15-11-stable-eev15.11.0-rc42
Diffstat (limited to 'doc/development/contributing')
-rw-r--r--doc/development/contributing/design.md2
-rw-r--r--doc/development/contributing/first_contribution.md340
-rw-r--r--doc/development/contributing/img/bot_ready.pngbin0 -> 9367 bytes
-rw-r--r--doc/development/contributing/img/changes_tab.pngbin0 -> 49899 bytes
-rw-r--r--doc/development/contributing/img/gdk_home.pngbin0 -> 56874 bytes
-rw-r--r--doc/development/contributing/img/mr_button.pngbin0 -> 14900 bytes
-rw-r--r--doc/development/contributing/img/new_merge_request.pngbin0 -> 9302 bytes
-rw-r--r--doc/development/contributing/img/ui_text_after.pngbin0 -> 4446 bytes
-rw-r--r--doc/development/contributing/img/ui_text_before.pngbin0 -> 5243 bytes
-rw-r--r--doc/development/contributing/index.md36
-rw-r--r--doc/development/contributing/merge_request_workflow.md84
11 files changed, 375 insertions, 87 deletions
diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md
index 210370f9816..d68bc194266 100644
--- a/doc/development/contributing/design.md
+++ b/doc/development/contributing/design.md
@@ -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
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.
+
+![GDK](img/gdk_home.png)
+
+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:
+
+![UI text](img/ui_text_before.png)
+
+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.
+
+ ![UI text](img/ui_text_after.png)
+
+### 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:
+
+ ![Create merge request banner](img/mr_button.png)
+
+ 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.
+
+ ![New merge request](img/new_merge_request.png)
+
+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:
+
+ ![Changes tab](img/changes_tab.png)
+
+ 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**.
+
+ ![GitLab bot ready comment](img/bot_ready.png)
+
+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
new file mode 100644
index 00000000000..85116c8957b
--- /dev/null
+++ b/doc/development/contributing/img/bot_ready.png
Binary files differ
diff --git a/doc/development/contributing/img/changes_tab.png b/doc/development/contributing/img/changes_tab.png
new file mode 100644
index 00000000000..2158e9dd183
--- /dev/null
+++ b/doc/development/contributing/img/changes_tab.png
Binary files differ
diff --git a/doc/development/contributing/img/gdk_home.png b/doc/development/contributing/img/gdk_home.png
new file mode 100644
index 00000000000..77505850609
--- /dev/null
+++ b/doc/development/contributing/img/gdk_home.png
Binary files differ
diff --git a/doc/development/contributing/img/mr_button.png b/doc/development/contributing/img/mr_button.png
new file mode 100644
index 00000000000..5bf08b44412
--- /dev/null
+++ b/doc/development/contributing/img/mr_button.png
Binary files differ
diff --git a/doc/development/contributing/img/new_merge_request.png b/doc/development/contributing/img/new_merge_request.png
new file mode 100644
index 00000000000..34512d06dd2
--- /dev/null
+++ b/doc/development/contributing/img/new_merge_request.png
Binary files differ
diff --git a/doc/development/contributing/img/ui_text_after.png b/doc/development/contributing/img/ui_text_after.png
new file mode 100644
index 00000000000..3a54e7ef653
--- /dev/null
+++ b/doc/development/contributing/img/ui_text_after.png
Binary files differ
diff --git a/doc/development/contributing/img/ui_text_before.png b/doc/development/contributing/img/ui_text_before.png
new file mode 100644
index 00000000000..afd75a11ac2
--- /dev/null
+++ b/doc/development/contributing/img/ui_text_before.png
Binary files differ
diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md
index 6a9dd34e703..ef3242b89c2 100644
--- a/doc/development/contributing/index.md
+++ b/doc/development/contributing/index.md
@@ -8,10 +8,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Contribute to GitLab
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 in a way that is easy for everyone.
-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 to the contribution process for development, see [Tutorial: Make a GitLab contribution](first_contribution.md).
+
+For other ways to contribute see our [Contributing to GitLab](https://about.gitlab.com/community/contribute/) page.
Looking for something to work on? See the
[How to contribute](#how-to-contribute) section for more information.
@@ -43,27 +44,10 @@ If you would like to contribute to GitLab:
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. [Read about](https://gitlab.com/gitlab-community/meta) and [request access](https://gitlab.com/gitlab-community/meta#request-access-to-community-forks)
- to the GitLab Community forks. In some cases, you will want to set up the
- [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) to
- [develop against the GitLab community fork](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/index.md#develop-in-your-own-gitlab-fork).
-1. Create a feature branch and make changes in the [GitLab community fork](https://gitlab.com/gitlab-community/gitlab).
-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`.
+For a walkthrough of the contribution process, see [Tutorial: Make a GitLab contribution](first_contribution.md).
-#### Review process
+### Review process
When you submit code to GitLab, we really want it to get merged! However, we always review
submissions carefully, and this takes time. Code submissions will usually be reviewed by two
@@ -95,7 +79,7 @@ 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
+### 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
@@ -119,7 +103,7 @@ This [documentation](issue_workflow.md) outlines the current issue workflow:
- [Technical and UX debt](../labels/index.md#technical-and-ux-debt)
- [Technical debt in follow-up issues](issue_workflow.md#technical-debt-in-follow-up-issues)
-#### Merge requests workflow
+### Merge requests workflow
This [documentation](merge_request_workflow.md) outlines the current merge request process.
@@ -136,9 +120,9 @@ This [documentation](merge_request_workflow.md) outlines the current merge reque
## 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).
+[relevant information](https://about.gitlab.com/handbook/marketing/community-relations/contributor-success/community-contributors-workflows.html#contributing-to-the-gitlab-enterprise-edition-ee).
## Finding help
- [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.
+- Join the community-run [Discord server](https://discord.gg/gitlab) and find other contributors in the `#contribute` channel.
diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md
index f39d93a39bc..a67459e02ed 100644
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
@@ -55,66 +55,25 @@ within the MR.
## Merge request guidelines for contributors
-### Getting started
-
-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).
-
-To start developing GitLab locally, download the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit)
-and see the [Development section](../../index.md) for the required guidelines.
-
-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).
-
-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.
-
-### Creating a merge request
-
-To create a merge request:
-
-1. [Read about](https://gitlab.com/gitlab-community/meta) and [request access](https://gitlab.com/gitlab-community/meta#request-access-to-community-forks)
- to the GitLab Community forks. In some cases, you will want to set up the
- [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) to
- [develop against the GitLab community fork](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/index.md#develop-in-your-own-gitlab-fork).
-1. Create a feature branch in the [GitLab community fork](https://gitlab.com/gitlab-community/gitlab)
- (don't work off the [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 the 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).
+For a walkthrough of the contribution process, see [Tutorial: Make a GitLab contribution](first_contribution.md).
+
+### 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.
+
+- 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).
+
+- 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
@@ -381,3 +340,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)