diff options
Diffstat (limited to 'doc/development/contributing')
| -rw-r--r-- | doc/development/contributing/community_roles.md | 2 | ||||
| -rw-r--r-- | doc/development/contributing/index.md | 14 | ||||
| -rw-r--r-- | doc/development/contributing/issue_workflow.md | 31 | ||||
| -rw-r--r-- | doc/development/contributing/merge_request_workflow.md | 14 | ||||
| -rw-r--r-- | doc/development/contributing/style_guides.md | 6 |
5 files changed, 38 insertions, 29 deletions
diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 5419992517b..3804aa7f8a8 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -12,7 +12,7 @@ GitLab community members and their privileges/responsibilities. |-------|------------------|--------------| | Maintainer | Accepts merge requests on several GitLab projects | Added to the [team page](https://about.gitlab.com/company/team/). An expert on code reviews and knows the product/codebase | | Reviewer | Performs code reviews on MRs | Added to the [team page](https://about.gitlab.com/company/team/) | -| Developer |Has access to GitLab internal infrastructure & issues (e.g. HR-related) | GitLab employee or a Core Team member (with an NDA) | +| Developer |Has access to GitLab internal infrastructure & issues (for example, HR-related) | GitLab employee or a Core Team member (with an NDA) | | Contributor | Can make contributions to all GitLab public projects | Have a GitLab.com account | [List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab-ce). diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 2fe08f78aed..fe7dc52d077 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -129,8 +129,8 @@ The general flow of contributing to GitLab is: 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, +1. Assign the merge request (if possible) to, or [mention](../../user/project/issues/issue_data_and_actions.md#mentions), + 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 @@ -167,18 +167,18 @@ GitLab will do its best to review community contributions as quickly as possible 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. +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 +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: +Mention a maintainer in merge requests that contain: - More than 500 changes. - Any major [breaking changes](#breaking-changes). @@ -191,7 +191,7 @@ If you are not sure who to mention, the reviewer will do this for you early in t 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.). +- Changing the definition of an existing API (by doing things like re-naming query parameters or changing routes). - 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. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index aa1b353c634..1dfe560d68d 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -47,11 +47,11 @@ scheduling into milestones. Labeling is a task for everyone. (For some projects, Most issues will have labels for at least one of the following: -- Type: `~feature`, `~bug`, `~tooling`, `~documentation`, etc. -- Stage: `~"devops::plan"`, `~"devops::create"`, etc. -- Group: `~"group::source code"`, `~"group::knowledge"`, `~"group::editor"`, etc. -- Category: `~"Category:Code Analytics"`, `~"Category:DevOps Reports"`, `~"Category:Templates"`, etc. -- Feature: `~wiki`, `~ldap`, `~api`, `~issues`, `~"merge requests"`, etc. +- Type. For example: `~feature`, `~bug`, `~tooling`, or `~documentation`. +- 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` @@ -72,12 +72,17 @@ issue should have one and only one. The current type labels are: -- ~feature -- ~bug -- ~tooling -- ~"support request" -- ~meta -- ~documentation +- `~feature` + - `~"feature::addition"` + - `~"feature::enhancement"` + - `~"feature::maintenance"` +- `~bug` +- `~tooling` + - `~"tooling::pipelines"` + - `~"tooling::workflow"` +- `~"support request"` +- `~meta` +- `~documentation` A number of type labels have a priority assigned to them, which automatically makes them float to the top, depending on their importance. @@ -201,7 +206,7 @@ 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`, `~"merge requests"` etc. +Examples of feature labels are `~wiki`, `~ldap`, `~api`, `~issues`, and `~"merge requests"`. #### Naming and color convention @@ -223,7 +228,7 @@ The current department labels are: ### Team labels -**Important**: Most of the historical team labels (e.g. Manage, Plan etc.) are +**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. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index a6dcac47910..534150e4d37 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -12,7 +12,7 @@ to GitLab code, tests, and documentation. The issues that are specifically suita for community contributions are listed with the [`Accepting merge requests`](issue_workflow.md#label-for-community-contributors) label, but you are free to contribute to any issue you want. -Please note that if an issue is marked for the current milestone at any time, even +If an issue is marked for the current milestone at any time, even 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. @@ -23,8 +23,8 @@ wireframes of the proposed feature if it will also change the UI. 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), -[Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests), etc. +[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 @@ -69,7 +69,7 @@ request is as follows: 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. The MR must include *Before* and *After* screenshots if UI changes are made. - 1. Include any steps or setup required to ensure reviewers can view the changes you've made (e.g. include any information about feature flags). + 1. Include any steps or setup required to ensure reviewers can view the changes you've made (for example, include any information about feature flags). 1. If you're allowed to, set a relevant milestone and [labels](issue_workflow.md). 1. UI changes should use available components from the GitLab Design System, [Pajamas](https://design.gitlab.com/). @@ -204,7 +204,7 @@ the contribution acceptance criteria below: only one working on your feature branch, otherwise merge `main`. 1. Only one specific issue is fixed or one specific feature is implemented. Do not combine things; send separate merge requests for each issue or feature. -1. Migrations should do only one thing (e.g., create a table, move data to a new +1. Migrations should do only one thing (for example, create a table, move data to a new table, or remove an old table) to aid retrying on failure. 1. Contains functionality that other users will benefit from. 1. Doesn't add configuration options or settings options since they complicate making @@ -214,7 +214,7 @@ the contribution acceptance criteria below: - Check for N+1 queries via the SQL log or [`QueryRecorder`](../merge_request_performance_guidelines.md). - Avoid repeated access of the file system. - Use [polling with ETag caching](../polling.md) if needed to support real-time features. -1. If the merge request adds any new libraries (gems, JavaScript libraries, etc.), +1. If the merge request adds any new libraries (like gems or JavaScript libraries), they should conform to our [Licensing guidelines](../licensing.md). See those instructions for help if the "license-finder" test fails with a `Dependencies that need approval` error. Also, make the reviewer aware of the new @@ -272,7 +272,7 @@ request: We allow engineering time to fix small problems (with or without an issue) that are incremental improvements, such as: -1. Unprioritized bug fixes (e.g. [Banner alerting of project move is +1. Unprioritized bug fixes (for example, [Banner alerting of project move is showing up everywhere](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/18985)) 1. Documentation improvements 1. Rubocop or Code Quality improvements diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 5a54e3afbea..1b339b7f252 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -62,6 +62,7 @@ Before you push your changes, Lefthook automatically runs the following checks: - SCSS lint: Run `yarn lint:stylelint` checks (with the [`.stylelintrc`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.stylelintrc) configuration) on the modified `*.scss{,.css}` files. Tags: `stylesheet`, `css`, `style`. - RuboCop: Run `bundle exec rubocop` checks (with the [`.rubocop.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.rubocop.yml) configuration) on the modified `*.rb` files. Tags: `backend`, `style`. - Vale: Run `vale` checks (with the [`.vale.ini`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.vale.ini) configuration) on the modified `*.md` files. Tags: `documentation`, `style`. +- Documentation metadata: Run checks for the absence of [documentation metadata](../documentation/index.md#metadata). In addition to the default configuration, you can define a [local configuration](https://github.com/Arkweid/lefthook/blob/master/docs/full_guide.md#local-config). @@ -139,7 +140,10 @@ reviewers/maintainers must not ask authors to use one style or the other, as bot are accepted. This isn't an ideal situation since this leaves space for [bike-shedding](https://en.wiktionary.org/wiki/bikeshedding), and ideally we should enable all RuboCop rules to avoid style-related -discussions/nitpicking/back-and-forth in reviews. +discussions/nitpicking/back-and-forth in reviews. There are some styles that +commonly come up in reviews that are not enforced, the +[GitLab Ruby style guide](../backend/ruby_style_guide.md) includes a non-exhaustive +list of these topics. Additionally, we have a dedicated [newlines style guide](../newlines_styleguide.md), as well as dedicated |