Skip to main content
Version: 3.0.0-beta.2

Releases

Distributions releases support

New releases target the current stable distributions release, and development should prepare for future stable distributions releases.

  • We recommend installing LibreTime on the current stable distributions.
  • Maintenance only releases will provide bug and security fixes for stable and old stable distributions.
Ubuntu 18.04Debian 10Ubuntu 20.04Debian 11
Release date2018-04-262019-07-062020-04-232021-08-14
End of life2023-042024-062025-042026-06
Versions
3.0.xmaintenancemaintenancerecommendedrecommended

Versioning schema

We follow the Semantic Versioning standards.

In a nutshell, given a version number MAJOR.MINOR.PATCH we increment the:

  1. MAJOR version when we make incompatible API changes,
  2. MINOR version when we add functionality in a backwards-compatible manner, and
  3. PATCH version when we make backwards-compatible bug fixes.

Releasing a new version

This guide walks you through the steps required to release a new version of LibreTime.

caution

This guide is still a work in progress, and doesn't cover every use cases. Depending on the version bump, some steps might be wrong. For example, in case of a patch release, the documentation requires different changes.

Before releasing a new version, make sure linter don't fail and tests are passing.

Start by cleaning the repository and make sure you don't have uncommitted changes:

git checkout main
make clean
git status

Choose the next version based the our versioning schema:

export VERSION=3.0.0-beta.0

Create a new release-$VERSION branch and release commit to prepare a release pull request:

git checkout -b "release-$VERSION"
export COMMIT_MESSAGE="chore: release $VERSION"
git commit --allow-empty --message="$COMMIT_MESSAGE"

1. Version bump

Write the new $VERSION to the VERSION file, and bump the python packages version:

bash tools/bump-python-version.sh "$VERSION"

git add .
git commit --fixup ":/$COMMIT_MESSAGE"

2. Release note

Prepare a new release note based on the docs/releases/unreleased.md file. Be sure that the filename match the releases notes naming conventions:

ls -l docs/releases/
cp docs/releases/unreleased.md docs/releases/$VERSION.md

The release note file must be updated with:

  • the version and date of this release,
  • an auto generated features and bug fixes changelog,
  • instructions for upgrading,
  • deprecation notices,
  • remove empty sections.

Reset and clean the docs/releases/unreleased.md file for a future version.

Update the Github release creation job to use the new release note file in .github/workflows/release.yml.

Commit the release note changes:

git add .
git commit --fixup ":/$COMMIT_MESSAGE"

3. Website and docs

Update the version in the website files, the files that need changing are:

  • website/vars.js
  • website/versions.json

Replace the old versioned docs with the current docs:

mv website/versioned_sidebars/version-*-sidebars.json website/versioned_sidebars/version-$VERSION-sidebars.json

rm -R website/versioned_docs/version-*
cp -R docs website/versioned_docs/version-$VERSION

Commit the website and docs changes:

git add .
git commit --fixup ":/$COMMIT_MESSAGE"

4. Create a new pull request

Squash the changes and open a pull request for others to review:

git rebase --autosquash --interactive main

Merge the pull request when it's reviewed and ready.

5. Create and push a tag

Pull the merged release commit:

git checkout main
git pull upstream main

Make sure HEAD is the previously merged release commit and tag it with the new version:

git show --quiet

git tag -a -m "$VERSION" "$VERSION"

Generate the changelog for the newly tagged version:

make changelog

git add .
git commit -m "chore: generate changelog for $VERSION"

Push the tag upstream to finalize the release process:

git push upstream main --follow-tags