released 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 16ad85ccdafa69e73909d4f175e292aea0b13fd3
+  data.tar.gz: 768b7e7e8bc22e4e0d6e406e0b89df6573ea2046
+SHA512:
+  metadata.gz: 15ddba448b7ba2e02991a4e2721e35032074bbe648d527e48da881745e62f1f1809b2dfa1f95f2b756d2dde3c1b7c315af88fb5bd96859e97b606f17e2f8637a
+  data.tar.gz: f4b2de9c067cc3d0a2ff08522a2c95967d50b4905a55d9efa2ec1d091085c7c121f9d070a8df765b27af71f553d12e0c8527680981f4f0922cae2be9c1210607

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :devel do
+  gem 'fuubar'
+  gem 'geminabox'
+  gem 'json', '~> 2.0'
+  gem 'rake'
+  gem 'rspec-its'
+  gem 'rspec-mocks'
+  gem 'rspec'
+  gem 'rubocop'
+  gem 'vcr'
+  gem 'webmock'
+end

data/Gemfile.lock

@@ -0,0 +1,130 @@
+PATH
+  remote: .
+  specs:
+    released (0.0.1)
+      ddplugin (~> 1.0)
+      gems
+      git
+      nanoc (~> 4.4)
+      netrc
+      octokit
+      twitter
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.5.0)
+      public_suffix (~> 2.0, >= 2.0.2)
+    ast (2.3.0)
+    builder (3.2.2)
+    colored (1.2)
+    concurrent-ruby (1.0.2)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    cri (2.7.0)
+      colored (~> 1.2)
+    ddplugin (1.0.0)
+    diff-lcs (1.2.5)
+    faraday (0.10.0)
+      multipart-post (>= 1.2, < 3)
+    fuubar (2.2.0)
+      rspec-core (~> 3.0)
+      ruby-progressbar (~> 1.4)
+    geminabox (0.13.4)
+      builder
+      faraday
+      httpclient (>= 2.2.7)
+      nesty
+      sinatra (>= 1.2.7)
+    gems (0.8.3)
+    git (1.3.0)
+    hamster (3.0.0)
+      concurrent-ruby (~> 1.0)
+    hashdiff (0.3.1)
+    httpclient (2.8.2.4)
+    json (2.0.2)
+    multi_json (1.12.1)
+    multipart-post (2.0.0)
+    nanoc (4.4.2)
+      cri (~> 2.3)
+      hamster (~> 3.0)
+      parallel (~> 1.9)
+      ref (~> 2.0)
+    nesty (1.0.2)
+    netrc (0.11.0)
+    octokit (4.6.2)
+      sawyer (~> 0.8.0, >= 0.5.3)
+    parallel (1.10.0)
+    parser (2.3.2.0)
+      ast (~> 2.2)
+    powerpack (0.1.1)
+    public_suffix (2.0.4)
+    rack (1.6.5)
+    rack-protection (1.5.3)
+      rack
+    rainbow (2.1.0)
+    rake (11.3.0)
+    ref (2.0.0)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-its (1.2.0)
+      rspec-core (>= 3.0.0)
+      rspec-expectations (>= 3.0.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    rubocop (0.45.0)
+      parser (>= 2.3.1.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.8.1)
+    safe_yaml (1.0.4)
+    sawyer (0.8.1)
+      addressable (>= 2.3.5, < 2.6)
+      faraday (~> 0.8, < 1.0)
+    simple_oauth (0.3.1)
+    sinatra (1.4.7)
+      rack (~> 1.5)
+      rack-protection (~> 1.4)
+      tilt (>= 1.3, < 3)
+    tilt (2.0.5)
+    twitter (4.4.2)
+      faraday (~> 0.8)
+      multi_json (~> 1.3)
+      simple_oauth (~> 0.2)
+    unicode-display_width (1.1.1)
+    vcr (3.0.3)
+    webmock (2.1.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.7.10, < 2.0)
+  fuubar
+  geminabox
+  json (~> 2.0)
+  rake
+  released!
+  rspec
+  rspec-its
+  rspec-mocks
+  rubocop
+  vcr
+  webmock
+
+BUNDLED WITH
+   1.13.6

data/README.md

@@ -0,0 +1,163 @@
+# Released
+
+Released is a release pipeline tool. It is a possible implementation of [Nanoc RFC 8](https://github.com/nanoc/rfcs/pull/8).
+
+## Status
+
+_Released_ is experimental. It lacks features and is not stable. To track development, take a look at the [GitHub projects for Released](https://github.com/ddfreyne/released/projects).
+
+## Example
+
+Example pipeline:
+
+```yaml
+goals:
+  - shell:
+      command: bundle exec rake spec
+  - shell:
+      command: bundle exec rake rubocop
+  - gem_built:
+      name: released
+      version: env!VERSION
+  - gem_pushed:
+      name: released
+      version: env!VERSION
+      authorization: |
+        -----BEGIN PGP MESSAGE-----
+        Comment: GPGTools - http://gpgtools.org
+
+        hQIMA2z0x64EwZScAQ/9E4WVht6M/KHgJ0JwGUn77/s7zexsHtc6jUhd0PGHJtTp
+        KI/0pnFuKketcoZ2MVGhoKO4zMj7oUgcMk9ajKYe+CtxntWoCVqSKFtuAPD7Sa59
+        vcDLMnznNHpF3X6lRoCaRZ9uJYKaxR+HkrKjs8IquX2fr1rmTUy2POQvqZiz8kur
+        uYJNT2rV83dVxnnf5Xxi+39XGpHznDYC7Jz0cETTjj69xq8HqLaXG2DMaYGfZQMX
+        laL/vABwy63jzpDyp3IUNYEhol9GNJT02kvZLf851LtG7WUif5mH/Yh7jYbDMMbE
+        L0bwZ6rwF483QLnrcBQmjVVokRZmgwVZ2aj4FrE9rPPcRP5En4xqnyAoNECqJEIw
+        a95f92xOoKhuANo5pFWLkV4sOw5wbY35yY3+URAaXc0xSsfpMi7zDkcMGBI0heZn
+        pzFb9rGBOA0k+nLwAS8cIEqVWPmUMUkKaKR2vnJdqMS3we9q8wEwaDY6LyrXZOv9
+        4CgqmGAJAGlODzEzJ3HiW3eP24/8A/s9dpA665/gL497Mt+y2M998hZg6KOVHCVV
+        j3JF1h+hY8f/aE/Z1A8rHwh2fSrbBkoJlG+YqqFgstcgVeHPToI+Cqnv4z9MZLxR
+        9USzTsS5aIagiNfKIuugaieGpwphIwy5P3GNRSFpew3yldm47rPAqJi9kgscHrDS
+        WwHkjnLwffytKqAeUyQjXdZMvWtd3KN/bdc4n/mSeu+C7MdQzP9SJI9psTlFkpFk
+        4kQZyb0WGIdRH5Rs3KFQ2UaNl+feNi18QFz6vLKamUGuX58OwkvX5TzvnFQ=
+        =RMIv
+        -----END PGP MESSAGE-----
+```
+
+Example output:
+
+```
+% released nanoc.yaml
+```
+
+```
+*** Assessing goals…
+
+gem pushed (released)… ok
+
+*** Achieving goals…
+
+shell (bundle exec rake spec)… ok (newly achieved)
+shell (bundle exec rake rubocop)… ok (newly achieved)
+gem built (released)… ok (newly achieved)
+gem pushed (released)… ok (already achieved)
+
+Finished! :)
+```
+
+## Philosophy
+
+_Released_’s philosophy is threefold:
+
+* **idempotent**: The tool should be able to be run multiple times for the same version, and steps that have already executed should not cause additional effects. For example, if publishing the gem succeeds, but pushing to GitHub fails, the tool should be able to be run again and pushing to GitHub should succeed without failing on the gem push step.
+
+* **safe**: If an erroneous condition arises, and continuing could lead to a broken release, the tool should abort. For example, if any of the pre-release verifications fail, the release should not continue.
+
+* **resilient**: If a release cannot be made properly due to a dependent service being unavailable, the tool should be able to retry the step, or skip it if the step is deemed to be optional.
+
+## Concepts
+
+_Released_ has the following concepts:
+
+* pipeline
+* goal
+
+The sections below elaborate on these concepts.
+
+### Goal
+
+A goal expresses an individual desired end state. For example:
+
+* `tests_passing`: the tests are passing
+* `style_checked`: the style checks are passing
+* `pkg_built`: the Debian package is built
+* `pkg_published`: the Debian package is published
+* `tweet_sent`: the tweet about the release is sent
+
+Goals are described in a passive voice (e.g. `gem_built`; “the gem has been built”) rather than in the imperative mood (e.g. `build_gem`; “build the gem”). This approach allows expressing what the end state is, rather than how to achieve it. This way, the release process is idempotent: re-running the release process when it has already succeeded before will leave everything as-is, as all goals have already been achieved.
+
+When attempting to achieve a goal, _Released_ will first _assess_ the goal in order to determine whether the goal can realistically be obtained given the current circumstances. For example, when the goal is to have a Debian package published, the assessment would fail if no working credentials are available.
+
+_Released_ will take the necessary steps to achieve a given goal, but no more than that. If a goal is already achieved, no steps will be taken. It is therefore quite acceptable try to achieve a goal multiple times.
+
+TODO: figure out difference between temporary/retriable failures (GitHub is down) and permanent/non-retriable ones (tests are failing)
+
+### Pipeline
+
+A pipeline is a sequence of goals. Each goal will be executed in sequence, and a goal will only be executed if no previous goals have failed.
+
+## Pipeline file
+
+Strings in `pipeline.yaml` will be replaced according the following rules:
+
+* Strings starting with `env!` will be replaced with the value of the environment variable whose name is everything after the exclamation mark. For example, `version: env!VERSION` will become `version: 0.1.2` if the `VERSION` environment variable is set to `0.1.2`.
+
+* Strings starting with `sh!` will be replaced with the output of the shell command following the exclamation mark. For example, `version: sh!echo -n 0.1.2` will become `version: 0.1.2`.
+
+* Strings starting with `-----BEGIN PGP MESSAGE-----` will be replaced with their content passed through `gpg --decrypt`.
+
+## Defining custom goal types
+
+To define a custom goal type, subclass `Released::Goal` and give it an identifier:
+
+```ruby
+class FileExists < Released::Goal
+  identifier :file_exists
+
+  def initialize(config)
+    @filename = config.fetch('filename')
+    @contents = config.fetch('contents')
+  end
+
+  def try_achieve
+    File.write(@filename, @contents)
+  end
+
+  def achieved?
+    File.file?(@filename) && File.read(@filename) == @contents
+  end
+
+  def failure_reason
+    if !File.file?(@filename)
+      "file `#{@filename}` does not exist"
+    elsif File.read(@filename) != @contents
+      "file `#{@filename}` does not have the expected contents"
+    else
+      "unknown reason"
+    end
+  end
+end
+```
+
+Define the following methods:
+
+* `initialize(config)` — Initialize the goal with the given configuration. The configuration is a hash whose keys are strings (not symbols).
+
+* `try_achieve` — Perform any steps necessary to achieve the goal.
+
+* `achieved?` — Return `true` if the goal has been achieved, `false` otherwise. This method should not mutate state.
+
+* `failure_reason` — Return a string containing the reason why the goal was not achieved. This method should not mutate state.
+
+You might want to implement the following methods as well:
+
+* `effectful?` — Return `true` if achieving the goal is effectful, i.e. is expected to cause a state change, `false` otherwise. For example, a `gem_built` goal is effectful, while a `test_passed` goal is not. The default is `true`.

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rubocop/rake_task'
+require 'rspec/core/rake_task'
+
+RuboCop::RakeTask.new(:rubocop) do |task|
+  task.options  = %w(--display-cop-names --format simple)
+  task.patterns = ['bin/*', 'lib/**/*.rb', 'spec/**/*.rb']
+end
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = false
+end
+
+task default: [:spec, :rubocop]

data/lib/released/goal.rb

@@ -0,0 +1,38 @@
+module Released
+  class Goal
+    extend DDPlugin::Plugin
+
+    # @abstract
+    def initialize(_config = {})
+      raise NotImplementedError
+    end
+
+    def to_s
+      self.class.identifier.to_s
+    end
+
+    def assessable?
+      respond_to?(:assess)
+    end
+
+    # @abstract
+    def effectful?
+      true
+    end
+
+    # @abstract
+    def try_achieve
+      raise NotImplementedError
+    end
+
+    # @abstract
+    def achieved?
+      raise NotImplementedError
+    end
+
+    # @abstract
+    def failure_reason
+      raise NotImplementedError
+    end
+  end
+end

data/lib/released/goals/file_exists.rb

@@ -0,0 +1,30 @@
+module Released
+  module Goals
+    class FileExists < Released::Goal
+      identifier :file_exists
+
+      def initialize(config)
+        @filename = config.fetch('filename')
+        @contents = config.fetch('contents')
+      end
+
+      def try_achieve
+        File.write(@filename, @contents)
+      end
+
+      def achieved?
+        File.file?(@filename) && File.read(@filename) == @contents
+      end
+
+      def failure_reason
+        if !File.file?(@filename)
+          "file `#{@filename}` does not exist"
+        elsif File.read(@filename) != @contents
+          "file `#{@filename}` does not have the expected contents"
+        else
+          'unknown reason'
+        end
+      end
+    end
+  end
+end

data/lib/released/goals/gem_built.rb

@@ -0,0 +1,46 @@
+module Released
+  module Goals
+    class GemBuilt < Released::Goal
+      identifier :gem_built
+
+      def initialize(config = {})
+        @name = config.fetch('name')
+        @version = config.fetch('version')
+      end
+
+      def to_s
+        "gem built (#{@name})"
+      end
+
+      def try_achieve
+        # TODO: remove
+        Dir['*.gem'].each { |f| FileUtils.rm_f(f) }
+
+        stdout = ''
+        stderr = ''
+        piper = Nanoc::Extra::Piper.new(stdout: stdout, stderr: stderr)
+
+        begin
+          gemspec_file_path = "#{@name}.gemspec"
+          piper.run(['gem', 'build', gemspec_file_path], [])
+        rescue
+          raise "Failed to build gem: #{stderr}"
+        end
+      end
+
+      def achieved?
+        File.file?(expected_name)
+      end
+
+      def failure_reason
+        "expected the file #{expected_name} to exist"
+      end
+
+      private
+
+      def expected_name
+        @_expected_name ||= @name + '-' + @version + '.gem'
+      end
+    end
+  end
+end

data/lib/released/goals/gem_pushed.rb

@@ -0,0 +1,60 @@
+require 'gems'
+
+module Released
+  module Goals
+    class GemPushed < Released::Goal
+      identifier :gem_pushed
+
+      BASE_URL = 'https://rubygems.org'.freeze
+
+      def initialize(config = {})
+        @name = config.fetch('name')
+        @version = config.fetch('version')
+
+        @rubygems_repo = Gems::Client.new(
+          key: config.fetch('authorization'),
+          host: config.fetch('rubygems_base_url', BASE_URL),
+        )
+      end
+
+      def to_s
+        "gem pushed (#{@name})"
+      end
+
+      def assess
+        gems = @rubygems_repo.gems
+        if gems =~ /Access Denied/
+          raise 'Authorization failed'
+        end
+
+        unless gems.any? { |g| g['name'] == @name }
+          raise 'List of owned gems does not include request gem'
+        end
+      end
+
+      def try_achieve
+        filename = @name + '-' + @version + '.gem'
+        unless File.file?(filename)
+          raise "no such gem file: #{filename}"
+        end
+
+        File.open(filename, 'r') do |io|
+          @rubygems_repo.push(io)
+        end
+      end
+
+      def achieved?
+        gems = @rubygems_repo.gems
+        if gems =~ /Access Denied/
+          raise 'Authorization failed'
+        end
+
+        gems.any? { |g| g['name'] == @name && g['version'] == @version }
+      end
+
+      def failure_reason
+        "expected list of gems to contain “#{@name}”, version #{@version}"
+      end
+    end
+  end
+end

data/lib/released/goals/git_ref_pushed.rb

@@ -0,0 +1,39 @@
+require 'git'
+
+module Released
+  module Goals
+    class GitRefPushed < Released::Goal
+      identifier :git_ref_pushed
+
+      def initialize(config)
+        @working_dir = config.fetch('working_dir')
+        @remote = config.fetch('remote')
+        @branch = config.fetch('branch')
+      end
+
+      def try_achieve
+        g.push(@remote, @branch)
+      end
+
+      def achieved?
+        there_branch = g.branches["#{@remote}/#{@branch}"]
+        return false if there_branch.nil?
+        there = there_branch.gcommit.sha
+
+        here = g.object('HEAD').sha
+
+        here == there
+      end
+
+      def failure_reason
+        "HEAD does not exist on #{@remote}/#{@branch}"
+      end
+
+      private
+
+      def g
+        @_g ||= Git.open(@working_dir)
+      end
+    end
+  end
+end

data/lib/released/goals/github_release_exists.rb

@@ -0,0 +1,33 @@
+require 'octokit'
+
+module Released
+  module Goals
+    class GitHubReleaseExists < Released::Goal
+      identifier :github_release_exists
+
+      def initialize(config)
+        @repository_name = config.fetch('repository_name') # e.g. nanoc/nanoc
+        @tag = config.fetch('tag')
+        @release_notes = config.fetch('release_notes')
+      end
+
+      def try_achieve
+        client = Octokit::Client.new(netrc: true)
+        client.create_release(
+          @repository_name, @tag,
+          body: @release_notes
+        )
+      end
+
+      def achieved?
+        client = Octokit::Client.new(netrc: true)
+        releases = client.releases(@repository_name)
+        releases.any? { |r| r.tag_name == @tag }
+      end
+
+      def failure_reason
+        "no release exists in repository #{@repository_name} for tag #{@tag}"
+      end
+    end
+  end
+end

data/lib/released/goals/shell.rb

@@ -0,0 +1,40 @@
+module Released
+  module Goals
+    # TODO: rename
+    class Shell < Released::Goal
+      identifier :shell
+
+      def initialize(config = {})
+        @command = config.fetch('command')
+      end
+
+      def to_s
+        "shell (#{@command})"
+      end
+
+      def effectful?
+        false
+      end
+
+      def assess
+        sleep 1
+      end
+
+      def try_achieve
+        stdout = ''
+        stderr = ''
+        piper = Nanoc::Extra::Piper.new(stdout: stdout, stderr: stderr)
+
+        begin
+          piper.run(@command, [])
+        rescue
+          raise "Failed execute command!\n\nstderr:\n#{stderr}\n\nstdout:\n#{stdout}"
+        end
+      end
+
+      def achieved?
+        false
+      end
+    end
+  end
+end

data/lib/released/goals.rb

@@ -0,0 +1,11 @@
+module Released
+  module Goals
+  end
+end
+
+require_relative 'goals/file_exists'
+require_relative 'goals/gem_built'
+require_relative 'goals/gem_pushed'
+require_relative 'goals/git_ref_pushed'
+require_relative 'goals/github_release_exists'
+require_relative 'goals/shell'