Zappifest Release process

Zappifest release process

This document explains how to release a new version of zappifest. Zappifest is a CLI tool written in Ruby, and shipped with homebrew. Homebrew relies on formulas that tell the homebrew software how to install to program locally. The formula is listed inside a tap, which homebrew uses to know if an update is available.

Releasing a new version of Zappifest means updating the zappifest formula in applicaster’s homebrew tap, which also contains the zapptool formula. In order to do so, we will first need to create a new release (tag) in the zappifest repo :

• Once all your code is merged, make sure the version X.Y.Z in lib/version.rb matches the version you want to release. Make sure you follow semantic versioning rules:
  • Bump major version X if you're breaking the API
  • Bump minor version Y if you're adding a new feature
  • Bump patch version Z if you're fixing a bug
• Go to release tab. Draft a new release, add the tag corresponding to the release version, and fill in the release name and summary.
• Once your release is published, download the source tarball. If using Safari, it will automatically try to unzip the tarball, so it is better for this step to use either Chrome or Firefox. The tarball url should be something like this https://github.com/applicaster/zappifest/archive/X.Y.Z.tar.gz
• you will need to get the sha256 checksum of the tarball. In order to do this you can run either of this commands (assuming the file is in your ~/Download folder):

# this one will copy the checksum to the clipboard, but requires the openssl lib to be installed 
$ openssl sha256 < ~/Downloads/zappifest-X.Y.Z.tar.gz | pbcopy
# or
$ shasum -a 256 ~/Download/zappifest-x.y.z.tar.gz

From this point, a new release has been created on Github. A tag was created in the zappifest repo, and a tarball containing the source code is available. This is what we will use to update the homebrew formula.

• If you don't have the applicaster homebrew tap available locally already, clone git@github.com:applicaster/homebrew-tap.git
• Create a new PR to update the tap. All changes will happen in the zappifest.rb
• update the file with the following:
  • Update the tarball url, the version number, and the tarball checksum

class Zappifest < Formula
  desc "Tool to generate Zapp plugin manifest"
  homepage "https://github.com/applicaster/zappifest"
  url "https://github.com/applicaster/zappifest/archive/x.y.z.tar.gz" # update url here
  version "x.y.z" # update version here
  sha256 "#{tarball_checksum}" # update checksum here

• if your release contains a new gem, you need to give homebrew instructions to install it. add a resource block below, like this:

resource "new_gem_name" do
  url "https://rubygems.org/new_gem_name_url.gem"
  sha256 "#{gem_checksum}"
end

• if your release contains new files, add them in the lib.install call at the bottom of the file. The path should be relative to the zappifest project root:

lib.install(
  ...,
  "lib/new_file.rb",
)

• Have your PR approved and merged

From this point, the formula is updated in the tap, and users can install the new version by running

$ brew update && brew upgrade zappifest

brew update will tell homebrew to check for the updated formula in the applicaster tap. If it finds one, it will get the new instructions for users to upgrade zappifest. The Zappifest tool has its own built-in mechanism to check for updates. As soon as the tap update PR is merged, users running zappifest will be prompted to update to the latest version automatically.

If for some reason you want to restrict Zapp to allow requests from earlier versions of zappifest, you can also create a pull request to change the minimum zappifest version required. This will require Zapp to be deployed though

All is left to do now is to announce the update in #zapp-dev-updates, pasting a link to the new release on github