http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 BACKWARDS INCOMPATIBILITY:
 
+  - Plugin activation is now triggered by the `cache.scope` config and that config
+    is now required. Previous versions of the plugin had it set to `:box` but
+    there is no consensus whether `:box` and `:machine` is better. This is to
+    highlight that you need to think about the caching strategy you are going
+    to use. For more information and to discuss this move please check [GH-17](https://github.com/fgrehm/vagrant-cachier/issues/17).
+  - Because `cache.scope` is now a requirement and in order to reduce the amount of
+    configuration required by the plugin, we enabled automatic bucket detection by
+    default. To revert to the old behavior you can disable it globally from your
+    `~/.vagrant.d/Vagrantfile`.
   - Support for Vagrant < 1.4 is gone, please use a previous plugin version if
     you are running Vagrant 1.2 / 1.3
   - Automatic handling of multiple machine scoped cache dirs from versions

README.md

@@ -17,15 +17,13 @@ vagrant plugin install vagrant-cachier
 
 ## Quick start
 
-The easiest way to set things up is just to enable [cache buckets auto detection](http://fgrehm.viewdocs.io/vagrant-cachier/usage)
-from within your `Vagrantfile`:
-
 ```ruby
 Vagrant.configure("2") do |config|
   config.vm.box = 'your-box'
   if Vagrant.has_plugin?("vagrant-cachier")
-    # Enable cache buckets auto detection
+    # Configure cached packages to be shared between instances of the same base box.
-    config.cache.auto_detect = true
+    # More info on http://fgrehm.viewdocs.io/vagrant-cachier/usage
+    config.cache.scope = :box
 
     # If you are using VirtualBox, you might want to use that to enable NFS for
     # shared folders. This is also very useful for vagrant-libvirt if you want

docs/index.md

@@ -24,12 +24,9 @@ from within your `Vagrantfile`:
 Vagrant.configure("2") do |config|
   config.vm.box = 'your-box'
   if Vagrant.has_plugin?("vagrant-cachier")
-    # Enable cache buckets auto detection
+    # Configure cached packages to be shared between instances of the same base box.
-    config.cache.auto_detect = true
+    # More info on the "Usage" link above
-
+    config.cache.scope = :box
-    # You can pass in extra mount options for your cache buckets
-    # from http://docs.vagrantup.com/v2/synced-folders/basic_usage.html
-    config.cache.synced_folder_opts = { create: true }
 
     # If you are using VirtualBox, you might want to use that to enable NFS for
     # shared folders. This is also very useful for vagrant-libvirt if you want

docs/usage.md

@@ -1,24 +1,76 @@
 # Usage
 
-## Auto detect supported cache buckets
+## Being nice to others
 
-This is the easiest way to get started with plugin. By adding the code below to
-your `Vagrantfile` you can enable automatic detection of supported cache _buckets_.
 It is a good practice to wrap plugin specific configuration with `has_plugin?` checks
-so the user's Vagrantfiles do not break if vagrant-cachier is uninstalled or
+so the user's Vagrantfiles do not break if `vagrant-cachier` is uninstalled or
-the Vagrantfile is shared with people that don't have the plugin installed.
+the Vagrantfile is shared with people that don't have the plugin installed:
 
 ```ruby
 Vagrant.configure("2") do |config|
   # ...
   if Vagrant.has_plugin?("vagrant-cachier")
-    config.cache.auto_detect = true
+    # ... vagrant-cachier configs ...
   end
 end
 ```
 
-This will make `vagrant-cachier` do its best to find out what is supported on the
+## Cache scope
-guest machine and will set buckets accordingly.
+
+This is the only required configuration for the plugin to work and should be present
+on your project's specific `Vagrantfile` or on your `~/.vagrant.d/Vagrantfile` in
+order to enable it.
+
+### `:box` scope
+
+By setting `cache.scope` to `:box`, downloaded packages will get stored on a folder
+scoped to base boxes under your `~/.vagrant.d/cache`. The idea is to leverage the
+cache by allowing downloaded packages to be reused across projects. So, if your
+`Vagrantfile` has something like:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = 'some-box'
+  if Vagrant.has_plugin?("vagrant-cachier")
+    config.cache.scope = :box
+  end
+end
+```
+
+The cached files will be stored under `$HOME/.vagrant.d/cache/some-box`.
+
+### `:machine` scope
+
+If you are on a [multi VM environment](http://docs.vagrantup.com/v2/multi-machine/index.html),
+there is a huge chance that you'll end up having issues by sharing the same bucket
+across different machines. For example, if you `apt-get install` from two machines
+at "almost the same time" you are probably going to hit a _"SystemError: Failed to
+lock /var/cache/apt/archives/lock"_. To work around that, you can set the scope
+to be based on machines:
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = 'some-box'
+  if Vagrant.has_plugin?("vagrant-cachier")
+    config.cache.scope = :machine
+  end
+end
+```
+
+This will tell vagrant-cachier to download packages to `.vagrant/machines/<machine-name>/cache`
+on your current project directory.
+
+## Cache buckets automatic detection
+
+This is the easiest way to get started with plugin and is enabled by default.
+Under the hood, `vagrant-cachier` does its best to find out what is supported on the
+guest machine and will set buckets accordingly
+
+
+By adding the code below to
+your `Vagrantfile` you can enable automatic detection of supported cache _buckets_.
+
+This will make .
 
 ## Enable buckets as needed
 
@@ -57,40 +109,6 @@ end
 Please referer to http://docs.vagrantup.com/v2/synced-folders/basic_usage.html for
 more information about the supported parameters.
 
-## Cache scope
-
-By default downloaded packages will get stored on a folder scoped to base boxes
-under your `$HOME/.vagrant.d/cache`. The idea is to leverage the cache by allowing
-downloaded packages to be reused across projects. So, if your `Vagrantfile` has
-something like:
-
-```ruby
-Vagrant.configure("2") do |config|
-  config.vm.box = 'some-box'
-  config.cache.auto_detect = true
-end
-```
-
-The cached files will be stored under `$HOME/.vagrant.d/cache/some-box`.
-
-If you are on a [multi VM environment](http://docs.vagrantup.com/v2/multi-machine/index.html),
-there is a huge chance that you'll end up having issues by sharing the same bucket
-across different machines. For example, if you `apt-get install` from two machines
-at "almost the same time" you are probably going to hit a _"SystemError: Failed to
-lock /var/cache/apt/archives/lock"_. To work around that, you can set the scope
-to be based on machines:
-
-```ruby
-Vagrant.configure("2") do |config|
-  config.vm.box = 'some-box'
-  config.cache.scope = :machine
-end
-```
-
-This will tell vagrant-cachier to download packages to `.vagrant/machines/<machine-name>/cache`
-on your current project directory.
-
-
 ## Finding out disk space used by buckets
 
 At some point we might implement a `vagrant cache stats` command that will give you that

vagrant-cachier.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.version       = VagrantPlugins::Cachier::VERSION
   spec.authors       = ["Fabio Rehm"]
   spec.email         = ["fgrehm@gmail.com"]
-  spec.description   = %q{Speed up vagrant boxes provisioning}
+  spec.description   = %q{Caffeine reducer}
   spec.summary       = spec.description
   spec.homepage      = "https://github.com/fgrehm/vagrant-cachier"
   spec.license       = "MIT"
@@ -17,4 +17,14 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
+
+  spec.post_install_message = %q{
+  If you are new to vagrant-cachier just follow along with the docs available
+  at http://fgrehm.viewdocs.io/vagrant-cachier.
+
+  If you are a long time user, please note that plugin has gone through many
+  backwards incompatible changes since 0.6.0 so checkout
+  https://github.com/fgrehm/vagrant-cachier/blob/master/CHANGELOG.md
+  before continuing and caching all the things :)
+  }
 end