diff options
Diffstat (limited to 'doc/development/contributing')
| -rw-r--r-- | doc/development/contributing/community_roles.md | 6 | ||||
| -rw-r--r-- | doc/development/contributing/design.md | 12 | ||||
| -rw-r--r-- | doc/development/contributing/index.md | 7 | ||||
| -rw-r--r-- | doc/development/contributing/issue_workflow.md | 6 | ||||
| -rw-r--r-- | doc/development/contributing/merge_request_workflow.md | 4 | ||||
| -rw-r--r-- | doc/development/contributing/style_guides.md | 36 | ||||
| -rw-r--r-- | doc/development/contributing/verify/index.md | 4 |
7 files changed, 50 insertions, 25 deletions
diff --git a/doc/development/contributing/community_roles.md b/doc/development/contributing/community_roles.md index 37c3c24a7d1..8aa219d72a1 100644 --- a/doc/development/contributing/community_roles.md +++ b/doc/development/contributing/community_roles.md @@ -1,7 +1,7 @@ --- 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/engineering/ux/technical-writing/#assignments +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 --- # Community members & roles @@ -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 (for example, 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). +[List of current reviewers/maintainers](https://about.gitlab.com/handbook/engineering/projects/#gitlab). diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md index 04915985dc8..9e54b92337a 100644 --- a/doc/development/contributing/design.md +++ b/doc/development/contributing/design.md @@ -2,7 +2,7 @@ type: reference, dev 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/engineering/ux/technical-writing/#assignments +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 --- # Design and user interface changes @@ -17,11 +17,15 @@ with additions and improvements. ## Merge request reviews -As a merge request (MR) author, you must include _Before_ and _After_ +As a merge request (MR) author, you must: + +- Include _Before_ and _After_ screenshots (or videos) of your changes in the description, as explained in our [MR workflow](merge_request_workflow.md). These screenshots/videos are very helpful for all reviewers and can speed up the review process, especially if the changes are small. +- Attach the ~UX label to any merge request that impacts the user experience. This will enable Product Designers to [review](https://about.gitlab.com/handbook/engineering/ux/product-designer/mr-reviews/#stage-group-mrs/) any user facing changes. +- Assign the Product Designer suggested by Reviewer Roulette as the reviewer of your merge request. The reviewer does not have to be the domain expert unless this is a community contribution. ## Checklist @@ -35,7 +39,7 @@ Check these aspects both when _designing_ and _reviewing_ UI changes. - Use clear and consistent [terminology](https://design.gitlab.com/content/terminology/). - Check grammar and spelling. - Consider help content and follow its [guidelines](https://design.gitlab.com/usability/helping-users/). -- Request review from the [appropriate Technical Writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments), +- Request review from the [appropriate Technical Writer](https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments), indicating any specific files or lines they should review, and how to preview or understand the location/context of the text from the user's perspective. @@ -100,7 +104,7 @@ When the design is ready, _before_ starting its implementation: - Share design specifications in the related issue, preferably through a [Figma link](https://help.figma.com/hc/en-us/articles/360040531773-Share-Files-with-anyone-using-Link-Sharing#copy-link) link or [GitLab Designs feature](../../user/project/issues/design_management.md). - See [when you should use each tool](https://about.gitlab.com/handbook/engineering/ux/product-designer/#deliver). + See [when you should use each tool](https://about.gitlab.com/handbook/product/ux/product-designer/#deliver). - Document user flow and states (for example, using [Mermaid flowcharts in Markdown](../../user/markdown.md#mermaid)). - Document animations and transitions. - Document responsive behaviors. diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 2ff51e765a3..cbccd832d78 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -2,7 +2,7 @@ type: reference, dev 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/engineering/ux/technical-writing/#assignments +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 --- # Contribute to GitLab @@ -26,11 +26,6 @@ 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). -If you want to know how the GitLab [core team](https://about.gitlab.com/community/core-team/) -operates, see [the GitLab contributing process](https://gitlab.com/gitlab-org/gitlab/-/blob/master/PROCESS.md). - -GitLab Inc engineers should refer to the [engineering workflow document](https://about.gitlab.com/handbook/engineering/workflow/). - ## Security vulnerability disclosure Report suspected security vulnerabilities by following the diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index d557319b41f..df337bb2809 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -2,7 +2,7 @@ type: reference, dev 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/engineering/ux/technical-writing/#assignments +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 --- # Issues workflow @@ -373,7 +373,7 @@ below will make it easy to manage this, without unnecessary overhead. which might lead to many hard problems to solve. Changing some text in GitLab is probably 1, adding a new Git Hook maybe 4 or 5, big features 7-9. 1. If something is very large, it should probably be split up in multiple - issues or chunks. You can simply not set the weight of a parent issue and set + issues or chunks. You can not set the weight of a parent issue and set weights to children issues. ## Regression issues @@ -432,7 +432,7 @@ original merge request - or not tracked at all! The overheads of scheduling, and rate of change in the GitLab codebase, mean that the cost of a trivial technical debt issue can quickly exceed the value of tracking it. This generally means we should resolve these in the original merge -request - or simply not create a follow-up issue at all. +request - or not create a follow-up issue at all. For example, a typo in a comment that is being copied between files is worth fixing in the same MR, but not worth creating a follow-up issue for. Renaming a diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 0e9ac569558..b40df01cbe9 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -2,7 +2,7 @@ type: reference, dev 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/engineering/ux/technical-writing/#assignments +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 --- # Merge requests workflow @@ -14,7 +14,7 @@ label, but you are free to contribute to any issue you want. 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. +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 an issue (if there isn't one already) and leave a comment asking for it diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 2e696cf517b..9d04e1590d0 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -2,7 +2,7 @@ type: reference, dev 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/engineering/ux/technical-writing/#assignments +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 --- # Style guides @@ -41,13 +41,13 @@ We were using Overcommit prior to Lefthook, so you may want to uninstall it firs bundle exec lefthook install ``` -1. Test Lefthook is working by running the Lefthook `prepare-commit-msg` Git hook: +1. Test Lefthook is working by running the Lefthook `pre-push` Git hook: ```shell - bundle exec lefthook run prepare-commit-msg + bundle exec lefthook run pre-push ``` -This should return a fully qualified path command with no other output. +This should return the lefthook version and the list of executable commands with output. ### Lefthook configuration @@ -153,11 +153,37 @@ to add it to our [GitLab Styles](https://gitlab.com/gitlab-org/gitlab-styles) ge If the Cop targets rules that only apply to the main GitLab application, it should be added to [GitLab](https://gitlab.com/gitlab-org/gitlab) instead. +### Cop grace period + +A cop is in a "grace period" if it is enabled and has `Details: grace period` defined in its TODO YAML configuration. + +On the default branch, all of the offenses from cops in the ["grace period"](../rake_tasks.md#run-rubocop-in-graceful-mode) will not fail the RuboCop CI job. The job will notify Slack in the `#f_rubocop` channel when offenses have been silenced in the scheduled pipeline. However, on merge request pipelines, the RuboCop job will fail. + +A grace period can safely be lifted as soon as there are no warnings for 2 weeks in the `#f_rubocop` channel on Slack. + +### Enabling a new cop + +1. Enable the new cop in `.rubocop.yml` (if not already done via [`gitlab-styles`](https://gitlab.com/gitlab-org/ruby/gems/gitlab-styles)). +1. [Generate TODOs for the new cop](../rake_tasks.md#generate-initial-rubocop-todo-list). +1. [Set the new cop to "grace period"](#cop-grace-period). +1. Create an issue to fix TODOs and encourage Community contributions (via ~"good for new contributors" and/or ~"Seeking community contributions"). [See some examples](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=created_date&state=opened&label_name%5B%5D=good%20for%20new%20contributors&label_name%5B%5D=static%20code%20analysis&first_page_size=20). +1. Create an issue to remove "grace period" after 2 weeks silence in `#f_rubocop` Slack channel. ([See an example](https://gitlab.com/gitlab-org/gitlab/-/issues/374903).) + +### Silenced offenses + +When offenses are silenced for cops in ["grace period"](#cop-grace-period), +the `#f_rubocop` Slack channel receives a notification message every two hours. + +To fix this issue: + +1. Find cops with silenced offenses in the linked CI job. +1. [Generate TODOs](../rake_tasks.md#generate-initial-rubocop-todo-list) for these cops. + #### RuboCop node pattern When creating [node patterns](https://docs.rubocop.org/rubocop-ast/node_pattern.html) to match Ruby's AST, you can use [`scripts/rubocop-parse`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/scripts/rubocop-parse) -to display the AST of a Ruby expression, in order to help you create the matcher. +to display the AST of a Ruby expression, to help you create the matcher. See also [!97024](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97024). ### Resolving RuboCop exceptions diff --git a/doc/development/contributing/verify/index.md b/doc/development/contributing/verify/index.md index 09b206d59aa..e94b7583904 100644 --- a/doc/development/contributing/verify/index.md +++ b/doc/development/contributing/verify/index.md @@ -52,7 +52,7 @@ and they serve us and our users well. Some examples of these principles are that - The feedback delivered by GitLab CI/CD and data produced by the platform should be accurate. If a job fails and we notify a user that it was successful, it can have severe negative consequences. -- Feedback needs to be available when a user needs it and data can not disappear unexpectedly when engineers need it. +- Feedback needs to be available when a user needs it and data cannot disappear unexpectedly when engineers need it. - It all doesn't matter if the platform is not secure and we are leaking credentials or secrets. - When a user provides a set of preconditions in a form of CI/CD configuration, the result should be deterministic each time a pipeline runs, because otherwise the platform might not be trustworthy. @@ -62,7 +62,7 @@ are leaking credentials or secrets. ### Measure before you optimize, and make data-informed decisions -It is very difficult to optimize something that you can not measure. How would you +It is very difficult to optimize something that you cannot measure. How would you know if you succeeded, or how significant the success was? If you are working on a performance or reliability improvement, make sure that you measure things before you optimize them. |