debian-mirror-gitlab/doc/development/contributing/index.md

239 lines
11 KiB
Markdown
Raw Normal View History

2021-01-03 14:25:43 +05:30
---
type: reference, dev
stage: none
group: Development
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-03 14:25:43 +05:30
---
2018-12-05 23:21:45 +05:30
# Contribute to GitLab
2018-11-20 20:47:30 +05:30
Thank you for your interest in contributing to GitLab. This guide details how
2018-12-13 13:39:08 +05:30
to contribute to GitLab in a way that is easy for everyone.
2018-11-20 20:47:30 +05:30
2020-05-24 23:13:21 +05:30
For a first-time step-by-step guide to the contribution process, see our
[Contributing to GitLab](https://about.gitlab.com/community/contribute/) page.
2018-11-20 20:47:30 +05:30
2020-06-23 00:09:42 +05:30
Looking for something to work on? See the
[How to contribute](#how-to-contribute) section for more information.
2018-12-13 13:39:08 +05:30
2020-05-24 23:13:21 +05:30
GitLab comes in two flavors:
2018-11-20 20:47:30 +05:30
2020-05-24 23:13:21 +05:30
- GitLab Community Edition (CE), our free and open source edition.
- GitLab Enterprise Edition (EE), which is our commercial edition.
Throughout this guide you will see references to CE and EE for abbreviation.
To get an overview of GitLab community membership, including those that would review or merge
your contributions, visit [the community roles page](community_roles.md).
2018-12-13 13:39:08 +05:30
2019-12-21 20:55:43 +05:30
If you want to know how the GitLab [core team](https://about.gitlab.com/community/core-team/)
2020-05-24 23:13:21 +05:30
operates, see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab/blob/master/PROCESS.md).
2018-11-20 20:47:30 +05:30
2020-05-24 23:13:21 +05:30
GitLab Inc engineers should refer to the [engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/).
2018-11-20 20:47:30 +05:30
## Security vulnerability disclosure
2020-05-24 23:13:21 +05:30
Report suspected security vulnerabilities in private to
2018-11-20 20:47:30 +05:30
`support@gitlab.com`, also see the
2019-12-21 20:55:43 +05:30
[disclosure section on the GitLab.com website](https://about.gitlab.com/security/disclosure/).
2020-05-24 23:13:21 +05:30
2021-02-22 17:27:13 +05:30
WARNING:
2020-05-24 23:13:21 +05:30
Do **NOT** create publicly viewable issues for suspected security vulnerabilities.
2018-11-20 20:47:30 +05:30
## Code of conduct
2019-07-31 22:56:46 +05:30
We want to create a welcoming environment for everyone who is interested in contributing.
2020-05-24 23:13:21 +05:30
Visit our [Code of Conduct page](https://about.gitlab.com/community/contribute/code-of-conduct/) to learn more about our commitment to an open and welcoming environment.
2018-11-20 20:47:30 +05:30
## Closing policy for issues and merge requests
GitLab is a popular open source project and the capacity to deal with issues
and merge requests is limited. Out of respect for our volunteers, issues and
merge requests not in line with the guidelines listed in this document may be
closed without notice.
2020-05-24 23:13:21 +05:30
Treat our volunteers with courtesy and respect, it will go a long way
2018-11-20 20:47:30 +05:30
towards getting your issue resolved.
Issues and merge requests should be in English and contain appropriate language
for audiences of all ages.
2020-05-24 23:13:21 +05:30
If a contributor is no longer actively working on a submitted merge request,
we can:
- Decide that the merge request will be finished by one of our
[Merge request coaches](https://about.gitlab.com/company/team/).
- Close the merge request.
We make this decision based on how important the change is for our product vision. If a merge
request coach is going to finish the merge request, we assign the
`~coach will finish` label.
When a team member picks up a community contribution,
2019-07-07 11:18:12 +05:30
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.
2018-11-20 20:47:30 +05:30
2020-11-24 15:15:51 +05:30
## Closing policy for inactive bugs
GitLab values the time spent by contributors on reporting bugs. However, if a bug remains inactive for a very long period,
it will qualify for auto-closure. Please refer to the [auto-close inactive bugs](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#auto-close-inactive-bugs) section in our handbook to understand the complete workflow.
2018-11-20 20:47:30 +05:30
## Helping others
2020-05-24 23:13:21 +05:30
Help other GitLab users when you can.
The methods people use to seek help can be found on the [getting help page](https://about.gitlab.com/get-help/).
2018-11-20 20:47:30 +05:30
2020-05-24 23:13:21 +05:30
Sign up for the mailing list, answer GitLab questions on StackOverflow or respond in the IRC channel.
2018-11-20 20:47:30 +05:30
2020-05-24 23:13:21 +05:30
## How to contribute
2018-11-20 20:47:30 +05:30
2020-06-23 00:09:42 +05:30
If you would like to contribute to GitLab:
- Issues with the
[`~Accepting merge requests` label](issue_workflow.md#label-for-community-contributors)
are a great place to start.
2020-11-24 15:15:51 +05:30
- 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.
2020-06-23 00:09:42 +05:30
- Consult the [Contribution Flow](#contribution-flow) section to learn the process.
2020-05-24 23:13:21 +05:30
2019-12-21 20:55:43 +05:30
If you have any questions or need help visit [Getting Help](https://about.gitlab.com/get-help/) to
2020-05-24 23:13:21 +05:30
learn how to communicate with GitLab. We have a [Gitter channel for contributors](https://gitter.im/gitlab/contributors),
however we favor
[asynchronous communication](https://about.gitlab.com/handbook/communication/#internal-communication) over real time communication.
Thanks for your contribution!
### GitLab Development Kit
The GitLab Development Kit (GDK) helps contributors run a local GitLab instance with all the
required dependencies. It can be used to test changes to GitLab and related projects before raising
a Merge Request.
For more information, see the [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit)
project.
2018-11-20 20:47:30 +05:30
2020-06-23 00:09:42 +05:30
### 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
2021-06-08 01:23:25 +05:30
[develop against your fork](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/index.md#develop-in-your-own-gitlab-fork).
2020-06-23 00:09:42 +05:30
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. Assign the merge request (if possible) to, or `@mention`, one of the
[code owners](../../user/project/code_owners.md) for the relevant project,
and explain that you are ready for review.
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
[domain experts](../code_review.md#domain-experts) before being merged:
- A [reviewer](../code_review.md#the-responsibility-of-the-reviewer).
- A [maintainer](../code_review.md#the-responsibility-of-the-maintainer).
Keep the following in mind when submitting merge requests:
- When reviewers are reading through a merge request they may request guidance from other
reviewers.
2021-02-22 17:27:13 +05:30
- If the code quality is found to not meet GitLab standards, the merge request reviewer will
2020-06-23 00:09:42 +05:30
provide guidance and refer the author to our:
2021-01-29 00:20:46 +05:30
- [Documentation](../documentation/styleguide/index.md) style guide.
2021-02-22 17:27:13 +05:30
- [Code style guides](style_guides.md).
2020-06-23 00:09:42 +05:30
- Sometimes style guides will be followed but the code will lack structural integrity, or the
2021-04-29 21:17:54 +05:30
reviewer will have reservations about the code's overall quality. When there is a reservation,
2020-06-23 00:09:42 +05:30
the reviewer will inform the author and provide some guidance.
- Though GitLab generally allows anyone to indicate
2021-06-08 01:23:25 +05:30
[approval](../../user/project/merge_requests/approvals/index.md) of merge requests, the
2020-06-23 00:09:42 +05:30
maintainer may require [approvals from certain reviewers](../code_review.md#approval-guidelines)
before merging a merge request.
- After review, the author may be asked to update the merge request. Once the merge request has been
updated and reassigned to the reviewer, they will review the code again. This process may repeat
any number of times before merge, to help make the contribution the best it can be.
Sometimes a maintainer may choose to close a merge request. They will fully disclose why it will not
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.
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, feel free to `@mention` all merge request coaches with
`@gitlab-org/coaches` to get their attention.
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.
2021-03-11 19:13:27 +05:30
- Any major [breaking changes](#breaking-changes).
2020-06-23 00:09:42 +05:30
- External libraries.
If you are not sure who to mention, the reviewer will do this for you early in the merge request process.
2021-03-11 19:13:27 +05:30
#### Breaking changes
A "breaking change" is any change that requires users to make a corresponding change to their code, settings, or workflow. "Users" might be humans, API clients, or even code classes that "use" another class. Examples of breaking changes include:
- Removing a user-facing feature without a replacement/workaround.
- Changing the definition of an existing API (by re-naming query parameters, changing routes, etc.).
- Removing a public method from a code class.
A breaking change can be considered "major" if it affects many users, or represents a significant change in behavior.
2020-06-23 00:09:42 +05:30
#### Issues workflow
2018-11-20 20:47:30 +05:30
2019-12-04 20:38:33 +05:30
This [documentation](issue_workflow.md) outlines the current issue workflow:
2018-11-20 20:47:30 +05:30
2019-12-04 20:38:33 +05:30
- [Issue tracker guidelines](issue_workflow.md#issue-tracker-guidelines)
2019-03-02 22:35:43 +05:30
- [Issue triaging](issue_workflow.md#issue-triaging)
2019-12-04 20:38:33 +05:30
- [Labels](issue_workflow.md#labels)
2019-03-02 22:35:43 +05:30
- [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)
2019-12-04 20:38:33 +05:30
- [Technical debt in follow-up issues](issue_workflow.md#technical-debt-in-follow-up-issues)
2018-11-20 20:47:30 +05:30
2020-06-23 00:09:42 +05:30
#### Merge requests workflow
2018-11-20 20:47:30 +05:30
This [documentation](merge_request_workflow.md) outlines the current merge request process.
2019-03-02 22:35:43 +05:30
- [Merge request guidelines](merge_request_workflow.md#merge-request-guidelines)
- [Contribution acceptance criteria](merge_request_workflow.md#contribution-acceptance-criteria)
- [Definition of done](merge_request_workflow.md#definition-of-done)
2019-07-07 11:18:12 +05:30
- [Dependencies](merge_request_workflow.md#dependencies)
2018-11-20 20:47:30 +05:30
## Style guides
2018-12-13 13:39:08 +05:30
This [documentation](style_guides.md) outlines the current style guidelines.
2018-11-20 20:47:30 +05:30
2020-03-13 15:44:24 +05:30
## Implement design & UI elements
2020-05-24 23:13:21 +05:30
This [design documentation](design.md) outlines the current process for implementing design and UI
elements.
2020-03-13 15:44:24 +05:30
2020-05-24 23:13:21 +05:30
## Contribute documentation
2019-12-26 22:10:19 +05:30
2020-05-24 23:13:21 +05:30
For information on how to contribute documentation, see GitLab
[documentation guidelines](../documentation/index.md).
2019-12-26 22:10:19 +05:30
2020-05-24 23:13:21 +05:30
## Getting an Enterprise Edition License
2018-11-20 20:47:30 +05:30
2020-05-24 23:13:21 +05:30
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/#for-contributors-to-the-gitlab-enterprise-edition-ee).