README.markdown in license_finder-0.5.0 vs README.markdown in license_finder-0.6.0

- old
+ new

@@ -1,57 +1,80 @@ # License Finder [![Build Status](https://secure.travis-ci.org/pivotal/LicenseFinder.png)](http://travis-ci.org/pivotal/LicenseFinder) +[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/pivotal/LicenseFinder) With bundler it's easy for your project to depend on many gems. This decomposition is nice, but managing licenses becomes difficult. This tool gathers info about the licenses of the gems in your project. ## Installation -===== Add license_finder to your Rails project's Gemfile and `bundle`: ```ruby -gem 'license_finder', :git => "https://github.com/pivotal/LicenseFinder.git" +gem 'license_finder' ``` -Now, initialize license finder: +## Usage +License finder will generate reports of action items - i.e., dependencies that do not fall within your license "whitelist". + ```sh -$ bundle exec rake license:init +$ bundle exec license_finder ``` -This will create a `config/license_finder.yml` file that lets you configure license finder. -This is where you should add licenses which are allowed on the project, so they will be automatically approved. +The first time you run this, `license_finder` will create a default configuration file `./config/license_finder.yml`: -## Usage -Once you've whitelisted licenses, you can then tell license finder to analyze your Gemfile and generate a list of -dependencies that have non-whitelisted licenses: +```yaml +--- +whitelist: +#- MIT +#- Apache 2.0 +ignore_groups: +#- test +#- development +``` -```sh -$ bundle exec rake license:action_items +This allows you to configure bundler groups and add licenses to the whitelist. + +On a brand new Rails project, you could expect `license_finder` to output something like the following +(assuming you whitelisted the MIT license in your `config/license_finder.yml`): + ``` +Dependencies that need approval: -This will write out a dependencies.yml and dependencies.txt file in the root of your project, as well as -output a list of unapproved dependencies to the console. It will also return a non-zero exit status if there +highline, 1.6.14, ruby +json, 1.7.5, ruby +mime-types, 1.19, ruby +rails, 3.2.8, other +rdoc, 3.12, other +rubyzip, 0.9.9, ruby +xml-simple, 1.1.1, other +``` + +The executable task will also write out a dependencies.yml, dependencies.txt, and dependencies.html file in the root of your project. + +The latter two files are human readable reports that you could send to your non-technical business partners, lawyers, etc. + +`license_finder` will also return a non-zero exit status if there are unapproved dependencies. You could use this in a CI build, for example, to alert you whenever someone adds an unapproved dependency to the project. It will also merge in an existing dependencies.yml file, if one exists (i.e., you've previously run this command and then edited the resulting file). ### Manually approving dependencies -Whenever you have a dependency that falls outside of your whitelist, `rake license:action_items` will tell you. +Whenever you have a dependency that falls outside of your whitelist, `license_finder` will tell you. If your business decides that this is an acceptable risk, you can manually approve the dependency by finding its section in the `dependencies.yml` file and setting its `approved` attribute to true. For example, lets assume you've only whitelisted the "MIT" license in your `config/license_finder.yml`. You then add the 'awesome_gpl_gem' to your Gemfile, -which we'll assume is licensed with the `GPL` license. You then run `rake license_finder:action_items` and see +which we'll assume is licensed with the `GPL` license. You then run `license_finder` and see the gem listed in the output: ```txt -awesome_gpl_gem 1.0.0, GPL +awesome_gpl_gem, 1.0.0, GPL ``` Your business tells you that in this case, it's acceptable to use this gem. You should now update your `dependencies.yml` file, setting the `approved` attribute to `true` for the `awesome_gpl_gem` section: @@ -60,11 +83,11 @@ version: 1.0.0 license: GPL approved: true ``` -If you rerun `rake license:action_items`, you should no longer see `awesome_gpl_gem` in the output. +If you rerun `license_finder`, you should no longer see `awesome_gpl_gem` in the output. ## Manually managing Javascript Dependencies License Finder currently has no method for automatically detecting third-party javascript libraries in your application @@ -80,94 +103,31 @@ You could then update the "approved" attribute to true once you have signoff from your business. License Finder will remember any manually added licenses between successive runs. -## Usage outside Rails +## Usage with Rake -As a standalone script: +First, add license finder to your project's Gemfile: -```sh -$ git clone http://github.com/pivotal/LicenseFinder.git license_finder -$ cd /path/to/your/project -$ /path/to/license_finder/bin/license_finder +```ruby +gem "license_finder" ``` -Optionally add `--with-licenses` to include the full text of the licenses in the output. +Next, update your project's Rakefile with the license finder rake task: - -## Sample Output - -File: `config/license_finder.yml`: - -```yaml ---- -whitelist: -- MIT -- Apache 2.0 -ignore_groups: -- test -- development +```ruby +require 'bundler/setup' +require 'license_finder' +LicenseFinder.load_rake_tasks ``` -File: `dependencies.yml`: +You can now run `bundle exec rake license_finder`. This is the equivalent of running `bundle exec license_finder`. -```yaml ---- -- name: "json_pure" - version: "1.5.1" - license: "other" - approved: false +This could be handy if you have a build for CI that you want to break when you have unapproved dependencies. The +rake task will `exit 1` immediately if there are unapproved dependencies, stopping your build dead in its tracks! -- name: "rake" - version: "0.8.7" - license: "MIT" - approved: true -``` - -File: `dependencies.txt`: - - json_pure 1.5.1, other - rake 0.8.7, MIT - -File: `bin/license_finder`: - -```yaml ---- -json_pure 1.5.1: - dependency_name: json_pure - dependency_version: 1.5.1 - install_path: /some/path/.rvm/gems/ruby-1.9.2-p180/gems/json_pure-1.5.1 - license_files: - - file_name: COPYING - header_type: other - body_type: other - disclaimer_of_liability: other - - file_name: COPYING-json-jruby - header_type: other - body_type: other - disclaimer_of_liability: other - readme_files: - - file_name: README - mentions_license: true - - file_name: README-json-jruby.markdown - mentions_license: false ---- -rake 0.8.7: - dependency_name: rake - dependency_version: 0.8.7 - install_path: /some/path/.rvm/gems/ruby-1.9.2-p180/gems/rake-0.8.7 - license_files: - - file_name: MIT-LICENSE - header_type: other - body_type: mit - disclaimer_of_liability: "mit: THE AUTHORS OR COPYRIGHT HOLDERS" - readme_files: - - file_name: README - mentions_license: true -``` - ## A note to gem authors / maintainers For the good of humanity, please add a license to your gemspec! ```ruby @@ -176,5 +136,9 @@ s.license = "MIT" end ``` And add a `LICENSE` file to your gem that contains your license text. + +## License + +LicenseFinder is released under the terms of the MIT License. http://www.opensource.org/licenses/mit-license