Skip to content

Latest commit

 

History

History
209 lines (155 loc) · 7.05 KB

CONTRIBUTING.md

File metadata and controls

209 lines (155 loc) · 7.05 KB
Raw

Contributing to Reek

We welcome any and all contributions to Reek!

If what you’re proposing requires significant work discuss it beforehand as an issue – it’s much easier for us to guide you towards a good solution and less frustrating for you than doing a lot of work only to find us suggesting large parts should be rewritten.

Don’t hesitate to offer trivial fixes (spelling, better naming ideas, etc.) – we’ll let you know if you’re overdoing it. :)

Reporting Issues

Search all existing (open and closed) issues for a possible previous report; comment there if the issue is not actually resolved properly or you have any additional information.

Include the steps to reproduce the issue, the expected outcome and the actual outcome.

Include as much information as possible: the exact Reek invocation that you use, Reek’s config and version, Ruby version, Ruby platform (MRI, JRuby, etc.), operating system.

Try to provide a minimal example that reproduces the issue. Extra kudos if you can write it as a failing test. :)

Make sure any code examples and output are properly formatted using code blocks.

Contributing features, bugfixes, documentation

Getting started

Fork Reek, then clone it, make sure you have Bundler installed, install dependencies and make sure all of the existing tests pass:

git clone [email protected]:…username…/reek.git
cd reek
gem install bundler
bundle
bundle exec rake

Once you’re sure your copy of Reek works create your own feature branch from our "master" branch:

git checkout -b your_feature_or_fix_name

Make sure you have read our style guide before you start contributing.

Then start hacking and add new tests which make sure that your new feature works or demonstrate that your fix was needed.

RSpec Specs

Reek uses Rspec for unit and functional testing.

We're trying to follow betterspecs. You can find an excellent cheat sheet on how to write idiomatic Rspec here.

We do not use the popular "foo" / "bar" naming when it comes to the question "how to come up with good example names?". Instead, we use the military alphabet in ascending order which means that we would write this

class Foo
  def bar(baz)
    baz.quux
  end
end

rather like this:

class Alfa
  def bravo(charlie)
    charlie.delta
  end
end

We also aim to make our specs as self-reliant as possible. They should not rely on external sample or configuration files since that makes it very hard to reason about them and introduces a tight coupling which makes refactoring more difficult. Unfortunately our current specs are a bit misleading in this regard since they are often doing the opposite, relying on external sample and configuration files (indicated by using some of the constants defined in samples/paths.rb). Our goal is to reverse this development.

Cucumber Features

Reek uses Cucumber with Aruba for integration tests. Keep the following in mind when writing cucumber features.

What to test

Not everything needs a cucumber feature. We try to limit cucumber features to things that really require end-to-end testing of Reek's behavior. In particular, this means individual smell detectors should not have their own scenarios.

TTY output checks

Some default behaviors of Reek depend on whether the output is a TTY, for example output coloring and the progress bar. Because under Aruba stdout is not a TTY, Reeks default behavior in the scenarios is different in this regard than if it were run in a terminal.

Failing Cucumber Scenarios

If there is a failing scenario and you cannot figure out why it is failing, just run the failing scenario: bundle exec cucumber features/failing_scenario.feature:line. By doing so Aruba will leave its set up in the tmp/aruba directory. You can then cd into this directory and run Reek the same way the cucumber scenario actually ran it. This way you can debug scenario failures that can be very opaque sometimes.

Writing new smell detectors

Please see our separate guide for this.

Creating your pull request

We care a lot about good commit messages.

Once you’re happy with your feature / fix – or want to share it as a work-in-progress and request comments – once again make sure all of the tests pass. This will also run RuboCop – fix any offenses RuboCop finds (or discuss them in the pull request):

bundle exec rake

Once your code is ready for review push it to your repository:

git push -u origin

Then go to your GitHub fork and make a pull request to the original repository.

Review and Fixes

Try to gauge and let us know in the pull request whether what you propose is a backward-compatible bugfix and should go into the next patch release, is a backward-compatible feature and should go into the next minor release, or has to break backward-compatibility and so needs to wait for the next major release of Reek. See also our versioning policy below.

Once your PR is open someone will review it, discuss the details (if needed) and either merge right away or ask for some further fixes.

GitHub doesn’t have a good way to amend pull requests from external repositories. In cases where it’s easier to make a direct fix to your pull request (rather than describing it in the comments) we’ll either open a separate pull request to the branch in your repository or ask you to give us commit access to your repository.

If there were any fixes to your pull request we’ll ask you to squash all of the commits into one:

git rebase -i master
# squash squash squash
git push -f origin

Versioning policy

We are following semantic versioning.

If you're working on a change that is breaking backwards-compatibility just go ahead with your pull request like normal. We'll discuss this then in the pull request and help you to point your pull request to the right branch.

Releasing Reek

In this example we assume the current version is 5.3.1 and you want to update to 5.3.2.

  • Create a branch with a name like "prepare-v.5.3.2"
  • Update the version in lib/reek/version.rb
  • List all relevant changes in CHANGELOG.md
  • Update the version number in our cucumber features, otherwise the build will fail. You can do this quite easily via 
    find features/ -type f -exec sed -i '' 's/v5.3.1/v5.3.2/g' {} +
  • Push the branch, create a pull request, have it reviewed and merged
  • Pull the latest master and then do a 
    bundle exec rake release