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 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 "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, with the exception of the Windows (mingw) build, that needs a run of the Linux build before.

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.25.16 (development-branch).