Merge branch '18400-improve-style-guides-documentation' into 'master'

Improve the style guide documentation

Closes #18400

See merge request gitlab-org/gitlab!23533

doc/development/README.md

@@ -9,20 +9,29 @@ description: 'Learn how to contribute to GitLab.'
 
 - Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md)
 - [GitLab contributing guide](contributing/index.md)
-- [Architecture](architecture.md) of GitLab
+  - [Issues workflow](contributing/issue_workflow.md) (issue tracker guidelines, triaging, labels, feature proposals, issue weight, regression issues, technical and UX debt)
+  - [Merge requests workflow](contributing/merge_request_workflow.md) (merge request guidelines, contribution acceptance criteria, definition of done, dependencies)
+  - [Style guides](contributing/style_guides.md)
+  - [Implement design & UI elements](contributing/design.md)
+- [GitLab Architecture Overview](architecture.md)
 - [Rake tasks](rake_tasks.md) for development
 
 ## Processes
 
-- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/blob/master/PROCESS.md)
-- [Generate a changelog entry with `bin/changelog`](changelog.md)
+**Must-reads:**
+
 - [Code review guidelines](code_review.md) for reviewing code and having code reviewed
 - [Database review guidelines](database_review.md) for reviewing database-related changes and complex SQL queries, and having them reviewed
 - [Pipelines for the GitLab project](pipelines.md)
-- [Guidelines for implementing Enterprise Edition features](ee_features.md)
+
+Complementary reads:
+
+- [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/blob/master/PROCESS.md)
 - [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer)
-- [Requesting access to Chatops on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLabbers)
+- [Guidelines for implementing Enterprise Edition features](ee_features.md)
 - [Danger bot](dangerbot.md)
+- [Generate a changelog entry with `bin/changelog`](changelog.md)
+- [Requesting access to Chatops on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLabbers)
 
 ## UX and Frontend guides
 

doc/development/contributing/design.md

@@ -4,7 +4,7 @@ For guidance on UX implementation at GitLab, please refer to our [Design System]
 
 The UX team uses labels to manage their workflow.
 
