license_finder 1.2 → 2.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2049a25200cf6a0cdad954f85359676042c62338
-  data.tar.gz: d5addeb14c9dd87defafcec6345212959e8a4603
+  metadata.gz: 272a63170ce7ba95ee485b5810c3d9bf525a0326
+  data.tar.gz: f6e7364050de7afec4d9ffb95f3e1d20cadb780f
 SHA512:
-  metadata.gz: ef837a059b9fb88d1cc0daa2cd64ed70c6e774579946b23dd056f88b44769ff5a6d3dc3736b9cd974b7868f0af9fbd1049522a0dce8a1b0276cf49f69333f7e7
-  data.tar.gz: eb1273739818c2d900079e7a7c2f1d0187f5a8651f23e92ba293e09541d865fbfbac4c22d3e99d7774c9fcc15ac4e390fd5031b81f2820717b8593d3894a7d6b
+  metadata.gz: 3207fee7de7b192aac50c45208931002322a0dbc8fb24e30adb072a28dbacc6e11567c210895bd88163f65de2df0095db2ba7d39a75966b9ad636ae2d0b3c1d6
+  data.tar.gz: 5dd187332ae0d7d61ebde94a3610c43b8a81ac60332bf963b3dab5518950f2ae7e6036c58d6570cd864d7bb038f2e3e96b70eb457686748eb31db33f0892e98a

data/.travis.yml

@@ -28,4 +28,5 @@ before_install:
   - unzip -q gradle*
   - rm gradle*.zip
   - mv gradle* ~/gradle
-  - cd -
+  - npm install -g bower
+  - cd -

data/CHANGELOG.rdoc

@@ -1,3 +1,30 @@
+=== 2.0.0 / unreleased
+
+* Features
+
+  * Stores (in an append-only YAML file) every decision that has been made
+    about a project's dependencies, even if a decision was later reverted.
+  * Stores timestamps and other metadata (who, why) about each decision.
+  * When needed, applies those decisions to the list of packages currently
+    reported by the package managers.
+  * The CLI never writes HTML or CSV reports to the file system, only to
+    STDOUT. So, users have more choice over which reports to generate, when to
+    generate them, and where to put them. See `license_finder report`.
+  * Removed dependencies on sqlite and sequel.
+  * Minimized the responsibilities of the configuration YAML file. The CLI
+    never updates the config file, which means less futzing with the file
+    system. Makes room for replacing the config file with command line options.
+
+* Bugfixes
+
+  * `license_finder` does not write anything to the file system, #94, #114, #117
+
+=== 1.2.1 / unreleased
+
+* Features
+
+  * Can list dependencies that were added manually
+
 === 1.2 / 2014-11-10
 
 * Features

data/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## TL;DR
+
+* Fork the project from https://github.com/pivotal/LicenseFinder
+* Create a feature branch.
+* Make your feature addition or bug fix. Please make sure there is appropriate test coverage.
+* Rebase on top of master.
+* Send a pull request.
+
+
+## Development Dependencies
+
+To successfully run the test suite, you will need node.js, python, pip
+and gradle installed. If you run `rake check_dependencies`, you'll see
+exactly what you're missing.
+
+### Python
+
+For the python dependency tests you will want to have virtualenv
+installed, to allow pip to work without sudo. For more details, see
+this [post on virtualenv][].
+
+  [post on virtualenv]: http://hackercodex.com/guide/python-development-environment-on-mac-osx/#virtualenv
+
+
+### JRuby
+
+If you're running the test suite with jruby, you're probably going to
+want to set up some environment variables:
+
+```
+JAVA_OPTS='-client -XX:+TieredCompilation -XX:TieredStopAtLevel=1' JRUBY_OPTS='-J-Djruby.launch.inproc=true'
+```
+
+### Gradle
+
+You'll need a gradle version >= 1.8.

data/README.md

@@ -21,7 +21,7 @@ report.
 * Node.js (via `npm`)
 * Bower
 
-### Experimental project types 
+### Experimental project types
 
 * Java (via `maven`)
 * Java (via `gradle`)
@@ -46,13 +46,12 @@ gem 'license_finder', :group => :development
 
 This approach helps you remember to install `license_finder`, but can
 pull in unwanted dependencies, including `bundler`. To mitigate this
