Skip to content

Releasing

Jump to bottom
ekollof edited this page Jun 10, 2026 · 3 revisions

Releasing

This page documents how to cut a release of Xepher and publish distribution packages.

Version scheme

Xepher uses semantic versioning (MAJOR.MINOR.PATCH):

Bump When
PATCH Bug fixes, performance improvements, no new user-visible features
MINOR New user-visible features or significant behaviour changes
MAJOR Breaking changes or major architectural rewrites

Current release: v0.8.1

Release checklist

  1. Ensure all commits are pushed and make DEBUG=1 passes all 123 doctests.
  2. Bump the version in the three packaging files (all must match):
    • packaging/arch/PKGBUILD → pkgver=X.Y.Z (and packaging/arch/stable/PKGBUILD if present)
    • packaging/rpm/weechat-xmpp.spec → Version: X.Y.Z + new %changelog entry
    • packaging/debian/changelog → new stanza at the top
  3. Commit the bump: 
    git add packaging/arch/PKGBUILD packaging/arch/stable/PKGBUILD \
        packaging/rpm/weechat-xmpp.spec packaging/debian/changelog
git commit -m "chore: bump packaging to vX.Y.Z"
  4. Tag the release: 
    git tag -a vX.Y.Z -m "vX.Y.Z — <one-line summary>"
  5. Push commits and tag: 
    git push && git push origin vX.Y.Z
  6. GitHub Actions builds packages automatically (.github/workflows/packages.yml). Monitor with: 
    gh run watch --repo ekollof/xepher
  7. Edit the release on GitHub if needed (title, notes): 
    gh release edit vX.Y.Z --title "vX.Y.Z — <summary>" --notes "..."

CI package builds (primary)

Pushing a v* tag triggers the Packages workflow. It runs packaging/github-build.sh <version> on ubuntu-latest, building all five distros sequentially in fresh Docker containers:

Distro Docker image Script
Debian debian:stable build-deb-inside.sh
Fedora fedora:latest build-rpm-inside.sh
Arch archlinux:latest docker-arch-wrapper.sh → build-arch-inside.sh
Alpine alpine:edge build-alpine-inside.sh
Void ghcr.io/void-linux/void-linux:latest-full-x86_64 build-void-inside.sh

Artifacts are attached to the GitHub Release automatically via softprops/action-gh-release.

All packaging paths pass PACKAGE_BUILD=1 to make, which skips the dev-only .source ELF section embed. Without this, tarball builds lacking .git can produce gigabyte-sized RPM/APK packages.

Local package verification

Before tagging, you can run the same script CI uses (requires Docker):

bash packaging/github-build.sh X.Y.Z              # all distros
bash packaging/github-build.sh X.Y.Z --fedora   # single distro

Output: packaging/build/

Format File pattern
Debian/Ubuntu xepher_X.Y.Z-1_amd64.deb (+ xepher-dbgsym_…)
Fedora RPM xepher-X.Y.Z-1.fcNN.x86_64.rpm
Arch Linux xepher-X.Y.Z-1-x86_64.pkg.tar.zst (+ -debug-…)
Void Linux xepher-X.Y.Z_1.x86_64.xbps
Alpine xepher-X.Y.Z-r0.apk

Optional: persistent distrobox builds

For faster iterative local builds, packaging/distrobox-build.sh reuses persistent containers and stamps installed deps under /opt/xepher-build/:

bash packaging/distrobox-build.sh X.Y.Z
bash packaging/distrobox-build.sh X.Y.Z --debian

Prerequisites: distrobox + docker or podman.

Manual release fallback

If CI is unavailable, build locally then create the release manually:

gh release create vX.Y.Z \
  --title "vX.Y.Z — <summary>" \
  --notes "..." \
  --target master \
  packaging/build/xepher_X.Y.Z-1_amd64.deb \
  packaging/build/xepher-dbgsym_X.Y.Z-1_amd64.deb \
  packaging/build/xepher-X.Y.Z-1.fcNN.x86_64.rpm \
  packaging/build/xepher-X.Y.Z-1-x86_64.pkg.tar.zst \
  packaging/build/xepher-debug-X.Y.Z-1-x86_64.pkg.tar.zst \
  packaging/build/xepher-X.Y.Z_1.x86_64.xbps \
  packaging/build/xepher-X.Y.Z-r0.apk

Branch protection

master is protected on GitHub — force pushes and branch deletion are blocked. Direct pushes from the maintainer are still allowed.

Clone this wiki locally