-The  ~"UX" label on an issue is a signal to the UX team that it will need UX attention.
+The ~"UX" label on an issue is a signal to the UX team that it will need UX attention.
 To better understand the priority by which UX tackles issues, see the [UX section](https://about.gitlab.com/handbook/engineering/ux/) of the handbook.
 
 Once an issue has been worked on and is ready for development, a UXer removes the ~"UX" label and applies the ~"UX ready" label to that issue.

doc/development/contributing/index.md

@@ -118,6 +118,11 @@ This [documentation](merge_request_workflow.md) outlines the current merge reque
 
 This [documentation](style_guides.md) outlines the current style guidelines.
 
+## Implement design & UI elements
+
+This [design documentation](design.md) outlines the current process for implementing
+design & UI elements.
+
 ## Getting an Enterprise Edition License
 
 If you need a license for contributing to an EE-feature, please [follow these instructions](https://about.gitlab.com/handbook/marketing/community-relations/code-contributor-program/#for-contributors-to-the-gitlab-enterprise-edition-ee).

doc/development/contributing/style_guides.md

 # Style guides
 
-1. [Ruby](https://github.com/rubocop-hq/ruby-style-guide).
-   Important sections include [Source Code Layout][rss-source] and
-   [Naming][rss-naming]. Use:
-   - multi-line method chaining style **Option A**: dot `.` on the second line
-   - string literal quoting style **Option A**: single quoted by default
-1. [Rails](https://github.com/rubocop-hq/rails-style-guide)
-1. [Newlines styleguide][newlines-styleguide]
-1. [Testing][testing]
-1. [JavaScript styleguide][js-styleguide]
-1. [SCSS styleguide][scss-styleguide]
-1. [Shell commands (Ruby)](../shell_commands.md) created by GitLab
-   contributors to enhance security
-1. [Database Migrations](../migration_style_guide.md)
-1. [Markdown](https://cirosantilli.com/markdown-style-guide/)
-1. [Documentation styleguide](../documentation/styleguide.md)
-1. Interface text should be written subjectively instead of objectively. It
-   should be the GitLab core team addressing a person. It should be written in
-   present time and never use past tense (has been/was). For example instead
-   of _prohibited this user from being saved due to the following errors:_ the
-   text should be _sorry, we could not create your account because:_
-1. Code should be written in [US English][us-english]
-1. [Go](../go_guide/index.md)
-1. [Python](../python_guide/index.md)
-1. [Shell scripting](../shell_scripting_guide/index.md)
-
-## Checking the style and other issues
-
-This is also the style used by linting tools such as
-[RuboCop](https://github.com/rubocop-hq/rubocop) and [Hound CI](https://houndci.com).
-You can run RuboCop by hand or install a tool like [Overcommit](https://github.com/sds/overcommit) to run it for you.
-
-Overcommit will automatically run the configured checks (like Rubocop) on every modified file before commit.
-You can use the example overcommit configuration found in `.overcommit.yml.example` as a quickstart.
-This saves you time as you don't have to wait for the same errors to be detected by the CI.
+## Pre-commit static analysis
+
+You're strongly advised to install
+[Overcommit](https://github.com/sds/overcommit) to automatically check for
+static analysis offenses before committing locally:
+
+```shell
+cd tooling/overcommit && make && cd -
+```
+
+Then before a commit is created, Overcommit will automatically check for
+RuboCop (and other checks) offenses on every modified file.
+
+This saves you time as you don't have to wait for the same errors to be detected
+by the CI.
+
+## 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.
+
+For RuboCop rules that we have not taken a decision 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.
+
+Additionally, we have a dedicated
+[newlines styleguide](../newlines_styleguide.md), as well as dedicated
+[test-specific style guides and best practices](../testing_guide/index.md).
+
+## Database migrations
+
+See the dedicated [Database Migrations Style Guide](../migration_style_guide.md).
+
+## JavaScript
+
+See the dedicated [JS Style Guide](../fe_guide/style/javascript.md).
+
+## SCSS
+
+See the dedicated [SCSS Style Guide](../fe_guide/style/scss.md).
+
+## Go
+
+See the dedicated [Go standards and style guidelines](../go_guide/index.md).
+
+## Shell commands (Ruby)
+
+See the dedicated [Guidelines for shell commands in the GitLab codebase](../shell_commands.md).
+
+## Shell scripting
+
+See the dedicated [Shell scripting standards and style guidelines](../shell_scripting_guide/index.md).
+
+## Markdown
+
+We're following [Ciro Santilli's Markdown Style Guide](https://cirosantilli.com/markdown-style-guide).
+
+## Documentation
+
+See the dedicated [Documentation Style Guide](../documentation/styleguide.md).
+
+## Python
+
+See the dedicated [Python Development Guidelines](../python_guide/index.md).
+
+## Misc
+
+Code should be written in [US English](https://en.wikipedia.org/wiki/American_English).
 
 ---
 
 [Return to Contributing documentation](index.md)
-
-[rss-source]: https://github.com/rubocop-hq/ruby-style-guide/blob/master/README.adoc#source-code-layout
-[rss-naming]: https://github.com/rubocop-hq/ruby-style-guide/blob/master/README.adoc#naming-conventions
-[doc-guidelines]: ../documentation/index.md "Documentation guidelines"
-[js-styleguide]: ../fe_guide/style/javascript.md "JavaScript styleguide"
-[scss-styleguide]: ../fe_guide/style/scss.md "SCSS styleguide"
-[newlines-styleguide]: ../newlines_styleguide.md "Newlines styleguide"
-[testing]: ../testing_guide/index.md
-[us-english]: https://en.wikipedia.org/wiki/American_English

doc/development/dangerbot.md

@@ -4,7 +4,7 @@ The GitLab CI pipeline includes a `danger-review` job that uses [Danger](https:/
 to perform a variety of automated checks on the code under test.
 
 Danger is a gem that runs in the CI environment, like any other analysis tool.
-What sets it apart from, e.g., Rubocop, is that it's designed to allow you to
+What sets it apart from, e.g., RuboCop, is that it's designed to allow you to
 easily write arbitrary code to test properties of your code or changes. To this
 end, it provides a set of common helpers and access to information about what
 has actually changed in your environment, then simply runs your code!
@@ -13,6 +13,14 @@ If Danger is asking you to change something about your merge request, it's best
 just to make the change. If you want to learn how Danger works, or make changes
 to the existing rules, then this is the document for you.
 
+## Run Danger locally
+
+A subset of the current checks can be run locally with the following rake task:
+
+```shell
+bundle exec danger_local
+```
+
 ## Operation
 
 On startup, Danger reads a [`Dangerfile`](https://gitlab.com/gitlab-org/gitlab/blob/master/Dangerfile)
@@ -118,7 +126,6 @@ at GitLab so far:
 
 ## Limitations
 
-- [`danger local` does not work on GitLab](https://github.com/danger/danger/issues/458)
 - Danger output is not added to a merge request comment if working on
   a fork. This happens because the secret variable from the canonical
   project is not shared to forks.