Release Procedure

This document is a Core team guide, provided publicly to ensure transparancy in the release process.

Versioning

Jellyfin uses semantic versioning. All releases will have versions in the X.Y.Z format, starting from 10.0.0. Note however that the 10.Y.Z release chain represents the "cleanup" of the codebase, so it should be accepted that 10.Y.Z breaks all compatibility, at some point, with previous Emby-compatible interfaces, and may also break compatibility with previous 10.Y releases if required for later cleanup work. Our versioning will typically follow the patterns below:

X - Major breaking versions

  • Breaks compatibility with the HTTP and/or plugin APIs.

Y - Minor versions

  • Introduces new features.
  • Makes minor backwards-compatible API changes.

Z - Hotfix versions

  • Introduces critical bugfixes or otherwise changes master branch code since the last release.

General Release Philosophy

Release procedure (major/minor version releases)

  1. Announce release in the jellyfin-dev Matrix/Riot channel at least a few hours before releasing, to put a temporary freeze on merges.

  2. Ensure any required PRs are merged into both the jellyfin and jellyfin-web repositories.

  3. Create a release branch for the jellyfin and jellyfin-web repositories with the format release-X.Y.Z, where X.Y is the new minor + major version number and Z is a literal Z character, for example release-10.3.Z, based off the current master branches. These will be somewhat long-lived branches to track particular releases and deal with hotfixes to those branches should they be required.

  4. Execute the bump_version script inside the release branch in the jellyfin local repository. Commit the resulting differences as Bump version to X.Y.Z, where X.Y.Z is the full version number.

  5. Perform initial testing builds and test the resulting binaries.

    Basic testing checklist:

    1. Run through setup wizard and import small library.
    2. Test playback, navigation, and subtitles in the Web UI.
    3. Test playback, navigation, and subtitles in the various client apps.
  6. Call to jellyfin-dev for any release-critical bug found; perform bugfix pull requests against the release-X.Y.Z branch.

  7. Repeat the above two steps until no more RC bugs are found.

  8. Perform the release.

    1. Create pull requests from release branch into master in both repositories.
    2. Obtain approval from the Core team.
    3. Merge release branch PR into master in jellyfin-web.
    4. Update submodule for jellyfin-web directly in release branch. Commit the resulting differences as Update jellyfin-web submodule to X.Y.Z, where X.Y.Z is the full version number:
      cd MediaBrowser.WebDashboard/jellyfin-web
      git fetch --all
      git checkout master
      cd ../..
      git add MediaBrowser.WebDashboard/jellyfin-web
      git commit
    5. Merge release branch PR into master in jellyfin.
    6. Create the GitHub release and tag from release branch to facilitate future point releases.
    7. Build new releases packages off of release branch and upload to repositories.
    8. Announce new release in the jellyfin-announce Matrix/Riot channel and anywhere else required (e.g. Reddit, etc.).
  9. Delete any previous minor release branches, as all future hotfix work should go against the new release branch, or master directly for inclusion in the next major release.

Release procedure (Hotfix version releases)

  1. Discover a major, breaking bug in the current release which must be immediately fixed and cannot wait for the next full feature release; discuss and challenge any hotfixes (are they really needed and can't wait?) in the jellyfin-dev Matrix/Riot channel to coordinate hotfixes.

  2. Create all hotfix PRs against the current minor release branch in either the jellyfin and jellyfin-web repositories; merge when completed.

  3. Execute the bump_version script inside the release branch in the jellyfin local repository. Commit the resulting differences as Bump version to X.Y.Z, where X.Y.Z is the full version number.

  4. Perform the release.

    1. Create pull requests from release branch into master in any required repositories.
    2. Obtain approval from the Core team.
    3. IF the hotfix applies to the jellyfin-web repository, merge release branch PR into master in jellyfin-web.
    4. IF the hotfix applies to the jellyfin-web repository, update submodule for jellyfin-web directly in the jellyfin release branch. Commit the resulting differences as Update jellyfin-web submodule to X.Y.Z, where X.Y.Z is the full version number.
      cd MediaBrowser.WebDashboard/jellyfin-web
      git fetch --all
      git checkout master
      cd ../..
      git add MediaBrowser.WebDashboard/jellyfin-web
      git commit
    5. Merge release branch PR into master in jellyfin.
    6. Create the GitHub release and tag from release branch to facilitate future point releases. IF the hotfix did not affect the jellyfin-web repository, still create a new release and tag targeting the same point on the release branch to facilitate consistent versioning between the repositories; the changelog may be empty with a "new release to match main repository"-type message.
    7. Build new releases packages off of release branch and upload to repositories.
    8. Announce new release in the jellyfin-announce Matrix/Riot channel and anywhere else required (e.g. Reddit, etc.).