`angellist-style`

Table of Contents

Public Service Announcement
- The Merits of Linting
- Challenging the Status Quo
Scope
Installation
Usage
- Applying Partial Rulesets
- Generating a TODO File
- Building the Gem
Contributing

This gem encapsulates linter rules for rubocop that can be applied to any Ruby application or service within AngelList stack. It comes with a multiple config files which deactivate some of RuboCop’s features. It is meant as a less restrictive foundation that you can use directly or base your style discussions on.

Important

The gems' ruleset also loads the relaxed ruby style guide version 2.5, saved into a local file .rubocop_relaxed.yml.

Public Service Announcement

The Merits of Linting

The debate is over: automatic formatters and linters have won, period. You can argue with a bus or a mountain, but you won’t win that argument. Same here.

Please use rubocop to auto-correct your PRs.

It’s good for you,
It’s good for other developers who will be reading your code,
It’s good for the business, and
It’s good for the tests.

Challenging the Status Quo

There are many scenarios where you may disagree with a given rule, either in general, or in a specific context.

Here are your choices:

For in-place overrides that only happen once or twice, use in-line comments to disable and immediately re-enable the rule:

# lib/path/to-my-file.rb
# rubocop: disable Metrics/MethodLength
def very_long_method
  # very long body [snip]
end
# rubocop: enable Metrics/MethodLength

For per-file or folder rule overrides, add them to your local .rubocop.yml:

# .rubocop.yml
Metrics/MethodLength:
  Exclude:
    - lib/path/to-my-file.rb

Add an entire rule overide into your local .rubocop.yml file:

# .rubocop.yml
Metrics/MethodLength:
  Exclude:
    - lib/path/to-my-file.rb

Finally, if you want to propose a global change with one or more rules, dependencies, or exclusions, add your change to the appropriate file under config/, submit a pull request, and then announce your proposal and the PR in the appropriate Slack channel (you might want to create a poll). Once you are done receiving the feedback — move forward appropriately.

Scope

This gem is released as a public ruby gem (available at rubygems) for ease of deployment.

Installation

Add this line to your application’s Gemfile:

gem 'angellist-style'

And then execute:

$ bundle install

Alternatively, run:

$ gem install angellist-style -N

Usage

To use the styles contained in this gem, add this to your .rubocop.yml:

inherit_gem:
  angellist-style:
    - .rubocop.yml

# Local overrides.
Namespace/Rule1:
  Enabled: false

Namespace/Rule2:
  Enabled: false

# ... etc ....

Applying Partial Rulesets

While not recommended, you can load the rule overrides only for certain Rubocop top-level categories, which are all grouped in YAML files under the config/ folder.

If you inspect the file .rubocop_angellist.yml, you’ll see the full list of rule files that is being included.

Here we show a version you’d specify in your project’s .rubocop.yml. If you prefer not to apply some of the categories, just delete the corresponding line that you do not want to include:

inherit_gem:
angellist-style:
- .rubocop_relaxed.yml
- config/require.yml
- config/all_cops.yml
- config/layout.yml
- config/lint.yml
- config/metrics.yml
- config/naming.yml
- config/rails.yml
- config/rspec.yml
- config/security.yml
- config/style.yml

Generating a TODO File

Rubocop can generate a local "TODO" file, which you can check-in — this alllows you to run rubocop on CI and have it pass all the legacy code, but fail any new code that does not satisfy the linter.

$ bundle exec rubocop --auto-gen-config

Building the Gem

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Gem management is provided by Rake tasks:

To install this gem onto your local machine, run bundle exec rake install.
If you have not yet authenticated with rubygems.org, make sure to create an account, and protect it with the MFA. Then
To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/venturehacks/angellist-style.

angellist-style

Development

Runtime