diff options
Diffstat (limited to 'doc/development/contributing/style_guides.md')
| -rw-r--r-- | doc/development/contributing/style_guides.md | 115 |
1 files changed, 4 insertions, 111 deletions
diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 9d04e1590d0..fe1aa8449c2 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -108,117 +108,6 @@ pre-push: For more information, check out [Lefthook documentation Skipping commands section](https://github.com/evilmartians/lefthook/blob/master/docs/full_guide.md#skipping-commands). -## Ruby, Rails, RSpec - -Our codebase style is defined and enforced by [RuboCop](https://github.com/rubocop-hq/rubocop). - -You can check for any offenses locally with `bundle exec rubocop --parallel`. -On the CI, this is automatically checked by the `static-analysis` jobs. - -In addition, you can [integrate RuboCop](../developing_with_solargraph.md) into -supported IDEs using the [Solargraph](https://github.com/castwide/solargraph) gem. - -For RuboCop rules that we have not taken a decision on yet, we follow the -[Ruby Style Guide](https://github.com/rubocop-hq/ruby-style-guide), -[Rails Style Guide](https://github.com/rubocop-hq/rails-style-guide), and -[RSpec Style Guide](https://github.com/rubocop-hq/rspec-style-guide) as general -guidelines to write idiomatic Ruby/Rails/RSpec, but reviewers/maintainers should -be tolerant and not too pedantic about style. - -Similarly, some RuboCop rules are currently disabled, and for those, -reviewers/maintainers must not ask authors to use one style or the other, as both -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. 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 -[test-specific style guides and best practices](../testing_guide/index.md). - -### Creating new RuboCop cops - -Typically it is better for the linting rules to be enforced programmatically as it -reduces the aforementioned [bike-shedding](https://en.wiktionary.org/wiki/bikeshedding). - -To that end, we encourage creation of new RuboCop rules in the codebase. - -We maintain Cops across several Ruby code bases, and not all of them are -specific to the GitLab application. -When creating a new cop that could be applied to multiple applications, we encourage you -to add it to our [GitLab Styles](https://gitlab.com/gitlab-org/gitlab-styles) gem. -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, to help you create the matcher. -See also [!97024](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/97024). - -### Resolving RuboCop exceptions - -When the number of RuboCop exceptions exceed the default [`exclude-limit` of 15](https://docs.rubocop.org/rubocop/1.2/usage/basic_usage.html#command-line-flags), -we may want to resolve exceptions over multiple commits. To minimize confusion, -we should track our progress through the exception list. - -The preferred way to [generate the initial list or a list for specific RuboCop rules](../rake_tasks.md#generate-initial-rubocop-todo-list) -is to run the Rake task `rubocop:todo:generate`: - -```shell -# Initial list -bundle exec rake rubocop:todo:generate - -# List for specific RuboCop rules -bundle exec rake 'rubocop:todo:generate[Gitlab/NamespacedClass,Lint/Syntax]' -``` - -This Rake task creates or updates the exception list in `.rubocop_todo/`. For -example, the configuration for the RuboCop rule `Gitlab/NamespacedClass` is -located in `.rubocop_todo/gitlab/namespaced_class.yml`. - -Make sure to commit any changes in `.rubocop_todo/` after running the Rake task. - -### Reveal existing RuboCop exceptions - -To reveal existing RuboCop exceptions in the code that have been excluded via `.rubocop_todo.yml` and -`.rubocop_todo/**/*.yml`, set the environment variable `REVEAL_RUBOCOP_TODO` to `1`. - -This allows you to reveal existing RuboCop exceptions during your daily work cycle and fix them along the way. - -NOTE: -Define permanent `Exclude`s in `.rubocop.yml` instead of `.rubocop_todo/**/*.yml`. - ## Database migrations See the dedicated [Database Migrations Style Guide](../migration_style_guide.md). @@ -231,6 +120,10 @@ See the dedicated [JS Style Guide](../fe_guide/style/javascript.md). See the dedicated [SCSS Style Guide](../fe_guide/style/scss.md). +## Ruby + +See the dedicated [Ruby Style Guide](../backend/ruby_style_guide.md). + ## Go See the dedicated [Go standards and style guidelines](../go_guide/index.md). |