kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Merge branch 'docs-merge-requests' into 'master'

Browse source 
Docs: Cleaning up the merge request workflow

Closes #51355

See merge request gitlab-org/gitlab-ce!24559
This commit is contained in:
Marcia Ramos 2019-03-13 18:44:04 +00:00
commit dd6af1262c
2 changed files with 164 additions and 151 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/development/contributing/index.md
View file

@ -119,6 +119,7 @@ This [documentation](merge_request_workflow.md) outlines the current merge reque
- [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines) - [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines)
- [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria) - [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria)
- [Definition of done](merge_request_workflow.md#definition-of-done) - [Definition of done](merge_request_workflow.md#definition-of-done)
- [Dependencies](merge_request_workflow.md#dependencies)
## Style guides ## Style guides

314
doc/development/contributing/merge_request_workflow.md
View file

@ -1,91 +1,95 @@
# Merge requests # Merge requests
We welcome merge requests with fixes and improvements to GitLab code, tests, We welcome merge requests from everyone, with fixes and improvements
and/or documentation. The issues that are specifically suitable for to GitLab code, tests, and documentation. The issues that are specifically suitable
community contributions are listed with for community contributions are listed with the [`Accepting merge requests`](issue_workflow.md#label-for-community-contributors)
[the `Accepting merge requests` label](issue_workflow.md#label-for-community-contributors), label, but you are free to contribute to any issue you want.
but you are free to contribute to any other issue you want.
Please note that if an issue is marked for the current milestone either before Please note that if an issue is marked for the current milestone at any time, even
or while you are working on it, a team member may take over the merge request when you are working on it, a GitLab Inc. team member may take over the merge request
in order to ensure the work is finished before the release date. in order to ensure the work is finished before the release date.
If you want to add a new feature that is not labeled it is best to first create If you want to add a new feature that is not labeled, it is best to first create
a feedback issue (if there isn't one already) and leave a comment asking for it an issue (if there isn't one already) and leave a comment asking for it
to be marked as `Accepting Merge Requests`. Please include screenshots or to be marked as `Accepting Merge Requests`. Please include screenshots or
wireframes if the feature will also change the UI. wireframes of the proposed feature if it will also change the UI.
Merge requests should be opened at [GitLab.com][gitlab-mr-tracker]. Merge requests should be submitted to the appropriate project at GitLab.com, for example
[GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests),
[GitLab EE](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests),
[GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests),
[GitLab Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests), etc.
If you are new to GitLab development (or web development in general), see the If you are new to GitLab development (or web development in general), see the
[I want to contribute!](index.md#i-want-to-contribute) section to get you started with [I want to contribute!](index.md#i-want-to-contribute) section to get started with
some potentially easy issues. some potentially easy issues.
To start with GitLab development download the [GitLab Development Kit][gdk] and To start developing GitLab, download the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit)
see the [Development section](../../README.md) for some guidelines. and see the [Development section](../../README.md) for the required guidelines.
[gitlab-mr-tracker]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests
[gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit
## Merge request guidelines ## Merge request guidelines
If you can, please submit a merge request with the fix or improvements If you find an issue, please submit a merge request with a fix or improvement, if
including tests. If you don't know how to fix the issue but can write a test you can, and include tests. 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 that exposes the issue, we will accept that as well. In general, bug fixes that
include a regression test are merged quickly while new features without proper include a regression test are merged quickly, while new features without proper
tests are least likely to receive timely feedback. The workflow to make a merge tests might be slower to receive feedback. The workflow to make a merge
request is as follows: request is as follows:
1. Fork the project into your personal space on GitLab.com 1. [Fork](../../workflow/forking_workflow.md#creating-a-fork) the project into
1. Create a feature branch, branch away from `master` your personal namespace (or group) on GitLab.com.
1. Write [tests](https://docs.gitlab.com/ee/development/rake_tasks.html#run-tests) and code 1. Create a feature branch in your fork (don't work off `master`).
1. [Generate a changelog entry with `bin/changelog`][changelog] 1. Write [tests](../rake_tasks.md#run-tests) and code.
1. [Generate a changelog entry with `bin/changelog`](../changelog.md)
1. If you are writing documentation, make sure to follow the 1. If you are writing documentation, make sure to follow the
[documentation guidelines][doc-guidelines] [documentation guidelines](../documentation/index.md).
1. If you have multiple commits please combine them into a few logically 1. Follow the [commit messages guidelines](#commit-messages-guidelines).
organized commits by [squashing them][git-squash] 1. If you have multiple commits, combine them into a few logically organized
1. Push the commit(s) to your fork commits by [squashing them](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing),
1. Submit a merge request (MR) to the `master` branch but do not change the commit history if you're working on shared branches though.
1. Your merge request needs at least 1 approval but feel free to require more. 1. Push the commit(s) to your working branch in your fork.
For instance if you're touching backend and frontend code, it's a good idea 1. Submit a merge request (MR) to the `master` branch in the main GitLab project.
1. Your merge request needs at least 1 approval, but feel free to require more.
For instance if you're touching both backend and frontend code, it's a good idea
to require 2 approvals: 1 from a backend maintainer and 1 from a frontend to require 2 approvals: 1 from a backend maintainer and 1 from a frontend
maintainer maintainer.
1. You don't have to select any approvers, but you can if you really want 1. If you're submitting changes to documentation, you'll need approval from a technical
specific people to approve your merge request writer, based on the appropriate [product category](https://about.gitlab.com/handbook/product/categories/).
1. The MR title should describe the change you want to make Only assign the MR to them when it's ready for docs review.
1. The MR description should give a motive for your change and the method you 1. You don't have to select any specific approvers, but you can if you really want
used to achieve it. specific people to approve your merge request.
1. If you are contributing code, fill in the template already provided in the 1. The MR title should describe the change you want to make.
"Description" field. 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 1. If you are contributing documentation, choose `Documentation` from the
"Choose a template" menu and fill in the template. "Choose a template" menu and fill in the description according to the template.
1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
`Closes #XXX` syntax to auto-close the issue(s) once the merge request will `Closes #XXX` syntax to [auto-close](../../user/project/issues/automatic_issue_closing.md)
be merged. the issue(s) once the merge request is merged.
1. If you're allowed to, set a relevant milestone and labels 1. If you're allowed to (Core team members, for example), set a relevant milestone
1. If the MR changes the UI it should include *Before* and *After* screenshots and [labels](issue_workflow.md).
1. If the MR changes CSS classes please include the list of affected pages, 1. If the MR changes the UI, it should include *Before* and *After* screenshots.
`grep css-class ./app -R` 1. If the MR changes CSS classes, please include the list of affected pages, which
1. Be prepared to answer questions and incorporate feedback even if requests can be found by running `grep css-class ./app -R`.
for this arrive weeks or months after your MR submission 1. Be prepared to answer questions and incorporate feedback into your MR with new
1. If a discussion has been addressed, select the "Resolve discussion" button commits. Once you have fully addressed a suggestion from a reviewer, click the
beneath it to mark it resolved. "Resolve discussion" button beneath it to mark it resolved.
1. If your MR touches code that executes shell commands, reads or opens files or 1. The merge request author resolves only the discussions they have fully addressed.
If there's an open reply or discussion, a suggestion, a question, or anything else,
the discussion should be left to be resolved by the reviewer.
1. If your MR touches code that executes shell commands, reads or opens files, or
handles paths to files on disk, make sure it adheres to the handles paths to files on disk, make sure it adheres to the
[shell command guidelines](../shell_commands.md) [shell command guidelines](../shell_commands.md)
1. If your code creates new files on disk please read the 1. If your code creates new files on disk please read the
[shared files guidelines](../shared_files.md). [shared files guidelines](../shared_files.md).
1. When writing commit messages please follow
[these](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
[guidelines](http://chris.beams.io/posts/git-commit/).
1. If your merge request adds one or more migrations, make sure to execute all 1. If your merge request adds one or more migrations, make sure to execute all
migrations on a fresh database before the MR is reviewed. If the review leads migrations on a fresh database before the MR is reviewed. If the review leads
to large changes in the MR, do this again once the review is complete. to large changes in the MR, execute the migrations again once the review is complete.
1. For more complex migrations, write tests. 1. Write tests for more complex migrations.
1. Merge requests **must** adhere to the [merge request performance 1. Merge requests **must** adhere to the [merge request performance guidelines](../merge_request_performance_guidelines.md).
guidelines](../merge_request_performance_guidelines.md). 1. For tests that use Capybara, read
1. For tests that use Capybara or PhantomJS, see this [article on how [how to write reliable, asynchronous integration tests](https://robots.thoughtbot.com/write-reliable-asynchronous-integration-tests-with-capybara).
to write reliable asynchronous tests](https://robots.thoughtbot.com/write-reliable-asynchronous-integration-tests-with-capybara).
1. If your merge request introduces changes that require additional steps when 1. If your merge request introduces changes that require additional steps when
installing GitLab from source, add them to `doc/install/installation.md` in installing GitLab from source, add them to `doc/install/installation.md` in
the same merge request. the same merge request.
@ -95,109 +99,117 @@ request is as follows:
instructions are specific to a version, add them to the "Version specific instructions are specific to a version, add them to the "Version specific
upgrading instructions" section. upgrading instructions" section.
Please keep the change in a single MR **as small as possible**. If you want to If you would like quick feedback on your merge request feel free to mention someone
contribute a large feature think very hard what the minimum viable change is. from the [core team](https://about.gitlab.com/community/core-team/) or one of the
Can you split the functionality? Can you only submit the backend/API code? Can [merge request coaches](https://about.gitlab.com/team/). When having your code reviewed
you start with a very simple UI? Can you do part of the refactor? The increased and when reviewing merge requests, please keep the [code review guidelines](../code_review.md)
reviewability of small MRs that leads to higher code quality is more important in mind.
to us than having a minimal commit log. The smaller an MR is the more likely it
is it will be merged (quickly). After that you can send more MRs to enhance it.
The ['How to get faster PR reviews' document of Kubernetes](https://github.com/kubernetes/community/blob/master/contributors/devel/faster_reviews.md) also has some great points regarding this.
For examples of feedback on merge requests please look at already ### Keep it simple
[closed merge requests][closed-merge-requests]. If you would like quick feedback
on your merge request feel free to mention someone from the [core team] or one
of the [Merge request coaches][team].
Please ensure that your merge request meets the contribution acceptance criteria.
When having your code reviewed and when reviewing merge requests please take the *Live by smaller iterations.* Please keep the amount of changes in a single MR **as small as possible**.
[code review guidelines](../code_review.md) into account. If you want to contribute a large feature, think very carefully about what the
[minimum viable change](https://about.gitlab.com/handbook/product/#the-minimally-viable-change)
is. Can you split the functionality into two smaller MRs? Can you submit only the
backend/API code? Can you start with a very simple UI? Can you do just a part of the
refactor?
[git-squash]: https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits Small MRs which are more easily reviewed, lead to higher code quality which is
[closed-merge-requests]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests?assignee_id=&label_name=&milestone_id=&scope=&sort=&state=closed more important to GitLab than having a minimal commit log. The smaller an MR is,
[team]: https://about.gitlab.com/team/ the more likely it will be merged quickly. After that you can send more MRs to
enhance and expand the feature. The [How to get faster PR reviews](https://github.com/kubernetes/kubernetes/blob/release-1.5/docs/devel/faster_reviews.md)
document from the Kubernetes team also has some great points regarding this.
### Commit messages guidelines
When writing commit messages, please follow the guidelines below:
- The commit subject must contain at least 3 words.
- The commit subject should ideally contain up to 50 characters,
and must not be longer than 72 characters.
- The commit subject must start with a capital letter.
- The commit subject must not end with a period.
- The commit subject and body must be separated by a blank line.
- The commit body must not contain more than 72 characters per line.
- Commits that change 30 or more lines across at least 3 files must
describe these changes in the commit body.
- The commit subject or body must not contain Emojis.
- Use issues and merge requests' full URLs instead of short references,
as they are displayed as plain text outside of GitLab.
- The merge request must not contain more than 10 commit messages.
If the guidelines are not met, the MR will not pass the
[Danger checks](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/danger/commit_messages/Dangerfile).
For more information see [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/).
## Contribution acceptance criteria ## Contribution acceptance criteria
1. The change is as small as possible To make sure that your merge request can be approved, please ensure that it meets
the contribution acceptance criteria below:
1. The change is as small as possible.
1. Include proper tests and make all tests pass (unless it contains a test 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 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. unit tests, even if the class is exercised at a higher level, such as a feature test.
1. If you suspect a failing CI build is unrelated to your contribution, you may - If a failing CI build seems to be unrelated to your contribution, you can try
try and restart the failing CI job or ask a developer to fix the restarting the failing CI job, rebasing from master to bring in updates that
aforementioned failing test may resolve the failure, or if it has not been fixed yet, ask a developer to
1. Your MR initially contains a single commit (please use `git rebase -i` to help you fix the test.
squash commits) 1. The MR initially contains a a few logically organized commits.
1. Your changes can merge without problems (if not please rebase if you're the 1. The changes can merge without problems. If not, you should rebase if you're the
only one working on your feature branch, otherwise, merge `master`) only one working on your feature branch, otherwise merge `master`.
1. Does not break any existing functionality 1. Only one specific issue is fixed or one specific feature is implemented. Do not
1. Fixes one specific issue or implements one specific feature (do not combine combine things; send separate merge requests for each issue or feature.
things, send separate merge requests if needed) 1. Migrations should do only one thing (e.g., create a table, move data to a new
1. Migrations should do only one thing (e.g., either create a table, move data table, or remove an old table) to aid retrying on failure.
to a new table or remove an old table) to aid retrying on failure 1. Contains functionality that other users will benefit from.
1. Keeps the GitLab code base clean and well structured 1. Doesn't add configuration options or settings options since they complicate making
1. Contains functionality we think other users will benefit from too and testing future changes.
1. Doesn't add configuration options or settings options since they complicate 1. Changes do not degrade performance:
making and testing future changes - Avoid repeated polling of endpoints that require a significant amount of overhead.
1. Changes do not adversely degrade performance. - Check for N+1 queries via the SQL log or [`QueryRecorder`](../merge_request_performance_guidelines.md).
- Avoid repeated polling of endpoints that require a significant amount of overhead - Avoid repeated access of the filesystem.
- Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/merge_request_performance_guidelines.html) - Use [polling with ETag caching](../polling.md) if needed to support real-time features.
- Avoid repeated access of filesystem 1. If the merge request adds any new libraries (gems, JavaScript libraries, etc.),
1. If you need polling to support real-time features, please use they should conform to our [Licensing guidelines](../licensing.md). See those
[polling with ETag caching][polling-etag]. instructions for help if the "license-finder" test fails with a
1. Changes after submitting the merge request should be in separate commits `Dependencies that need approval` error. Also, make the reviewer aware of the new
(no squashing). library and explain why you need it.
1. It conforms to the [style guides](style_guides.md) and the following: 1. The merge request meets GitLab's [definition of done](#definition-of-done), below.
- If your change touches a line that does not follow the style, modify the
entire line to follow it. This prevents linting tools from generating warnings.
- Don't touch neighbouring lines. As an exception, automatic mass
refactoring modifications may leave style non-compliant.
1. If the merge request adds any new libraries (gems, JavaScript libraries,
etc.), they should conform to our [Licensing guidelines][license-finder-doc].
See the instructions in that document for help if your MR fails the
"license-finder" test with a "Dependencies that need approval" error.
1. The merge request meets the [definition of done](#definition-of-done).
[license-finder-doc]: ../licensing.md
[polling-etag]: ../polling.md
## Definition of done ## Definition of done
If you contribute to GitLab please know that changes involve more than just If you contribute to GitLab please know that changes involve more than just
code. We have the following [definition of done][definition-of-done]. Please ensure you support code. We use the following [definition of done](https://www.agilealliance.org/glossary/definition-of-done).
the feature you contribute through all of these steps. Your contribution is not *done* until you have made sure it meets all of these
requirements.
1. Description explaining the relevancy (see following item) 1. Clear description explaining the relevancy of the contribution.
1. Working and clean code that is commented where needed 1. Working and clean code that is commented where needed.
1. [Unit, integration, and system tests][testing] that pass on the CI server 1. [Unit, integration, and system tests](../testing_guide/index.md) that all pass
1. Performance/scalability implications have been considered, addressed, and tested on the CI server.
1. [Documented][doc-guidelines] in the `/doc` directory 1. Performance/scalability implications have been considered, addressed, and tested.
1. [Changelog entry added][changelog], if necessary 1. [Documented](../documentation/index.md) in the `/doc` directory.
1. Reviewed by UX/FE/BE and any concerns are addressed 1. [Changelog entry added](../changelog.md), if necessary.
1. Merged by a project maintainer 1. Reviewed by relevant (UX/FE/BE/tech writing) reviewers and all concerns are addressed.
1. Added to the release blog article, if relevant 1. Merged by a project maintainer.
1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/), if relevant 1. Added to the [release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/),
1. Community questions answered if relevant.
1. Answers to questions radiated (in docs/wiki/support etc.) 1. Added to [the website](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml), if relevant.
1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-at-the-system-level-aka-end-to-end-tests) added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams) with any questions 1. [Black-box tests/end-to-end tests](../testing_guide/testing_levels.md#black-box-tests-at-the-system-level-aka-end-to-end-tests)
added if required. Please contact [the quality team](https://about.gitlab.com/handbook/engineering/quality/#teams)
with any questions.
## Dependencies
If you add a dependency in GitLab (such as an operating system package) please If you add a dependency in GitLab (such as an operating system package) please
consider updating the following and note the applicability of each in your consider updating the following, and note the applicability of each in your merge
merge request: request:
1. Note the addition in the release blog post (create one if it doesn't exist yet) <https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/> 1. Note the addition in the [release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/)
1. Upgrade guide, for example <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/update/7.5-to-7.6.md> (create one if it doesn't exist yet).
1. Installation guide <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies> 1. [The upgrade guide](../../update/upgrading_from_source.md).
1. GitLab Development Kit <https://gitlab.com/gitlab-org/gitlab-development-kit> 1. The [GitLab Installation Guide](../../install/installation.md#1-packages-and-dependencies).
1. Test suite <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/prepare_build.sh> 1. The [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit).
1. Omnibus package creator <https://gitlab.com/gitlab-org/omnibus-gitlab> 1. The [CI environment preparation](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/prepare_build.sh).
1. The [Omnibus package creator](https://gitlab.com/gitlab-org/omnibus-gitlab).
[definition-of-done]: http://guide.agilealliance.org/guide/definition-of-done.html
[testing]: ../testing_guide/index.md
---
[Return to Contributing documentation](index.md)
[changelog]: ../changelog.md "Generate a changelog entry"
[doc-guidelines]: ../documentation/index.md "Documentation guidelines"