Merge pull request #465 from puppetlabs/release-prep-for-2.0

Release prep for v2.0.0

CONTRIBUTING.md

@@ -1,9 +1,6 @@
 # How to contribute
 
-Third-party patches are essential for keeping vmpooler great. We want to keep it as easy as possible to contribute changes that
-get things working in your environment. There are a few guidelines that we
-need contributors to follow so that we can have a chance of keeping on
-top of things.
+Third-party patches are essential for keeping VMPooler great. We want to keep it as easy as possible to contribute changes that get things working in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
 
 ## Getting Started
 
@@ -18,28 +15,25 @@ top of things.
 
 * Create a topic branch from where you want to base your work.
   * This is usually the master branch.
-  * Only target release branches if you are certain your fix must be on that
-    branch.
-  * To quickly create a topic branch based on master; `git checkout -b
-    fix/master/my_contribution master`. Please avoid working directly on the
-    `master` branch.
+  * Only target release branches if you are certain your fix must be on that branch.
+  * To quickly create a topic branch based on master: `git checkout -b fix/master/my_contribution master`. Please avoid working directly on the `master` branch.
 * Make commits of logical units.
 * Check for unnecessary whitespace with `git diff --check` before committing.
 * Make sure your commit messages are in the proper format.
 
-````
-    (POOLER-1234) Make the example in CONTRIBUTING imperative and concrete
+```plain
+(POOLER-1234) Make the example in CONTRIBUTING imperative and concrete
 
-    Without this patch applied the example commit message in the CONTRIBUTING
-    document is not a concrete example.  This is a problem because the
-    contributor is left to imagine what the commit message should look like
-    based on a description rather than an example.  This patch fixes the
-    problem by making the example concrete and imperative.
+Without this patch applied the example commit message in the CONTRIBUTING
+document is not a concrete example.  This is a problem because the
+contributor is left to imagine what the commit message should look like
+based on a description rather than an example.  This patch fixes the
+problem by making the example concrete and imperative.
 
-    The first line is a real life imperative statement with a ticket number
-    from our issue tracker.  The body describes the behavior without the patch,
-    why this is a problem, and how the patch fixes the problem when applied.
-````
+The first line is a real life imperative statement with a ticket number
+from our issue tracker.  The body describes the behavior without the patch,
+why this is a problem, and how the patch fixes the problem when applied.
+```
 
 * Make sure you have added the necessary tests for your changes.
 * Run _all_ the tests to assure nothing else was accidentally broken.
@@ -48,36 +42,32 @@ top of things.
 
 ### Documentation
 
-For changes of a trivial nature to comments and documentation, it is not
-always necessary to create a new ticket in Jira. In this case, it is
-appropriate to start the first line of a commit with '(doc)' instead of
-a ticket number.
+For changes of a trivial nature to comments and documentation, it is not always necessary to create a new ticket in Jira. In this case, it is appropriate to start the first line of a commit with '(doc)' instead of a ticket number.
 
-````
-    (doc) Add documentation commit example to CONTRIBUTING
+```plain
+(doc) Add documentation commit example to CONTRIBUTING
 
-    There is no example for contributing a documentation commit
-    to the Puppet repository. This is a problem because the contributor
-    is left to assume how a commit of this nature may appear.
+There is no example for contributing a documentation commit
+to the Puppet repository. This is a problem because the contributor
+is left to assume how a commit of this nature may appear.
 
-    The first line is a real life imperative statement with '(doc)' in
-    place of what would have been the ticket number in a
-    non-documentation related commit. The body describes the nature of
-    the new documentation or comments added.
-````
+The first line is a real life imperative statement with '(doc)' in
+place of what would have been the ticket number in a
+non-documentation related commit. The body describes the nature of
+the new documentation or comments added.
+```
 
 ## Submitting Changes
 
