[Legacy] manual Solidus release instructions - solidusio/solidus GitHub Wiki

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 checkout -b v2.9

# Point the Solidus Installer to the right Starter Frontend version (as done in [#4898](https://github.com/solidusio/solidus/pull/4898)).
# and create a commit 

git tag 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. v3.3) in solidus_starter_frontend.
In the new Solidus Starter Frontend branch (e.g. v3.3), change the default solidus target branch in the CircleCI Config to point to the newly created branch.
Change Latest Version Nightly build Scheduled Pipeline's trigger to point to the newly created branch (e.g. v3.3).

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

Create a blog post for the solidus website (link to the upgrade instructions on our guides).
Create an update on https://opencollective.com/solidus.
Post a Tweet on our SolidusIO account.
Create a GitHub Discussion for the new Minor release in the Announcements category (eg. https://github.com/solidusio/solidus/discussions/4161), and add a link to the upgrade instructions on our guides.
Notify on Slack in the #general channel.
Add the new version to the list on the repository wiki.

Post on RubyFlow

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:

Release the API version corresponding to the version just released (2.9 in the example above);
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