// OPENBOX DOCS

Releasing

Cut and publish an OpenBoxGL AppImage release.

This page is for maintainers publishing an AppImage release from master. The release is built in CI when a v* tag is pushed; the steps below prepare the version, changelog, and metadata before that tag.

Before you tag

  1. Work from a clean master that tracks origin/master; confirm the target tag does not already exist.
  2. Bump updates.py VERSION to the new semver.
  3. Add a dated section to CHANGELOG.md (Keep a Changelog format) and the comparison links.
  4. Prepend release metadata to openbox.metainfo.xml.
  5. Update the README release badge, PARITY.md latest-release text, the bug-report template's version field, and any branch/version references that should track the current release. Leave historical version references in old changelog/metainfo entries and completed specs unchanged.
  6. Run the local gates: 
    ./run_all_tests.sh
python3 -B test_packaging.py
appstreamcli validate --no-net openbox.metainfo.xml   # when available
desktop-file-validate openbox.desktop                 # when available
git diff --check

Build and verify the artifact locally

bash build_appimage.sh

The build produces OpenBox-x86_64.AppImage and OpenBox-x86_64.AppImage.zsync, but does not regenerate the .sha256 sidecar. Regenerate it explicitly:

sha256sum OpenBox-x86_64.AppImage > OpenBox-x86_64.AppImage.sha256
sha256sum -c OpenBox-x86_64.AppImage.sha256

Confirm the embedded version matches the release by extracting the AppImage and checking usr/share/openbox/updates.py VERSION.

Push and tag

  1. Commit the version/changelog/metadata changes, push directly to master, and wait for the Python 3.10 and 3.12 CI jobs to pass for that exact commit.
  2. Create and push an annotated tag: 
    git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

What CI does

Pushing a v* tag triggers .github/workflows/release-appimage.yml, which:

  1. Runs ./run_all_tests.sh.
  2. Builds the AppImage with build_appimage.sh.
  3. Regenerates OpenBox-x86_64.AppImage.sha256 and verifies OpenBox-x86_64.AppImage.zsync exists.
  4. Creates the release with softprops/action-gh-release@v2 and uploads the AppImage, .sha256, and .zsync assets. A tag containing - is marked prerelease.

The release notes are generated by GitHub; edit them to match the changelog section before publishing if needed.

Verify after publishing

  • Confirm GitHub's latest-release API returns the new version and all three assets.
  • Download the AppImage and .sha256 remotely and run sha256sum -c.
  • Start the AppImage and confirm the updater reports the new version as current with no update available.

Pitfalls

  • build_appimage.sh does not regenerate the .sha256 sidecar; a stale checksum must be replaced manually.
  • Release artifacts are Git-ignored and must be uploaded explicitly via the release workflow.
  • Do not tag or publish before CI succeeds for the exact release commit.
  • OpenBoxGL uses only master; there is no release branch or worktree.

Related