Editor/IDE styling standardization
We use EditorConfig to automatically apply certain styling
standards before files are saved locally. Most editors/IDEs will honor the
settings automatically by default. If your editor/IDE does not automatically support
we suggest investigating to see if a plugin exists. For instance here is the
plugin for vim.
Pre-push static analysis
We strongly recommend installing Lefthook to automatically check for static analysis offenses before pushing your changes.
lefthook, run the following in your GitLab source directory:
# 1. Make sure to uninstall Overcommit first overcommit --uninstall # If using rbenv, at this point you may need to do: rbenv rehash # 2. Install lefthook... ## With Homebrew (macOS) brew install Arkweid/lefthook/lefthook ## Or with Go go get github.com/Arkweid/lefthook ## Or with Rubygems gem install lefthook ### You may need to run the following if you're using rbenv rbenv rehash # 3. Install the Git hooks lefthook install -f
Before you push your changes, Lefthook then automatically run Danger checks, and other checks for changed files. This saves you time as you don't have to wait for the same errors to be detected by CI/CD.
Lefthook relies on a pre-push hook to prevent commits that violate its ruleset.
To override this behavior, pass the environment variable
LEFTHOOK=0. That is,
LEFTHOOK=0 git push.
You can also:
- Define local configuration.
- Skip checks per tag on the fly.
LEFTHOOK_EXCLUDE=frontend git push origin.
- Run hooks manually.
lefthook run pre-push.
Ruby, Rails, RSpec
Our codebase style is defined and enforced by RuboCop.
You can check for any offenses locally with
bundle exec rubocop --parallel.
On the CI, this is automatically checked by the
For RuboCop rules that we have not taken a decision on yet, we follow the Ruby Style Guide, Rails Style Guide, and 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, and ideally we should enable all RuboCop rules to avoid style-related discussions/nitpicking/back-and-forth in reviews.
Creating new RuboCop cops
Typically it is better for the linting rules to be enforced programmatically as it reduces the aforementioned bike-shedding.
To that end, we encourage creation of new RuboCop rules in the codebase.
When creating a new cop that could be applied to multiple applications, we encourage you to add it to our GitLab Styles gem.
Resolving RuboCop exceptions
When the number of RuboCop exceptions exceed the default
exclude-limit of 15,
we may want to resolve exceptions over multiple commits. To minimize confusion,
we should track our progress through the exception list.
When auto-generating the
.rubocop_todo.yml exception list for a particular Cop,
and more than 15 files are affected, we should add the exception list to
a different file,
This ensures that our list isn't mistakenly removed by another auto generation of
.rubocop_todo.yml. This also allows us greater visibility into the exceptions
which are currently being resolved.
One way to generate the initial list is to run the todo auto generation,
exclude limit set to a high number.
bundle exec rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit=10000
You can then move the list from the freshly generated
.rubocop_todo.yml for the Cop being actively
resolved and place it in the
.rubocop_manual_todo.yml. In this scenario, do not commit auto generated
changes to the
.rubocop_todo.yml as an
exclude limit that is higher than 15 will make the
.rubocop_todo.yml hard to parse.
See the dedicated Database Migrations Style Guide.
See the dedicated JS Style Guide.
See the dedicated SCSS Style Guide.
See the dedicated Go standards and style guidelines.
Shell commands (Ruby)
See the dedicated Guidelines for shell commands in the GitLab codebase.
See the dedicated Shell scripting standards and style guidelines.
We're following Ciro Santilli's Markdown Style Guide.
See the dedicated Documentation Style Guide.
See the dedicated Python Development Guidelines.
Code should be written in US English.