Skip to content

How to release Solidus

Jump to bottom
Alberto Vena edited this page Nov 9, 2022 · 44 revisions

Release a new Major version

To release a new Major version we try to respect this simple principle:

The only difference between a Major version and the last Minor of the past series is the removal of deprecated code.

For example, v2.11 is identical to v3.0. The only difference is that in v3.0 we removed all of the code deprecated during the v2.x cycle.

This is not always possible. There are some things that cannot be easily deprecated. For those exceptions, we just make the change in the major being as explicit as possible about it in the CHANGELOG.

The technical steps to release a new Major version are:

  • Change the deprecation horizon to the next Major.
  • Follow all the steps of the Minor version 👇
  • Post an update on RubyFlow to be published on RubyWeekly.

Release a new Minor version

For Solidus 3.2+, please remember to bump solidus_frontend at the target version before releasing a new version of the core gems.

Let's say the latest version on master is 2.9.0.alpha and we want to release a new 2.9.0 version. ​ These are the steps required for the release to happen: ​

Make sure CHANGELOG.md is up to date

​ Our CHANGELOG is where all the major changes are listed. It's a great resource for developers that want to update their store since they can walk through it and understand if there are changes that can impact their stores. Take a look at the current CHANGELOG to better understand how to update it. ​ A fast way to generate a CHANGELOG is via github_fast_changelog. For example, the commands to create the 2.9 changelog before the release should be: ​ ​

gem install github_fast_changelog
export GITHUB_ACCESS_TOKEN=...
git rev-list v2.8...master | github_fast_changelog solidusio/solidus > CHANGELOG_2.9.md

​ Now we can adjust the format of the file to match the main CHANGELOG.md and create a PR. ​

Run the gem release command

​ We can use gem-release to automate the release here. ​ From the master branch you can run: ​

gem bump -v 2.9.0 --branch v2.9 --tag --push --remote upstream
gem release

​ The first command will take care of: ​

  • Checking out a new v2.9 branch
  • Bumping solidus version to 2.9.0 changing it at core/lib/spree/core/version.rb
  • Pushing a commit with the change to the new branch in the upstream repository
  • Creating and pushing a new git tag 2.9.0 ​ The gem release command will actually push new 2.9.0 gems to RubyGems. ​

Create a GH release

​ Now you can go on GH and create a release into: ​ https://github.com/solidusio/solidus/releases ​

Prepare master for the next version:

​

Update gemspecs version

In the master branch let's start a 2.10.0.alpha. ​ Open core/lib/spree/core/version.rb file and change from: ​

def self.solidus_version
  "2.9.0"
end

​ to: ​

def self.solidus_version
  "2.10.0.alpha"
end

Also, update the version returned in the .previous_solidus_minor_version method to 2.9. ​

Update Solidus version in the docker-compose.yml file

Just change here with the new version (eg. 2.10.0 without the .alpha part):

https://github.com/solidusio/solidus/blob/e92f4dcf458347821f8871f0b89a6aedd30076d1/docker-compose.yml#L30

Update the CHANGELOG:

​

  • update the released date for 2.9.0.
  • add a 2.10.0 (unreleased) line. ​ Take a look at this PR as an example. ​

Update the extensions builds, security page, and the example-app

​

CircleCI Extension Builds

​ Update https://github.com/solidusio/circleci-orbs-extensions for extensions that use the new CircleCI Orb. ​

Solidus Website

​ Also, in the Solidus main website repository add the new version in https://github.com/solidusio/solidus-site/blob/1a6a7386d7ca85400be31bfe38f903da84844bb2/data/versions.yml.

This will change the supported versions at: ​

Example App (for the Heroku button)

​

cd ..                               # Go up one dir relative to the solidus repo.
export UPDATE_EXAMPLE_APP_REPO=true # Enable the automatic push to GitHub.
test -d solidus-example-app && \    # If it's not the first time the app is generated
  rm -rf solidus-example-app        # we should remove it to start clean.
​
# Start the generator script that will generate the app 
# inside ./solidus-example-app and push it to GitHub.
solidus/bin/rails-application-template

​

Notify the community

​

Update API documentation

We need to start generating the API documentation for the new unreleased version in Spotlight. Go to https://next.stoplight.io/, log in or sign up and ask some other core team member for permissions.

You should now:

  1. Release the API version corresponding to the version just released (2.9 in the example above);
  2. Create a new version corresponding to the new unreleased version (2.10 in the example above);

Release a new Patch version

For Solidus 3.2+, please remember to bump solidus_frontend at the target version before releasing a new version of the core gems.

Suppose the latest 2.6.x is 2.6.0 and we want to release a new 2.6.1 version.

Then: ​

git checkout v2.6
gem bump -v patch --tag --push --remote upstream
gem release

After that, make sure you update the Changelog on master. If the fix comes from private forks on a Github security advisory, you'll have to add those entries manually, as they don't come from regular PRs. ​

Create a GitHub release

​ Now you can go on GitHub and create a release into: ​ https://github.com/solidusio/solidus/releases

Clone this wiki locally