Automate release process with CI

[mkobit]

Releases should be completely (or as much as possible) automated by a CI system.

The current release process is mostly manual. This leads to slow release cycles that are prone to error. The current process is well documented in #36.

I am surely missing some items, but here is current list of actions for a release (assuming access to the jekyll-asciidoc RubyGem and this repository):

1. Update version in lib/jekyll-asciidoc/version.rb
2. Commit and run rake release. This accomplishes a few things:
   • Creates and pushes a Git tag
   • Pushes commit up to remote
   • Publishes gem to jekyll-asciidoc RubyGem
3. Update version in lib/jekyll-asciidoc/version.rb for next release
4. Create a Github release for the tag
   • Identify relevant issues since last release
   • Tag with relevant milestone
   • Close open issues
5. Close milestone

In my opinion, I think trying to achieve a level of automated releases similar to how the spinnaker/deck would be awesome.

Related issues

• "Releases should be performed by the CI server (releases should be fully automated)" - Releases should be performed by the CI server (releases should be fully automated) asciidoctor#1565
• "publishing Jekyll 3 updates" - publishing Jekyll 3 updates #36

[mojavelinux]

👍

[mojavelinux]

Here's a helpful article on the topic of releasing in one click: http://www.yegor256.com/2014/08/26/publish-to-rubygems.html

[mojavelinux]

I have good news. @ldez has figured out how to get Travis CI to do a release (at least for apm packages). I think we can build on that work for this issue. See:

• https://github.com/ldez/travis-continuous-delivery-atom-publish
• chore: continuous delivery atom-autocomplete-asciidoc#2

[mojavelinux]

Here's the manual release process I've been following:

• Resolve all issues filed against the current milestone in the issue tracker.

• Record all changes for this release in CHANGELOG.adoc and set release date and released by:

  == X.Y.Z (YYYY-MM-DD) - @username
  

• Verify copyright year is correct in README.adoc and LICENSE.adoc, updating if necessary.

• Drop .dev suffix from version in lib/jekyll-asciidoc/version.rb

• Add revision line to README.adoc with version and date:

  vX.Y.Z, YYYY-MM-DD
  

• Create a prepare release commit using:

  $ git commit . -m 'Prepare X.Y.Z release'
  

• Push commit to GitHub:

• Verify CI build passes at https://travis-ci.org/asciidoctor/jekyll-asciidoc.

• Create an empty release commit using:

  $ git commit --allow-empty -a -m 'Release X.Y.Z'
  

• Create git tag, push commits and tags to GitHub, build gem and publish to RubyGems.org:

  $ bundle exec rake release
  

• Close milestone in the issue tracker.

• Create a new release on GitHub for this tag and copy in changes from CHANGELOG.adoc using the following template:

  Executive summary.
  
  ### Changes
  
  * ...
  
  ### Distributions
  
  * [RubyGem (jekyll-asciidoc)](https://rubygems.org/gems/jekyll-asciidoc)
  

• Bump version in lib/jekyll-asciidoc/version.rb and add .dev suffix

• Remove revision line from README.adoc.

• Start development on next release using:

  $ git commit . -m 'Begin development on next milestone [skip ci]'
  

• Push commit to GitHub:

  $ git push
  

[mojavelinux]

Travis can be configured to release a gem to RubyGems.org. See https://docs.travis-ci.com/user/deployment/rubygems/. I think I'm going to give that a try.

[mojavelinux]

Here's a script I hacked together to handle bumping the version and creating the release commits.

#!/usr/bin/bash

PUSH=false
while getopts "p" option; do
  case $option in
    p) PUSH=true ;;
  esac
done

GEM_VERSION=`bundle exec ruby -e "print (Gem::Version.new Jekyll::AsciiDoc::VERSION).release"`
sed -i "/VERSION/s/'[^']\+'/'$GEM_VERSION'/" lib/jekyll-asciidoc/version.rb
sed -i "3i v$GEM_VERSION, `date +%Y-%m-%d`" README.adoc
sed -i "/^:branch: master$/d" README.adoc
git commit -a -m "Prepare $GEM_VERSION release"
git commit --allow-empty -m "Release $GEM_VERSION"
git tag -m "Version $GEM_VERSION" v$GEM_VERSION
if [ $PUSH == true ]; then
  git push --tags
fi
sed -i "3d" README.adoc
sed -i "s/^ifdef::env-github\[\]$/&\n:branch: master/" README.adoc
GEM_VERSION=`bundle exec ruby -e "print (Gem::Version.new Jekyll::AsciiDoc::VERSION).segments.tap {|s| s[-1] += 1 }.join('.') + '.dev'"`
sed -i "/VERSION/s/'[^']\+'/'$GEM_VERSION'/" lib/jekyll-asciidoc/version.rb
git commit -m "Begin development on next version [skip ci]" .
if [ $PUSH == true ]; then
  git push
fi

I find most of the release helper gems to be too complex and error prone.

[mojavelinux]

After I pushed the tag, Travis performed the release. It went off without a hitch (except for some reason Travis failed on one of the interim builds, claiming that the commit disappeared).

Now that Travis releases the gem, what's next is to have Travis prepare and create the tag (including the version number swap). I'd like to be able to push a commit to master that triggers the release.sh script.

I'm thinking something like:

initiate release

From there, Travis runs release.sh to create the release commit and switch back to the development version after.

This is where we need to setup the SSH key because we need to allow Travis to push to the repository.

We may want to consolidate some of the commits too so that we don't end up with so many interim commits. We may even be able to amend the initial release commit so that it's only temporary. (Another idea would be to push a temporary branch or tag).

[mojavelinux]

Interesting to note that Travis CI now has build stages. This would allow the commit and deploy to happen in the same build. See https://docs.travis-ci.com/user/build-stages/deploy-rubygems/. I'm not sure if that will work for us, but it looks promising.

[mojavelinux]

This now done in GitHub Actions. The Release workflow drives a release starting from the web form.