-* Sign the [Contributor License Agreement](http://links.puppetlabs.com/cla).
+* Sign the Contributor License Agreement.
 * Push your changes to a topic branch in your fork of the repository.
 * Submit a pull request to the repository in the puppetlabs organization.
 * Update your Jira ticket to mark that you have submitted code and are ready for it to be reviewed (Status: Ready for Merge).
   * Include a link to the pull request in the ticket.
-* The Puppet SRE team looks at Pull Requests on a regular basis.
-* After feedback has been given we expect responses within two weeks. After two
-  weeks we may close the pull request if it isn't showing any activity.
+* The Puppet DIO team looks at Pull Requests on a regular basis.
+* After feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.
 
-# Additional Resources
+## Additional Resources
 
 * [Puppet Labs community guildelines](http://docs.puppetlabs.com/community/community_guidelines.html)
 * [Bug tracker (Jira)](http://tickets.puppetlabs.com)

README.md

@@ -1,4 +1,4 @@
-![VMPooler](https://raw.github.com/puppetlabs/vmpooler/master/lib/vmpooler/public/img/logo.png)
+![VMPooler](lib/vmpooler/public/img/logo.png)
 
 # VMPooler
 
@@ -8,11 +8,15 @@ VMPooler provides configurable 'pools' of instantly-available (pre-provisioned)
 
 At [Puppet, Inc.](http://puppet.com) we run acceptance tests on thousands of disposable VMs every day. VMPooler manages the life cycle of these VMs from request through deletion, with options available to pool ready instances, and provision on demand.
 
+### v2.0.0 note
+
+As of version 2.0.0, all providers other than the dummy one are now separate gems. Historically the vSphere provider was included within VMPooler itself. That code has been moved to the [puppetlabs/vmpooler-provider-vsphere](https://github.com/puppetlabs/vmpooler-provider-vsphere) repository and the `vmpooler-provider-vsphere` gem. To migrate from VMPooler 1.x to 2.0 you will need to ensure that `vmpooler-provider-vsphere` is installed along side the `vmpooler` gem. See the  [Provider API](docs/PROVIDER_API.md) docs for more information.
+
 ## Installation
 
 ### Prerequisites
 
-VMPooler is available as a gem. To use the gem run `gem install vmpooler` or add it to your Gemfile and install via bundler.
+VMPooler is available as a gem. To use the gem run `gem install vmpooler` or add it to your Gemfile and install via bundler. You will also need to install any needed providers in the same manner.
 
 ### Dependencies
 
@@ -22,11 +26,13 @@ VMPooler requires a [Redis](http://redis.io/) server. This is the data store use
 
 Configuration for VMPooler may be provided via environment variables, or a configuration file.
 
-**Note on JRuby 9.2.11.x:** We have found when running VMPooler on JRuby 9.2.11.x we occasionally encounter a stack overflow error that causes the pool\_manager application component to fail and stop doing work. To address this issue on JRuby 9.2.11.x we recommend setting the JRuby option 'invokedynamic.yield=false'. To set this with JRuby 9.2.11.1 you can specify the environment variable 'JRUBY\_OPTS' with the value '-Xinvokedynamic.yield=false'.
+#### Note on JRuby 9.2.11.x
+
+We have found when running VMPooler on JRuby 9.2.11.x we occasionally encounter a stack overflow error that causes the pool\_manager application component to fail and stop doing work. To address this issue on JRuby 9.2.11.x we recommend setting the JRuby option `invokedynamic.yield=false`. To set this with JRuby 9.2.11.1 you can specify the environment variable `JRUBY_OPTS` with the value `-Xinvokedynamic.yield=false`.
 
 The provided configuration defaults are reasonable for  small VMPooler instances with a few pools. If you plan to run a large VMPooler instance it is important to consider configuration values appropriate for the instance of your size in order to avoid starving the provider, or Redis, of connections.
 
-As of VMPooler 0.13.x Redis uses a connection pool to improve efficiency and ensure thread safe usage. At Puppet, we run an instance with about 100 pools at any given time. We have to provide it with 200 Redis connections to the Redis connection pool, and a timeout for connections of 40 seconds, to avoid timeouts. Because metrics are generated for connection available and waited your metrics provider will need to be able to cope with this volume. Prometheus or StatsD is recommended to ensure metrics get delivered reliably.
+VMPooler uses a connection pool for Redis to improve efficiency and ensure thread safe usage. At Puppet, we run an instance with about 100 pools at any given time. We have to provide it with 200 Redis connections to the Redis connection pool, and a timeout for connections of 40 seconds, to avoid timeouts. Because metrics are generated for connection available and waited, your metrics provider will need to be able to cope with this volume. Prometheus or StatsD is recommended to ensure metrics get delivered reliably.
 
 Please see this [configuration](docs/configuration.md) document for more details about configuring VMPooler via environment variables.
 
@@ -113,21 +119,23 @@ A dashboard is provided to offer real-time statistics and historical graphs.  It
 
 [Graphite](http://graphite.wikidot.com/) is required for historical data retrieval.  See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), for details.
 
-## Command-line Utility
+## Related tools and resources
+
+### Command-line Utility
 
-- [vmfloaty](https://github.com/briancain/vmfloaty) is a ruby based CLI tool and scripting library written in ruby.
+- [vmfloaty](https://github.com/puppetlabs/vmfloaty) is a ruby based CLI tool and scripting library. We consider it the primary way for users to interact with VMPooler.
 
-## Vagrant plugin
+### Vagrant plugin
 
-- [vagrant-vmpooler](https://github.com/briancain/vagrant-vmpooler) Use Vagrant to create and manage your VMPooler instances.
+- [vagrant-vmpooler](https://github.com/briancain/vagrant-vmpooler): Use Vagrant to create and manage your VMPooler instances.
 
 ## Development and further documentation
 
 For more information about setting up a development instance of VMPooler or other subjects, see the [docs/](docs) directory.
 
-## Build status
+### Build status
 
-[![Build Status](https://travis-ci.org/puppetlabs/vmpooler.png?branch=master)](https://travis-ci.org/puppetlabs/vmpooler)
+[![Testing](https://github.com/puppetlabs/vmpooler/actions/workflows/testing.yml/badge.svg)](https://github.com/puppetlabs/vmpooler/actions/workflows/testing.yml)
 
 ## License
 

docs/PROVIDER_API.md

@@ -0,0 +1,100 @@
+# Provider API
+
+Providers facilitate VMPooler interacting with some other system that can create virtual machines. A single VMPooler instance can utilize one or more providers and can have multiple instances of the same provider. An example of having multiple instances of the same provider is when you need to interact with multiple vCenters from the same VMPooler instance.
+
+## Known Providers
+
+- `vmpooler-provider-vsphere` provides the ability to use VMware as a source of VMs. Its code can be found in the [puppetlabs/vmpooler-provider-vsphere](https://github.com/puppetlabs/vmpooler-provider-vsphere) repository.
+
+Know of others? Please submit a pull request to update this list or reach out to us on the Puppet community Slack.
+
+Want to create a new one? See below!
+
+## Create a new provider gem from scratch
+
+### Requirements
+
+1. the provider code will need to be in lib/vmpooler/providers directory of your gem regardless of your gem name
+2. the main provider code file should be named the same at the name of the provider. For example, the `vpshere` provider's main file is `lib/vmpooler/providers/vsphere.rb`.
+3. The gem must be installed on the same machine as VMPooler
+4. The provider name must be referenced in the VMPooler config file in order for it to be loaded.
+5. Your gem name and repository name should be `vmpooler-provider-<provider name>` so the community can easily search provider plugins.
+
+The resulting directory structure should resemble this:
+
+```bash
+lib/
+├── vmpooler/
+│   └── providers/
+│       └── <provider name>.rb
+└── vmpooler-provider-<provider name>/
+    └── version.rb
+```
+
+### 1. Use bundler to create the provider scaffolding
+
+```bash
+bundler gem --test=rspec --no-exe --no-ext vmpooler-provider-spoof
+cd vmpooler-providers-spoof/
+mkdir -p ./lib/vmpooler/providers
+touch ./lib/vmpooler/providers/spoof.rb
+mkdir ./lib/vmpooler-providers-spoof
+touch ./lib/vmpooler-providers-spoof/version.rb
+```
+
+There may be some boilerplate files generated, just delete those.
+
+### 2. Create the main provider file
+
+Ensure the main provider file uses the following code.
+
+```ruby
+# lib/vmpooler/providers/spoof.rb
+require 'yaml'
+require 'vmpooler/providers/base'
+
+module Vmpooler
+  class PoolManager
+    class Provider
+      class Spoof < Vmpooler::PoolManager::Provider::Base
+        # At this time it is not documented which methods should be implemented
+        # have a look at the https://github.com/puppetlabs/vmpooler-provider-vsphere
+        #for an example
+      end
+    end
+  end
+end
+```
+
+### 3. Create the version file
+
+Ensure you have a version file similar this:
+
+```ruby
+# frozen_string_literal: true
+# lib/vmpooler-provider-vsphere/version.rb 
+
+module VmpoolerProviderSpoof
+  VERSION = '1.0.0'
+end
+```
+
+### 4. Fill out your gemspec
+
+Ensure you fill out your gemspec file to your specifications.  If you need a dependency, please make sure you require it.
+
+`spec.add_dependency "foo", "~> 1.15"`.
+
+At a minimum you may want to add the `vmpooler` gem as a dev dependency so you can use it during testing.
+
+`spec.add_dev_dependency "vmpooler", "~> 2.0"`
+
+Also make sure this dependency can be loaded by JRuby.  If the dependency cannot be used by JRuby don't use it.
+
+### 5. Create some tests
+
+Your provider code should be tested before releasing. Copy and refactor some tests from the `vmpooler` gem under `spec/unit/providers/dummy_spec.rb`.
+
+### 6. Publish
+
+Think your provider gem is good enough for others?  Publish it and tell us on Slack or update this doc with a link to your gem.

lib/vmpooler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vmpooler
-  VERSION = '1.3.0'
+  VERSION = '2.0.0'
 end