11.2 Release checklist

A “minor release” means an update of y in 2.x.y.

Preparing the release

  1. Prepare the release branch (release/unstable for unstable releases or stable/2.x for stable releases). It is recommended to use a separate repository for this, or at least a worktree. The checked out repository must have no changes to tracked files.
    • Pull the latest changes in the remote repository, then switch to and update the branch:
      git fetch origin
      git rebase origin/master release/unstable

      (adapt as necessary for stable/2.x)

    • Remove untracked files from the repository, especially the ‘configure’ script:
      git clean -dfx --exclude release/

      (Keep untracked files in the ‘release/’ directory, such as ‘release/binaries/downloads/’ and local test builds.)

  2. Generate the ‘configure’ script and run it:
  3. Update the translation template ‘po/lilypond.pot’:
    make po-replace
  4. Edit the news files:
    • Copy the previous announcement from ‘Documentation/en/web/news-new.itexi’ to ‘Documentation/en/web/news-old.itexi’.
    • Create a new announcement in ‘Documentation/en/web/news-new.itexi’ by adjusting the version number and the date.
    • Adjust the headlines in ‘Documentation/en/web/news-headlines.itexi’ accordingly.
  5. Adjust the version numbers:
    • Bump the \version statements in ‘ly/Wel*.ly’ to the current version that is about to be released.
    • Adjust version numbers in ‘VERSION’. In most cases, this means setting VERSION_DEVEL to the current version. Only change VERSION_STABLE if releasing a stable version.
  6. Commit the changes:
    git commit -m "po: Update template" -- po/lilypond.pot
    git commit -m "web: Update news" -- Documentation/en/web/
    git commit -m "ly: Bump Welcome versions" -- ly/Wel*.ly
    git commit -m "Bump VERSION_DEVEL" -- VERSION

Creating the source release

  1. Remove untracked files from the repository (see above):
    git clean -dfx --exclude release/
  2. Generate the ‘configure’ script and run it:
  3. Create the source tarball:
    make dist

The last step creates ‘out/lilypond-2.x.y.tar.gz’, which will be the “single source of truth” for the following steps. Put it into a directory for the final upload step.

Building the binaries and documentation

These steps can be run in any order, or in parallel.

Collect all created binaries (‘.tar.gz’ and ‘.zip’) and documentation archives (‘.tar.xz’) in the directory next to the source tarball. If possible, give them some short testing to make sure everything works as expected.

Uploading the release

During this step, the artifacts from the previous steps are uploaded to lilypond.org and GitLab for the world to see. Make sure everything is ready before proceeding.

  1. Create a personal access token at https://gitlab.com/-/profile/personal_access_tokens. This can be limited to auto-expire the next day.
  2. Upload the source tarball to lilypond.org:
    scp lilypond-2.x.y.tar.gz graham@gcp.lilypond.org:/var/www/lilypond/downloads/sources/v2.x/lilypond-2.x.y.tar.gz
  3. In the directory where you collected the binaries, run the script to upload the files to GitLab:
    /path/to/lilypond/release/upload.py --token TOKEN 2.x.y
  4. Extract the web documentation from ‘lilypond-2.x.y-webdoc.tar.xz’ and adjust the group permissions:
    chmod -R g+w lilypond-2.x.y-webdoc
  5. Synchronize the documentation to lilypond.org:
    rsync --delay-updates --delete --delete-after --progress -prtvuz lilypond-2.x.y-webdoc/ graham@gcp.lilypond.org:/var/www/lilypond/doc/v2.x/

Tagging and announcing the release

  1. In the repository that was used to create the release (check that git log has the expected commits; “Bump VERSION_DEVEL” should be the last one), tag the release:
    git tag -am "LilyPond 2.x.y" v2.x.y
  2. Push the changes and the tag:
    git push origin HEAD:release/unstable v2.x.y

    (adapt as necessary for stable/2.x)

  3. Create a file ‘description.md’ with a copy of the release announcement (may be formatted as Markdown for links).
  4. Create the release on GitLab:
    /path/to/lilypond/release/create-release.py --token TOKEN --description description.md 2.x.y

Creating a release on GitLab will automatically send an email to everbody who subscribed to release notifications.

Post unstable release

In this case, the release branch is release/unstable.

  1. Update the master branch with the latest changes:
    git fetch origin
    git rebase origin/master master
  2. Merge the release branch:
    git merge --no-ff release/unstable
  3. Bump PATCH_LEVEL in the ‘VERSION’ file and commit:
    git commit -m "Bump VERSION" -- VERSION
  4. Push the branch to GitLab:
    git push origin HEAD:release/unstable
  5. Create a merge request from release/unstable to merge the changes into master.
  6. Update the website as described in Uploading website.
  7. Update the milestones at GitLab:
    1. Make sure all merge requests and issues are added to the milestone of the released version. Fill in the due date and close it.
    2. Create a new milestone for the next release (unless no more bugfix release is planned) and set the start date.
  8. Check open merge requests and remind people to update the \version statement in conversion rules and regression tests.

After the website update appears on lilypond.org, send a release notice to lilypond-devel and lilypond-user with the same announcement text and possibly further instructions.

LilyPond — Contributor’s Guide v2.23.13 (development-branch).