Upgrade procedure

Upgrade the theme as a deliberate website change. Avoid changing the theme version as part of an unrelated content update, so any regression is easier to identify and reverse.

1. Identify the current and target versions

Find the current version in the website’s _config.yml or Gemfile, then select a target version from the releases page.

Read the release notes for the target version and every intermediate version. Major releases can contain breaking changes, but release notes for minor and patch versions must be checked as well.

Resolve all documented breaking changes and deprecations before deploying the upgrade.

2. Prepare the upgrade

1. Create a dedicated branch for the upgrade.
2. Record any local theme overrides, particularly files in _includes and _layouts. See Safe customization and overrides.
3. Make sure the website builds successfully before changing anything. This provides a known-good baseline.
4. Open the Gemfile from the target release tag. For example: Gemfile for version 6.1.0.

3. Update the dependencies and version pin

Replace or merge the website’s Gemfile with the one from the target release. Preserve gems that are specific to the website, but use the released versions for the theme’s dependencies.

Then update the exact theme pin. For a remote theme:

remote_theme: ELIXIR-Belgium/elixir-toolkit-theme@6.1.0

For a Ruby gem installation:

gem "elixir-toolkit-theme", "6.1.0"

Use the same version in the release links and the theme pin. Install the updated dependencies and rebuild the lock file where the website uses one:

bundle install
bundle exec jekyll build

Commit the updated Gemfile and, when tracked by the website, Gemfile.lock together with the version-pin change.