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:

1. 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

2. 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

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

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

4. 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.