Release Flow

Goal: Tag a versioned release on GitHub and let CI handle packaging and publication. This page documents the axi-pcie-core release pipeline: what a tag triggers, what artefacts are produced, and how consumers obtain them.

For the upstream reusable-workflow schema (releases.yaml structure, releaseGen.py inputs, and the gen_release.yml calling conventions), refer to the slaclab/ruckus firmware release how-to.

Prerequisites

  • Write access to the slaclab/axi-pcie-core repository.

  • A GH_TOKEN personal access token with repo scope configured as a GitHub Actions secret in the repository settings.

  • All changes committed and pushed; the working tree on the target commit must be clean.

Step 1: Tag Convention

All releases use semantic versioning in the form vX.Y.Z. Recent tags illustrate the convention:

v6.7.0
v6.6.1
v6.6.0
v6.5.1
v6.5.0

  • Patch releases (Z increment) fix bugs without breaking the <Board>Core port list.

  • Minor releases (Y increment) add new boards or extend feature generics.

  • Major releases (X increment) introduce breaking changes to board-core ports or the AxiPciePkg constants.

Step 2: Tag the Commit and Push

git tag vX.Y.Z
git push origin vX.Y.Z

Pushing the tag triggers the tag-gated jobs in .github/workflows/axi_ci.yml.

What Gets Published

A vX.Y.Z tag push triggers two jobs:

  1. GitHub release — the gen_release job calls slaclab/ruckus/.github/workflows/gen_release.yml@main via the GitHub Actions reusable-workflow mechanism. It runs ruckus/scripts/releaseGen.py to create a GitHub release with auto-generated release notes.

  2. Debian package — the build-deb-pkg job builds a self-contained fpga-pcie-reprogram-vX.Y.Z_amd64.deb using conda-pack and the upload-deb-pkg job attaches it to the GitHub release (along with a checksums.txt SHA-256 manifest). The package wraps scripts/updatePcieFpga and its rogue/pyrogue runtime into a single dpkg-installable artefact.

Note

A conda channel publish (formerly to the tidair-tag channel) is no longer part of this flow. See Migration Note below.

How to Consume a Release

Source consumers (git submodule):

git checkout vX.Y.Z

Pin a specific tag in your downstream project’s .gitmodules or ruckus.tcl submodule initialisation to lock against a known-good release.

Firmware-update tool (Debian package):

Download fpga-pcie-reprogram-vX.Y.Z_amd64.deb from the GitHub release assets page, then install:

dpkg -i fpga-pcie-reprogram-vX.Y.Z_amd64.deb

The installed fpga-pcie-reprogram command wraps scripts/updatePcieFpga.

Safety Checks

The gen_release, build-deb-pkg, and upload-deb-pkg jobs all require startsWith(github.ref, 'refs/tags/'). On non-tag pushes (including pushes to main and feature branches) only the test_and_document job runs; no release artefacts are produced.

The test_and_document job (flake8 + python -m compileall) is a dependency of gen_release, so a tag push that fails linting will not produce a release.

Migration Note

The conda-recipe/ directory and the tidair-tag conda channel publish were removed in this release. Downstream consumers who previously installed via:

conda install -c tidair-tag axi_pcie_core

must switch to one of the following alternatives:

  • Git submodule — pin a specific vX.Y.Z tag in your project. Downstream consumers should switch to the submodule integration path documented in Integrate axi-pcie-core as a Git Submodule.

  • Debian package — install fpga-pcie-reprogram-vX.Y.Z_amd64.deb from the GitHub release assets (covers the firmware-update script use case).

The pip install path via setup.py is unaffected and remains supported.

Upstream Schema Reference

This page intentionally does not redocument the ruckus reusable-workflow input schema. The releaseGen.py script interface, releases.yaml format, and full gen_release.yml calling conventions are documented in the slaclab/ruckus firmware release how-to.