Skip to content

How to release extensions

Jump to bottom
Alberto Vena edited this page May 8, 2023 · 11 revisions

Releasing a new version

Requires permission to both push to the master/main branch and to rubygems.

  1. Ensure that the CI is green
  2. Update the version in lib/solidus_stripe/version.rb
  3. Commit the changes with the message Release vX.Y.Z
  4. Run bin/rake release (this will build, create the git tag, and push to both git and rubygems)
  5. Create the GitHub release and auto-generate the changelog

Migrating older extensions

  1. Ensure all the CHANGELOG.md entries are available in the repository GitHub /releases page or move the CHANGELOG content in a file called OLD_CHANGELOG.md with mv CHANGELOG.md OLD_CHANGELOG.md && touch CHANGELOG.md
  2. Once they're all there replace the contents of CHANGELOG.md with a link to the /releases page
  3. Update the .gemspec to reference the /releases page as the :changelog_uri
  4. Add require 'bundler/gem_tasks' in the extension's Rakefile

Example:

CHANGELOG.md

# Changelog

See https://github.com/solidusio/solidus_stripe/releases or [OLD_CHANGELOG.md](OLD_CHANGELOG.md) for older versions.

solidus_stripe.gemspec

  # …
  spec.metadata['changelog_uri'] = 'https://github.com/solidusio/solidus_stripe/releases'
  # …

Legacy Instructions using solidus_dev_support and the changelog generator

Automated release with solidus_dev_support

When the extension uses an up-to-date version of solidus_dev_support you can release the new version by using the following commands (remember to adjust the version number):

export new_version="1.6.0"
bundle exec gem bump -v $new_version --no-commit
bin/rake changelog # A $CHANGELOG_GITHUB_TOKEN is required, generate one via https://github.com/settings/tokens
git add CHANGELOG.md lib/**/version.rb
git commit -m "Release v$new_version"
git tag -m "Release v$new_version" v$new_version
git push --follow-tags # <remote>
bundle exec gem release

Then create a new release in GitHub (e.g., from https://github.com/solidusio/solidus_auth_devise/releases) using the newly pushed tag as a starting point, and copying the contents from the newly generated Changelog section as the description.

That's it! Happy releasing!

Manual configuration without solidus_dev_support

When the extension cannot take advantage of the facilities provided by solidus_dev_support you'll need to manually configure gem-release and github_changelog_generator.

Configure gem-release

Install and configure the gems gem-release and github-changelog-generator`.

The extension must have a properly configured .gem_release.yml file, like this one from solidus_stripe (remember to adjust the file path and the message body with the proper information):

# .gem_release.yml

bump:
  recurse: false
  file: 'lib/solidus_stripe/version.rb'
  message: Bump Solidus Stripe to %{version}
  tag: false

Now the command above should work fine: bundle exec gem bump -v 1.6.0 --no-commit.

Configure github_changelog_generator

Run bundle add github_changelog_generator to add the gem to the bundle and then replace the changelog rake task from the instructions above with:

bundle exec github_changelog_generator --user EXTENSION_ORG --project EXTENSION_NAME --token YOUR_TOKEN

Create the Release on GitHub

Create a new release from GitHub (e.g., from https://github.com/solidusio/solidus_auth_devise/releases/new) and copy the contents from the new version section in the Changelog.

Clone this wiki locally