website/docs: clarify plugin development with latest changes

website/docs/source/v2/plugins/development-basics.html.md

@@ -27,6 +27,45 @@ using [RubyGems](http://rubygems.org/). Familiarity with Ruby is required,
 but the [packaging and distribution](/v2/plugins/packaging.html) section should help
 guide you to packaging your plugin into a RubyGem.
 
+## Setup and Workflow
+
+Because plugins are packaged as RubyGems, Vagrant plugins should be
+developed as if you were developing a regular RubyGem. The easiest
+way to do this is to use the `bundle gem` command.
+
+Once the directory structure for a RubyGem is setup, you'll want
+to modify your Gemfile. Here is the basic structure of a Gemfile for
+Vagrant plugin development:
+
+```ruby
+source "https://rubygems.org"
+
+group :development do
+  gem "vagrant", :git => "https://github.com/mitchellh/vagrant.git"
+end
+
+group :plugins do
+  gem "my-vagrant-plugin", path: "."
+end
+```
+
+This Gemfile gets "vagrant" for development. This allows you to
+`bundle exec vagrant` to run Vagrant with your plugin already loaded,
+so that you can test it manually that way.
+
+The only thing about this Gemfile that may stand out as odd is the
+"plugins" group and putting your plugin in that group. Because
+`vagrant plugin` commands don't work in development, this is how
+you "install" your plugin into Vagrant. Vagrant will automatically
+load any gems listed in the "plugins" group. Note that this also
+allows you to add multiple plugins to Vagrant for development, if
+your plugin works with another plugin.
+
+With this structure in place, your workflow should be like any other
+Ruby project. When you want to manually test your plugin, use
+`bundle exec vagrant` in order to run Vagrant with your plugin
+loaded (as we specified in the Gemfile).
+
 ## Plugin Definition
 
 All plugins are required to have a definition. A definition contains details

website/docs/source/v2/plugins/packaging.html.md

@@ -51,6 +51,34 @@ for a good example.
 	</p>
 </div>
 
+Once the directory structure for a RubyGem is setup, you'll want
+to modify your Gemfile. Here is the basic structure of a Gemfile for
+Vagrant plugin development:
+
+```ruby
+source "https://rubygems.org"
+
+group :development do
+  gem "vagrant", :git => "https://github.com/mitchellh/vagrant.git"
+end
+
+group :plugins do
+  gem "my-vagrant-plugin", path: "."
+end
+```
+
+This Gemfile gets "vagrant" for development. This allows you to
+`bundle exec vagrant` to run Vagrant with your plugin already loaded,
+so that you can test it manually that way.
+
+The only thing about this Gemfile that may stand out as odd is the
+"plugins" group and putting your plugin in that group. Because
+`vagrant plugin` commands don't work in development, this is how
+you "install" your plugin into Vagrant. Vagrant will automatically
+load any gems listed in the "plugins" group. Note that this also
+allows you to add multiple plugins to Vagrant for development, if
+your plugin works with another plugin.
+
 Next, create a `Rakefile` that has at the very least, the following
 contents:
 
@@ -69,33 +97,14 @@ for a more comprehensive example that includes testing.
 
 ## Testing Your Plugin
 
-You have a couple options for testing your plugin. First, you can run
+To manually test your plugin during development, use
-`rake package`, then `vagrant plugin install` the resulting file to
+`bundle exec vagrant` to execute Vagrant with your plugin loaded
-test it. The downside of this is that there is a pretty slow feedback
+(thanks to the Gemfile setup we did earlier).
-loop every time you want to test the plugin.
 
-Alternatively, you can depend on Vagrant from your Gemfile for development
+For automated testing, the
-purposes only. Then you can use `bundle exec vagrant` and a Vagrantfile
+[vagrant-spec](https://github.com/mitchellh/vagrant-spec)
-in your own directory to test it. This has a fast feedback loop, but requires
+project provides helpers for both unit and acceptance testing
-that Vagrant has all the dependencies it needs installed on your system.
+plugins. See the giant README for that project for a detailed
-
+description of how to integrate vagrant-spec into your project.
-vagrant-aws uses the second option. You can see the dependency in the
+Vagrant itself (and all of its core plugins) use vagrant-spec
-[Gemfile](https://github.com/mitchellh/vagrant-aws/blob/master/Gemfile).
+for automated testing.
-The Vagrantfile is gitignored so that sensitive and volatile test
-information can be put into it. The important bit is that the Vagrantfile
-must have a `Vagrant.require_plugin` call so that it is loaded, since
-Vagrant doesn't automatically know about plugins not installed using
-`vagrant plugin`.
-
-For example, a vagrant-aws development Vagrantfile might look like this:
-
-```ruby
-Vagrant.require_plugin "vagrant-aws"
-
-Vagrant.configure("2") do |config|
-  config.vm.box = "test"
-end
-```
-
-Then you can run `bundle exec vagrant up` to test it. Note the "bundle exec"
-is required so that Bundler uses the proper Vagrant installation.