Add latest changes from gitlab-org/gitlab@master

3 files changed, 86 insertions, 44 deletions

diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md
index 9796e195f86..8426db84aa4 100644
--- a/doc/development/contributing/design.md
+++ b/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.
diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md
index 481a18aac3d..233bf255361 100644
--- a/doc/development/contributing/index.md
+++ b/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).
diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md
index 33c872cbb93..f35757249fc 100644
--- a/doc/development/contributing/style_guides.md
+++ b/doc/development/contributing/style_guides.md
@@ -1,49 +1,86 @@
 # 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