Skip to content

How to release Solidus

Jump to bottom
Marc Busqué edited this page Jan 26, 2023 · 44 revisions

Notice about major releases

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. Some things cannot be easily deprecated. For those exceptions, we just make the change in the major, being as explicit as possible about it in the upgrade instructions.

Please, always check if there are PRs on hold with the label release:major before releasing a new major.

Notice about solidus_frontend until we remove it from the meta-gem

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

Before releasing, we also need to bump the solidus_frontend dependency on the main gemspec file.

Automatic releasing

Take a look at how to prepare a release by leveraging our automatic release process.

For minor and major releases, after that, we need to perform the required steps outside of the repository.

Manual releasing

Release a new Major version

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 👇

Release a new Minor version

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 who want to update their store since they can walk through it and understand if changes 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 file format to match the main CHANGELOG.md. ​

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

Also, update the app service version in docker-compose.yml to solidus-2.9.0.

Then, run:

git commit -am 'Bump version and update Changelog'

You can now create a PR with the changes. Once it's merged:

git pull upstream master
git tag v2.9
git checkout -b v2.9
git push --follow-tags --set-upstream upstream v2.9

We can now release the new version to RubyGems.

gem release

​

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.dev. ​ Open core/lib/spree/core/version.rb file and change from: ​

def self.solidus_version
  "2.10.0"
end

​ to: ​

def self.solidus_version
  "2.10.0.dev"
end

Also, update the version returned in the .previous_solidus_minor_version method to 2.10, and the one in docker-compose.yml to 2.10.0.dev. ​

Steps outside of the repository

Publish detailed upgrade instructions on our guides (example PR).

Solidus starter frontend

Create a new matching branch (e.g. v2.9) in solidus_starter_frontend. ​

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

​

Post on RubyFlow

For major releases, post an update on RubyFlow to be published on RubyWeekly. ​

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);

Update guides version

At this point we should create a new version with docusaurus of the guides, pointing the main one to the last version released.

Release a new Patch version

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

Then:

  • Make sure you update the Changelog. 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.

​- Run:

git checkout v2.6
gem bump -v patch --tag --push --remote upstream
gem release
  • Update the current version to the next .dev one and push the changes.

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