README.md in skunk-0.5.2 vs README.md in skunk-0.5.3
- old
+ new
@@ -2,241 +2,189 @@
[](CODE_OF_CONDUCT.md) [](https://travis-ci.org/fastruby/skunk) [](https://codeclimate.com/github/fastruby/skunk/maintainability) [](http://rubydoc.info/gems/skunk) [](https://codecov.io/gh/fastruby/skunk)
-A RubyCritic extension to calculate SkunkScore for a file or project.
+Skunk is a RubyCritic extension to calculate a SkunkScore for a file or project. The SkunkScore is a value that assesses the technical debt of a module.
+## Table of contents
+* [What is the SkunkScore?](#what-is-the-skunkscore)
+* [Getting started](#getting-started)
+ * [Running SimpleCov](#running-simplecov)
+* [Usage](#usage)
+ * [Help commands](#help-commands)
+ * [Generate the SkunkCore for your project](#generate-the-skunkcore-for-your-project)
+ * [Comparing Feature Branches](#comparing-feature-branches)
+* [Sharing your SkunkScore](#sharing-your-skunkscore)
+* [Contributing](#contributing)
+* [Sponsorship](#sponsorship)
+
## What is the SkunkScore?
-The SkunkScore is a value that assesses the technical debt of a module. It takes
-into account:
+The main goal of the SkunkScore 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 my next test-writing efforts?
+- What are good candidates for my next refactoring efforts?
+
+To assess the technical debt of a module, Skunk takes into account:
- Code Complexity
- Code Smells
- Code Coverage
-The main goal of the SkunkScore is to serve as a compass in your next
-refactoring adventure. It will help you answer these questions:
+## Getting started
-- 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 next refactoring efforts?
+Start by including `skunk` in your Gemfile:
-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
gem 'skunk'
```
-And then execute:
+Then run `bundle`.
- $ bundle
+Or, install it yourself by running: `$ gem install skunk`
-Or install it yourself as:
+### Running SimpleCov to generate your Code Coverage report
+Use SimpleCov to generate a report of how many statements are covered by your test suite (code coverage). That's how `skunk` knows what's the status of your test suite + code coverage.
- $ gem install skunk
+Please refer to [SimpleCov's Getting Started Guide](https://github.com/simplecov-ruby/simplecov#getting-started) to install it and generate the coverage report.
+SimpleCov was successfully installed when it generated a JSON file under `coverage/.resultset.json` in your application directory.
+
+> :warning: Skunk runs `rubycritic`, which loads code coverage data from your `coverage/.resultset.json` file. Make sure to have this file for best SkunkScore results.
+
+**Note:** after adding more tests to your application, run SimpleCov again to generate an updated Code Coverage. This way, skunk will generate a new SkunkScore.
## Usage
-### Help details
+### Help commands
-There are not that many options but here they are:
+Run `skunk -h` to check out the help options:
```
-skunk -h
Usage: skunk [options] [paths]
-b, --branch BRANCH Set branch to compare
-o, --out FILE Output report to file
-v, --version Show gem's version
-h, --help Show this message
```
-### Getting a sorted list of smelly files
+### Generating the SkunkCore for your project
-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.
+The SkunkCore is a sorted list of smelly files. Skunk's report will be in the console. On the Ruby project you want to analyze, run:
-Then simply run:
-
```
skunk
```
-Then get a list of smelly files:
+The result is a list of smelly files and the SkunkScore of the project/files:
```
-$ skunk
-running flay smells
++-----------------------------------------------------+----------------+------------------+--------------+--------------+--------------+
+| file | skunk_score | churn_times_cost | churn | cost | coverage |
++-----------------------------------------------------+----------------+------------------+--------------+--------------+--------------+
+| samples/rubycritic/analysed_module.rb | 258.88 | 12.94 | 5 | 2.59 | 0.0 |
+| lib/skunk/commands/compare.rb | 85.41 | 32.32 | 14 | 2.31 | 63.64 |
+| lib/skunk/rubycritic/analysed_modules_collection.rb | 31.76 | 3.18 | 5 | 0.64 | 50.0 |
+| lib/skunk/commands/status_reporter.rb | 11.33 | 68.0 | 18 | 3.78 | 97.5 |
+| lib/skunk/command_factory.rb | 8.3 | 1.95 | 4 | 0.49 | 83.33 |
+| lib/skunk/commands/status_sharer.rb | 8.17 | 10.9 | 4 | 2.72 | 97.67 |
+| lib/skunk/cli/application.rb | 7.06 | 21.19 | 18 | 1.18 | 94.12 |
+| lib/skunk/cli/options/argv.rb | 4.08 | 7.35 | 9 | 0.82 | 95.24 |
+| lib/skunk/commands/compare_score.rb | 3.77 | 2.51 | 4 | 0.63 | 94.74 |
+| lib/skunk/rubycritic/analysed_module.rb | 3.37 | 33.74 | 10 | 3.37 | 100.0 |
+| lib/skunk/commands/version.rb | 2.64 | 0.7 | 8 | 0.09 | 70.0 |
+| lib/skunk/commands/output.rb | 1.86 | 0.09 | 1 | 0.09 | 80.0 |
+| lib/skunk/cli/options.rb | 0.68 | 5.44 | 8 | 0.68 | 100.0 |
+| lib/skunk/commands/default.rb | 0.4 | 3.23 | 8 | 0.4 | 100.0 |
+| lib/skunk/commands/shareable.rb | 0.2 | 0.4 | 2 | 0.2 | 100.0 |
+| lib/skunk/commands/help.rb | 0.2 | 1.2 | 6 | 0.2 | 100.0 |
+| lib/skunk/commands/base.rb | 0.1 | 0.49 | 5 | 0.1 | 100.0 |
+| lib/skunk.rb | 0.0 | 0.0 | 6 | 0.0 | 100.0 |
+| lib/skunk/version.rb | 0.0 | 0.0 | 12 | 0.0 | 0.0 |
++-----------------------------------------------------+----------------+------------------+--------------+--------------+--------------+
-running flog smells
-.............
-running reek smells
-.............
-running complexity
-.............
-running attributes
-.............
-running churn
-.............
-running simple_cov
-.............
-New critique at file:////Users/etagwerker/Projects/fastruby/skunk/tmp/rubycritic/overview.html
-+-----------------------------------------------------+----------------------------+----------------------------+----------------------------+----------------------------+----------------------------+
-| file | skunk_score | churn_times_cost | churn | cost | coverage |
-+-----------------------------------------------------+----------------------------+----------------------------+----------------------------+----------------------------+----------------------------+
-| lib/skunk/cli/commands/default.rb | 166.44 | 1.6643999999999999 | 3 | 0.5548 | 0 |
-| lib/skunk/cli/application.rb | 139.2 | 1.392 | 3 | 0.46399999999999997 | 0 |
-| lib/skunk/cli/command_factory.rb | 97.6 | 0.976 | 2 | 0.488 | 0 |
-| test/test_helper.rb | 75.2 | 0.752 | 2 | 0.376 | 0 |
-| lib/skunk/rubycritic/analysed_module.rb | 48.12 | 1.7184 | 2 | 0.8592 | 72.72727272727273 |
-| test/lib/skunk/cli/commands/status_reporter_test.rb | 45.6 | 0.456 | 1 | 0.456 | 0 |
-| lib/skunk/cli/commands/base.rb | 29.52 | 0.2952 | 3 | 0.0984 | 0 |
-| lib/skunk/cli/commands/status_reporter.rb | 8.0 | 7.9956 | 3 | 2.6652 | 100.0 |
-| test/lib/skunk/rubycritic/analysed_module_test.rb | 2.63 | 2.6312 | 2 | 1.3156 | 100.0 |
-| lib/skunk.rb | 0.0 | 0.0 | 2 | 0.0 | 0 |
-| lib/skunk/cli/options.rb | 0.0 | 0.0 | 2 | 0.0 | 0 |
-| lib/skunk/version.rb | 0.0 | 0.0 | 2 | 0.0 | 0 |
-| lib/skunk/cli/commands/help.rb | 0.0 | 0.0 | 2 | 0.0 | 0 |
-+-----------------------------------------------------+----------------------------+----------------------------+----------------------------+----------------------------+----------------------------+
-
-SkunkScore Total: 612.31
-Modules Analysed: 13
-SkunkScore Average: 0.47100769230769230769230769231e2
-Worst SkunkScore: 166.44 (lib/skunk/cli/commands/default.rb)
+SkunkScore Total: 428.21
+Modules Analysed: 19
+SkunkScore Average: 22.54
+Worst SkunkScore: 258.88 (samples/rubycritic/analysed_module.rb)
```
-The command will run `rubycritic` and it will try to load code coverage data
-from your `coverage/.resultset.json` file.
+With the report, you can answer [these refactoring questions](#what-is-the-skunkscore) with clarity.
-Skunk's report will be in the console. Use it wisely. :)
+In this example, the file `samples/rubycritic/analysed_module.rb` has the Worst SkunkScore. It means this file has a high code complexity, with lower code coverage. To decrease its SkunkScore, start by adding tests to it. Then, simplify the code to decrease the code complexity.
-### Comparing one branch vs. another
+Other great candidates are the files that have lower code coverage. By adding tests, their SkunkScore will decrease, and refactoring the code will be more achievable.
-Simply run:
+Skunk also gives you a SkunkScore Total value: it shows you the overall code quality of the project. As you decrease the SkunkScore of the files, the total score of the project will decrease.
+#### Excluding folders from the report
+
+To only run skunk on specific folders, pass a list of directories in the command line. For example, if you only want the report for the files under `app` and `lib`, run:
+
+`skunk app lib`
+
+### Comparing feature branches
+
+When working on new features, run skunk against your feature branch to check if the changes are improving or decreasing the code quality of the project.
+
+To generate the SkunkScore of your feature branch, run:
+
```
-skunk -b <target-branch-name>
+skunk -b <your-feature-branch-name>
```
-Then get a SkunkScore average comparison:
+Then, get a SkunkScore average comparison with `main` by running:
+`$ skunk -b main`
+
```
-$ 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 skunk score: 290.53999999999996
+Switched to branch 'main'
+....
+
+Base branch (main) average skunk score: 290.53999999999996
Feature branch (feature/compare) average skunk score: 340.3005882352941
Score: 340.3
```
-This should give you an idea if you're moving in the right direction or not.
+This should give you an idea if you're moving in the direction of maintaining the code quality or not. In this case, the feature branch is decreasing the code quality because it has a higher SkunkScore than the main branch.
-### Sharing results
+## Sharing your SkunkScore
-If you want to quickly share the results of your report, you can use an
-environment variable:
+If you want to share the results of your Skunk report with the Ruby community, run:
+`SHARE=true skunk app/`
+
```
-SHARE=true skunk app/
-...
SkunkScore Total: 126.99
Modules Analysed: 17
SkunkScore Average: 7.47
-Worst SkunkScore: 41.92 (lib/skunk/cli/commands/status_sharer.rb)
+Worst SkunkScore: 41.92 (lib/skunk/commands/status_sharer.rb)
Generated with Skunk v0.5.0
-Shared at: https://skunk.fastruby.io/k
+Shared at: https://skunk.fastruby.io/
```
-Results will be posted by default to https://skunk.fastruby.io which is a free
-and open source Ruby on Rails application sponsored by
-[OmbuLabs](https://www.ombulabs.com) ([source code](https://github.com/fastruby/skunk.fyi)).
+Results will be posted by default to https://skunk.fastruby.io which is a free and open source Ruby on Rails application sponsored by [OmbuLabs](https://www.ombulabs.com)([source code](https://github.com/fastruby/skunk.fyi)).
-If you prefer to post results to your own server, you can do so:
+If you prefer to post results to your server, set your own `SHARE_URL`:
+`$ SHARE_URL=https://path.to.your.skunk-fyi-server.example.com skunk app/`
+
```
-SHARE_URL=https://path.to.your.skunk-fyi-server.example.com skunk app/
-...
SkunkScore Total: 126.99
Modules Analysed: 17
SkunkScore Average: 7.47
-Worst SkunkScore: 41.92 (lib/skunk/cli/commands/status_sharer.rb)
+Worst SkunkScore: 41.92 (lib/skunk/commands/status_sharer.rb)
Generated with Skunk v0.5.0
-Shared at: https://path.to.your.skunk-fyi-server.example.com/k
+Shared at: https://path.to.your.skunk-fyi-server.example.com
```
-## Known Issues
-
-The SkunkScore should be calculated per method. This would provide a more accurate
-representation of the average SkunkScore in a module.
-
-I think that the SkunkScore of a module should be the average of the SkunkScores of
-all of its methods.
-
-Right now the SkunkScore is calculated using the totals for a module:
-
-- Total Code Coverage Percentage per Module
-- Total Churn per Module
-- Total Cost per Module
-
-For more details, feel free to review and improve this method: [RubyCritic::AnalysedModule#skunk_score]
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-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
+Have a fix for a problem you've been running into or an idea for a new feature you think would be useful? Want to see how you can support Skunk?
-Bug reports and pull requests are welcome on GitHub at [https://github.com/fastruby/skunk](https://github.com/fastruby/skunk). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fastruby/skunk/blob/main/CODE_OF_CONDUCT.md).
-
-When Submitting a Pull Request:
-
-* If your PR closes any open GitHub issues, please include `Closes #XXXX` in your comment.
-
-* Please include a summary of the change and which issue is fixed or which feature is introduced.
-
-* If changes to the behavior are made, clearly describe what changes.
-
-* If changes to the UI are made, please include screenshots of the before and after.
+Take a look at the [Contributing document](CONTRIBUTING.md) for instructions to set up the repo on your machine, check the Help Wanted section, and create a good Pull Request.
## Sponsorship
