From 580bc4615412b868d83e9428a56484cde9ca53a4 Mon Sep 17 00:00:00 2001 From: Suzanne Selhorn <sselhorn@gitlab.com> Date: Thu, 6 Apr 2023 21:17:28 +0000 Subject: [PATCH] Removed duplicate instructions Because right now we provide the same information in many places and we should try to standardize on one location, SSoT. Related to: https://gitlab.com/gitlab-org/technical-writing/-/issues/744 --- doc/development/contributing/index.md | 25 +----- .../contributing/merge_request_workflow.md | 84 ++++++------------- 2 files changed, 28 insertions(+), 81 deletions(-) diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index e4768bdb97fcb..c436be5edd1b5 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -43,27 +43,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 +For a walkthrough of the contribution process, see [Tutorial: Make a GitLab contribution](first_contribution.md). -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`. - -#### 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 +78,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 +102,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. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index f39d93a39bcf2..a67459e02ed0e 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) -- GitLab