-problem, see ignored_groups in [Configuration](#configuration).
+problem, see [Excluding Dependencies](#excluding-dependencies).
 
 
 ## Usage
 
-`license_finder` will generate reports of action items; i.e.,
-dependencies that do not fall within your license "whitelist".
+The first time you run `license_finder` it will output a report of all your project's packages.
 
 ```sh
 $ license_finder
@@ -64,6 +63,12 @@ Or, if you installed with bundler:
 $ bundle exec license_finder
 ```
 
+The output will report that none of your packages have been
+approved.  Over time you will tell `license_finder` which packages
+are approved, so when you run this command in the future, it will
+report current action items; i.e., packages that are new or have
+never been approved.
+
 If you don't wish to see progressive output "dots", use the `--quiet`
 option.
 
@@ -94,19 +99,80 @@ languages, as long as that language has a package definition in the project dire
 
 ### Continuous Integration
 
-`license_finder` will also return a non-zero exit status if there are
-unapproved dependencies. This can be useful for inclusion in a CI
-environment to alert you if someone adds an unapproved dependency to
-the project.
+`license_finder` will return a non-zero exit status if there are unapproved
+dependencies. This can be useful for inclusion in a CI environment to alert you
+if someone adds an unapproved dependency to the project.
+
+
+## Approving Dependencies
+
+`license_finder` will inform you whenever you have an unapproved dependency.
+If your business decides this is an acceptable risk, the easiest way to approve
+the dependency is by running `license_finder approval add`.
+
+For example, let's assume you've added the `awesome_gpl_gem`
+to your Gemfile, which `license_finder` reports is unapproved:
+
+```sh
+$ license_finder
+Dependencies that need approval:
+awesome_gpl_gem, 1.0.0, GPL
+```
+
+Your business tells you that in this case, it's acceptable to use this
+gem. You now run:
+
+```sh
+$ license_finder approval add awesome_gpl_gem
+```
+
+If you rerun `license_finder`, you should no longer see
+`awesome_gpl_gem` in the output.
+
+To record who approved the dependency and why:
+
+```sh
+$ license_finder approval add awesome_gpl_gem --who CTO --why "Go ahead"
+```
+
+### Whitelisting
+
+Approving packages one-by-one can be tedious.  Usually your business has
+blanket policies about which packages are approved.  To tell `license_finder`
+that any package with the MIT license should be approved, run:
+
+``` sh
+$ license_finder whitelist add MIT
+```
+
+Any current or future packages with the MIT license will be excluded from the
+output of `license_finder`.
+
+You can also record `--who` and `--why` when changing the whitelist, or making
+any other decision about your project.
 
 
 ## Output and Artifacts
 
-### STDOUT
+### Decisions file
+
+Any decisions you make about approvals will be recorded in a YAML file.  Be
+default, `license_finder` expects it to be named
+`doc/dependency_decisions.yml`.  All commands can be passed `--decisions_file`
+to override this location.  See [Configuration](#configuration) for other
+options.
+
+This file must be committed to version control.  Rarely, you will have to
+manually resolve conflicts in it.  In this situation, keep in mind that each
+decision has an associated timestamp, and the decisions are processed
+top-to-bottom, with later decisions overwriting or appending to earlier
+decisions.
+
+### Output from `action_items`
 
-On a Rails project, you could expect `license_finder` to output
-something like the following (assuming you whitelisted the MIT license
--- see [Configuration](#configuration)):
+You could expect `license_finder`, which is an alias for `license_finder
+action_items` to output something like the following on a Rails project where
+MIT had been whitelisted:
 
 ```
 Dependencies that need approval:
@@ -114,77 +180,46 @@ Dependencies that need approval:
 highline, 1.6.14, ruby
 json, 1.7.5, ruby
 mime-types, 1.19, ruby
-rails, 3.2.8, other
-rdoc, 3.12, other
+rails, 3.2.8, unknown
+rdoc, 3.12, unknown
 rubyzip, 0.9.9, ruby
-xml-simple, 1.1.1, other
+xml-simple, 1.1.1, unknown
 ```
 
-### Files and Reports
+You can customize the format of the output in the same way that you customize
+[output from `report`](#output-from-report).
 
-The executable task will also write out a `dependencies.db`,
-`dependencies.csv`, and `dependencies.html` file (in the `doc/`
-directory by default -- see [Configuration](#configuration)).
+### Output from `report`
 
-The latter two files are human-readable reports that you could send to
-your non-technical business partners, lawyers, etc.
+The `license_finder report` command will output human-readable reports that you
+could send to your non-technical business partners, lawyers, etc.  You can
+choose the format of the report (text, csv, html or markdown); see
+`license_finder --help report` for details.  The output is sent to STDOUT, so
+you can save the reports wherever you want them.  You can commit them to
+version control if you like.
 
-The HTML report generated by `license_finder` shows a summary of the
-project's dependencies and dependencies which need to be approved. The
-project name at the top of the report can be set in
-`config/license_finder.yml`.
+The HTML report generated by `license_finder report --format html` summarizes
+all of your project's dependencies and includes information about which need to
+be approved. The project name at the top of the report can be set with
+`license_finder project_name add`.
 
 
 ## Manual Intervention
 
 ### Setting Licenses
 
-When `license_finder` reports that a dependency's license is 'other',
+When `license_finder` reports that a dependency's license is 'unknown',
 you should manually research what the actual license is.  When you
 have established the real license, you can record it with:
 
 ```sh
-$ license_finder license MIT my_unknown_dependency
+$ license_finder licenses add my_unknown_dependency MIT
 ```
 
 This command would assign the MIT license to the dependency
 `my_unknown_dependency`.
 
 
-### Approving Dependencies
-
-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 using
-the `license_finder approve` command.
-
-For example, let's 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 `license_finder` and see the gem listed in the
-output:
-
-```sh
-awesome_gpl_gem, 1.0.0, GPL
-```
-
-Your business tells you that in this case, it's acceptable to use this
-gem. You now run:
-
-```sh
-$ license_finder approve awesome_gpl_gem
-```
-
-If you rerun `license_finder`, you should no longer see
-`awesome_gpl_gem` in the output.
-
-To record who approved the dependency and why:
-
-```sh
-$ license_finder approve awesome_gpl_gem --approver CTO --message "Go ahead"
-```
-
-
 ### Adding Hidden Dependencies
 
 `license_finder` can track dependencies that your package managers
@@ -192,22 +227,10 @@ don't know about (JS libraries that don't appear in your
 Gemfile/requirements.txt/package.json, etc.)
 
 ```sh
-$ license_finder dependencies add MIT my_js_dep 0.1.2
+$ license_finder dependencies add my_js_dep MIT 0.1.2
 ```
 
-To automatically approve an unmanaged dependency when you add it, use:
-
-```sh
-$ license_finder dependencies add MIT my_js_dep 0.1.2 --approve
-```
-
-To record who approved the dependency when you add it, use:
-
-```sh
-$ license_finder dependencies add MIT my_js_dep 0.1.2 --approve --approver CTO --message "Go ahead"
-```
-
-The version is optional.  Run `license_finder dependencies help` for
+Run `license_finder dependencies help` for
 additional documentation about managing these dependencies.
 
 `license_finder` cannot automatically detect when one of these
@@ -217,71 +240,55 @@ dependencies has been removed from your project, so you can use:
 $ license_finder dependencies remove my_js_dep
 ```
 
+### Excluding Dependencies
+
+Sometimes a project will have development or test dependencies which
+you don't want to track.  You can exclude theses dependencies by running
+`license_finder ignored_groups`.  (Currently this only works for packages
+managed by Bundler.)
+
+On rare occasions a package manager will report an individual dependency
+that you want to exclude from all reports, even though it is approved.
+You can exclude an individual dependency by running
+`license_finder ignored_dependencies`.  Think carefully before adding
+dependencies to this list.  A likely item to exclude is `bundler`,
+since it is a common dependency whose version changes from machine to
+machine.  Adding it to the `ignored_dependencies` would prevent it
+(and its oscillating versions) from appearing in reports.
+
 
 ## Configuration
 
-The first time you run `license_finder` it will create a default
-configuration file `./config/license_finder.yml`, which will look
-something like this:
+It may be difficult to remember to pass command line options to every command.
+In some of these cases you can store default values in a YAML formatted config
+file. `license_finder` looks for this file in `config/license_finder.yml`.
+
+As an example, the file might look like this:
 
 ```yaml
 ---
-whitelist:
-#- MIT
-#- Apache 2.0
-ignore_groups:
-#- test
-#- development
-ignore_dependencies:
-#- bundler
-dependencies_file_dir: './doc/'
-project_name: My Project Name
-gradle_command: # only meaningful if used with a Java/gradle project. Defaults to "gradle".
+decisions_file: './some_path/decisions.yml'
+gradle_command: './gradlew'
 ```
 
-By modifying this file, you can configure `license_finder`'s behavior:
-
-* Automatically approve licenses in the `whitelist`
-* Exclude test or development dependencies by setting `ignore_groups`.
-  (Currently this only works for Bundler.)
-* Exclude specific dependencies by setting `ignore_dependencies`.
-  (Think carefully before adding dependencies to this list. A likely
-  item to exclude is bundler itself, to avoid noisy changes to the doc
-  files when different people run `license_finder` with different
-  versions of bundler.)
-* Store the license database and text files in another directory by
-  changing `dependencies_file_dir`.
-* Set the HTML report title wih `project_name`, which defaults to the
-  name of the working directory.
-* See below for explanation of "gradle_command".
-
-You can also configure `license_finder` through the command line.  See
-`license_finder whitelist help`, `license_finder ignored_bundler_groups help`
-and `license_finder project_name help` for more details.
+If you set `decisions_file`, you won't have to pass it to every CLI command.
 
+Read on to learn about how `gradle_command` is used on gradle projects.
 
 ### Gradle Projects
 
 You need to install the license gradle plugin:
 [https://github.com/hierynomus/license-gradle-plugin](https://github.com/hierynomus/license-gradle-plugin)
 
-LicenseFinder assumes that gradle is in your shell's command path and
-can be invoked by just calling `gradle`.
+LicenseFinder assumes that gradle is in your shell's command path and can be
+invoked by just calling `gradle`.  If you must invoke gradle some other way
+(e.g., with a custom `gradlew` script), pass `--gradle_command` to
+`license_finder` or `license_finder report`.
 
-If you must invoke gradle some other way (e.g., with a custom
-`gradlew` script), set the `gradle_command` option in your project's
-`license_finder.yml`:
-
-```yaml
-# ... other configuration ...
-gradle_command: ./gradlew
-```
-
-By default, `license_finder` will report on gradle's "runtime"
-dependencies. If you want to generate a report for some other
-dependency configuration (e.g. Android projects will sometimes specify
-their meaningful dependencies in the "compile" group), you can specify
-it in your project's `build.gradle`:
+By default, `license_finder` will report on gradle's "runtime" dependencies. If
+you want to generate a report for some other dependency configuration (e.g.
+Android projects will sometimes specify their meaningful dependencies in the
+"compile" group), you can specify it in your project's `build.gradle`:
 
 ```
 // Must come *after* the 'apply plugin: license' line
@@ -292,20 +299,15 @@ downloadLicenses {
 ```
 
 
-## Upgrade for pre-0.8.0 users
-
-If you wish to cleanup your root directory you can run:
-
-```sh
-$ license_finder move
-```
+## Requirements
 
-This will move your `dependencies.*` files to the doc/ directory and update the config.
+`license_finder` requires ruby >= 1.9, or jruby.
 
 
-## Requirements
+## Upgrading
 
-`license_finder` requires ruby >= 1.9, or jruby.
+To upgrade from `license_finder` version ~1.2 to 2.0, see
+[`license_finder_upgrade`](https://github.com/mainej/license_finder_upgrade).
 
 
 ## A Plea to Package Authors and Maintainers
@@ -313,7 +315,7 @@ This will move your `dependencies.*` files to the doc/ directory and update the
 Please add a license to your package specs! Most packaging systems
 allow for the specification of one or more licenses.
 
-For example, Ruby Gems may have a license specified by name:
+For example, Ruby Gems can specify a license by name:
 
 ```ruby
 Gem::Specification.new do |s|
@@ -322,7 +324,7 @@ Gem::Specification.new do |s|
 end
 ```
 
-And add a `LICENSE` file to your package that contains your license text.
+And save a `LICENSE` file which contains your license text in your repo.
 
 
 ## Support
@@ -333,30 +335,8 @@ And add a `LICENSE` file to your package that contains your license text.
 
 ## Contributing
 
-* Fork the project from https://github.com/pivotal/LicenseFinder
-* Create a feature branch.
-* Make your feature addition or bug fix. Please make sure there is appropriate test coverage.
-* Rebase on top of master.
-* Send a pull request.
-
-To successfully run the test suite, you will need node.js, python, pip
-and gradle installed. If you run `rake check_dependencies`, you'll see
-exactly what you're missing.
-
-You'll need a gradle version >= 1.8.
+See [CONTRIBUTING.md](https://github.com/pivotal/LicenseFinder/blob/master/CONTRIBUTING.md).
 
-For the python dependency tests you will want to have virtualenv
-installed, to allow pip to work without sudo. For more details, see
-this [post on virtualenv][].
-
-  [post on virtualenv]: http://hackercodex.com/guide/python-development-environment-on-mac-osx/#virtualenv
-
-If you're running the test suite with jruby, you're probably going to
-want to set up some environment variables:
-
-```
-JAVA_OPTS='-client -XX:+TieredCompilation -XX:TieredStopAtLevel=1' JRUBY_OPTS='-J-Djruby.launch.inproc=true'
-```
 
 ## License