dpl 1.9.6.travis.2785.5 → 1.9.6.travis.2786.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d09726f4556fc801d3934ca94a7bdedc0c7da8343b6f5a878fabfa4aac2bb582
-  data.tar.gz: 91810e6ffe2ad4a9f71cf693c8d70cccc73e94e53e58375580bee66ba86a96a9
+  metadata.gz: 2aeed418eee48c5a1f70a183f440c3ed80b9a662a964c95ec10f71174b88ce32
+  data.tar.gz: ee5e06a0298a164e29dd9f1b10574d2a54c68c8276d7f136e4646fde8a9ec9a3
 SHA512:
-  metadata.gz: 1485d09c82e9cb506c28ff829d60013ddeb9da5093142af95f6de62073a94c48b495dc4b0bdd13657075e13a2f7f865a187ef559be3d786649ad5ffb57114852
-  data.tar.gz: 46528d9bd1e4fa3c09f87ae37873bec88c82151d21ac2f251197c6ef5db77c4ad5efee078d65a0c81c2f8a5e5f7eb7666b9c016cd9e94550a9d0897a20e5283d
+  metadata.gz: 62327c030d2b5d097b5884489a397b7a7ab3ecf321ef156c4cc30120bd7098febb348f380401d3b102cafc30ba08cc8e4a3309fab8028c721ac554383f3d8510
+  data.tar.gz: 9646f491985263caeb816b65bca8258e9a71d98fbd07fee4c0508588dcc5c3b8a9bafc22ce6dfeced760bf498a79a0d59f29692dd785ddbb8c5fe5c6d2570484

data/.github/CONTRIBUTING.md

@@ -1,3 +1,140 @@
+# Writing a new deployment provider
+
+So you want to add a new deployment provider,
+fix a bug, or add a new feature to an
+existing provider.
+
+That's great.
+
+This document explains what you need to know in order
+to accomplish the goal.
+
+`dpl` is written in Ruby, and we assume that you have
+a good understanding of how it works.
+
+## General structure of the `dpl` code base
+
+### `lib/dpl/provider`
+
+Each provider code is a subclass of `DPL::Provider`,
+and it lives under `lib/dpl/provider`.
+
+```
+lib
+└── dpl
+    ├── cli.rb
+    ├── error.rb
+    ├── provider
+    │   ├── anynines.rb
+    │   ├── atlas.rb
+    │   ├── azure_webapps.rb
+    │   ├── bintray.rb
+    │   ├── bitballoon.rb
+    │   ├── ⋮
+ ```
+
+`dpl` script will receive the provider name via `--provider`
+command-line option; e.g.,
+
+    dpl --provider=script …
+
+and attempts to load it at run time.
+
+In order to make `dpl` be aware of a provider code, put the provider
+code in `lib/dpl/provider` and add a key-value pair to the `DPL::Provider::GEM_NAME_OF`
+hash in `lib/dpl/provider.rb`.
+
+For example:
+
+```ruby
+module DPL
+  class Provider
+    GEM_NAME_OF = {
+      'NewProvider' => 'new_provider',
+    }
+  end
+end
+```
+
+There is no standard for how the key and value are defined, but
+we generally recommend adhering to the snake-case naming;
+e.g., for the `CloudFoundry` class, the file (and the gem name) is
+`cloud_foundry`.
+(Please note that some existing provider codes violate this guideline.)
+
+#### Basic structure of the provider code
+
+When `dpl` loads the provider code, first it sets up dependencies
+(install `apt` packages, `npm` modules, etc.).
+
+Then the following methods on the provider code are invoked:
+
+1. `#check_auth`: sets up (and ideally verifies) user credentials
+1. `#check_app`: verify that the application is valid
+1. `#push_app`: deploy the code
+
+If you are trying to implement support for a new provider and this basic
+flow does not suit your needs, be sure to seek help/advice.
+
+### `spec/provider`
+
+`dpl` uses [RSpec](https://github.com/rspec) for tests.
+The specs reside in `spec/provider`, and each provider has the corresponding
+`*_spec.rb` file to hold specs.
+
+## Testing new code locally
+
+To test it locally, first you need to write a corresponding `dpl-*.gemspec` file.
+You can write this file from scratch, or use the `gemspec_for` helper
+method, found in `gemspec_helper.rb`.
+We recommend the helper to ensure consistency.
+The important thing is that your new gem has a good runtime dependency, most
+notably on `dpl`.
+
+Once you have `dpl-*.gemspec`, you are ready to run specs. To do this,
+call `spec-*` Rake task.
+
+> This task (and others) are dynamically inferred from the presence of `dpl-*.gemspec`,
+> so there is no need for you to touch `Rakefile`.
+
+This Rake task builds and installs `dpl` and the provider gem from the local source,
+installs dependencies and runs the specs in `spec/provider/*_spec.rb`.
+For example, to run specs on the `s3` provider:
+
+    $ bundle install
+    $ rake spec-s3
+
+If you have other versions of `dpl` and `dpl-*` gems before running the Rake task,
+they may interfere with your tests.
+
+If you suspect this interference, be sure to uninstall them by
+
+    $ gem uninstall -aIx dpl dpl-* # for appropriate provider(s)
+
+or
+
+    $ rake clean
+
+to completely clean up the working directory.
+
+### Testing a portion of specs
+
+The `spec-*` Rake tasks take an optional argument, which is passed on
+to `rspec` to indicate which lines to execute.
+
+For example:
+
+    $ rake spec-s3["55"]
+
+### Avoid making actual network calls
+
+Deployment code often interact with external services to do the job.
+It is tempting to make calls to external servers during the specs,
+but resist this temptation.
+Instead, mock the network calls and write specs that deal with different results.
+Assuming that the external resources are stable in their behavior,
+this will make the specs less susceptible to network issues.
+
 # Testing `dpl` in the context of Travis CI builds
 
 It is possible to test new deployment provider or new functionality

data/Rakefile

@@ -164,12 +164,13 @@ providers.each do |provider|
   end
 
   desc %Q(Run dpl-#{provider} specs)
-  task "spec-#{provider}" => [Rake::FileTask[dpl_bin], "Gemfile-#{provider}"] do
+  task "spec-#{provider}", [:lines] => [Rake::FileTask[dpl_bin], "Gemfile-#{provider}"] do |_t, args|
+    tail = args.lines ? ":#{args.lines}" : ""
     sh "rm -f $HOME/.npmrc"
     logger.info green("Running `bundle install` for #{provider}")
     sh 'bash', '-cl', "bundle install --gemfile=Gemfile-#{provider} --path=vendor/cache/dpl-#{provider} --retry=3 --binstubs=stubs"
     logger.info green("Running specs for #{provider}")
-    sh "env BUNDLE_GEMFILE=Gemfile-#{provider} ./stubs/rspec spec/provider/#{provider}_spec.rb"
+    sh "env BUNDLE_GEMFILE=Gemfile-#{provider} ./stubs/rspec spec/provider/#{provider}_spec.rb#{tail}"
   end
 
   desc "Build dpl-#{provider} gem"

data/lib/dpl/version.rb

@@ -1,3 +1,3 @@
 module DPL
-  VERSION = '1.9.6.travis.2785.5'
+  VERSION = '1.9.6.travis.2786.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dpl
 version: !ruby/object:Gem::Version
-  version: 1.9.6.travis.2785.5
+  version: 1.9.6.travis.2786.5
 platform: ruby
 authors:
 - Konstantin Haase