README.md in skunk-0.2.0 vs README.md in skunk-0.3.0
- old
+ new
@@ -1,21 +1,32 @@
# Skunk
+[](code-of-conduct.md) [](https://travis-ci.org/fastruby/skunk) [](https://codeclimate.com/github/fastruby/skunk/maintainability)
+
A RubyCritic extension to calculate StinkScore for a file or project.
## What is the StinkScore?
-The StinkScore is a value that assess the quality of a module. It takes into
+The StinkScore is a value that assesses the quality of a module. It takes into
account:
- Code Quality
- Code Smells
- Churn
- Code Coverage
-The formula is not perfect and it is certainly controversial.
+The main goal of the StinkScore is to serve as a compass in your next
+refactoring adventure. It will help you answer these questions:
+- What can I do to pay off technical debt?
+- What are the most complicated files with the least code coverage?
+- What are good candidates for your next test-writing efforts?
+- What are good candidates for your nest refactoring efforts?
+
+The formula is not perfect and it is certainly controversial, so any feedback is
+welcome as a new issue!
+
## Installation
Add this line to your application's Gemfile:
```ruby
@@ -30,12 +41,18 @@
$ gem install skunk
## Usage
-Simply run:
+### Getting a sorted list of stinkiest files
+To get the best results, make sure that you have `coverage/.resultset.json` in
+your application directory. That way `skunk` knows what's the status of your
+test suite + code coverage.
+
+Then simply run:
+
```
skunk
```
Then get a list of stinky files:
@@ -82,15 +99,64 @@
Modules Analysed: 13
StinkScore Average: 0.47100769230769230769230769231e2
Worst StinkScore: 166.44 (lib/skunk/cli/commands/default.rb)
```
-The command will run `rubycritic`, so that will generate a RubyCritic overview
-HTML report as well.
+The command will run `rubycritic` and it will try to load code coverage data
+from your `.resultset.json` file.
Skunk's report will be in the console. Use it wisely. :)
+### Comparing one branch vs. another
+
+Simply run:
+
+```
+skunk -b <target-branch-name>
+```
+
+Then get a StinkScore average comparison:
+
+```
+$ skunk -b master
+Switched to branch 'master'
+running flay smells
+..
+running flog smells
+..............
+running reek smells
+..............
+running complexity
+..............
+running attributes
+..............
+running churn
+..............
+running simple_cov
+..............
+Switched to branch 'feature/compare'
+running flay smells
+..
+running flog smells
+.................
+running reek smells
+.................
+running complexity
+.................
+running attributes
+.................
+running churn
+.................
+running simple_cov
+.................
+Base branch (master) average stink score: 290.53999999999996
+Feature branch (feature/compare) average stink score: 340.3005882352941
+Score: 340.3
+```
+
+This should give you an idea if you're moving in the right direction or not.
+
## Known Issues
The StinkScore should be calculated per method. This would provide a more accurate
representation of the average StinkScore in a module.
@@ -111,6 +177,6 @@
To install this gem onto your local machine, run `bundle exec rake install`. 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](https://rubygems.org).
## Contributing
-Bug reports and pull requests are welcome on GitHub at https://github.com/fastruby/skunk.
+Bug reports and pull requests are welcome on GitHub at https://github.com/fastruby/skunk/issues.