You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
State as of 2026-11-03 (after the 3.10.2 release). TODO: marks blanks to fill in.
1. Before the release
Step
Where
Notes
Code and component changes merged
mccode-dev/McCodemain
Full set of testsuites "acceptable"
Manual run of CI on main / last branch with "code" changes
Run the pre-release workflow with the wanted tag, merge its PR
Actions → pre-release → Run workflow (vX.Y.Z), or gh workflow run pre-release.yml -f tag=vX.Y.Z
Opens "Pre-release updates for vX.Y.Z" (branch external/pre-release-vX.Y.Z) with: \reldate bumped to the current month, instrument .md's (mcdoc/mxdoc --in-repo --md), tool-doc .html twins, and manual PDFs + html tgz rebuilt into docpkg/manuals/{mcstas,mcxtrace}/. Run it after the last code change; the release ships whatever is committed. The bot PR does not start CI (docs only). By hand: docs/manuals/BUILDING.TXT.
Hand-maintained package lists. The pre-release PR text lists built packages that are missing; add those that should ship (e.g. webgl-classic, #3018). MSVC installers pull from conda-forge instead.
Draft the release notes
Text becomes the GitHub release body, which becomes RELEASE_NOTES.md. Tip: use the GitHub release-drafting
Put the notes in CHANGES_McStas / CHANGES_McXtrace, merge
McCode main
Must be merged before tagging: the McStas website copies CHANGES_McStas from the tag. Consider options for automation
2. At the release
Create and publish the GitHub release with a new tag vX.Y.Z on main:
web UI, or gh release create vX.Y.Z -R mccode-dev/McCode --notes-file notes.md.
Publish it, don't just push a tag: with a bare tag the autobuild creates a
draft, and every step below ignores drafts until you publish it.
A pre-release is skipped by all downstream automation (useful for test builds).
Merge the "INSTALL docs for vX.Y.Z" PR that install-docs opens
(branch external/install-docs-vX.Y.Z). It bumps INSTALL-McStas/ and
INSTALL-McXtrace/ and writes RELEASE_NOTES.md from the release text.
The text is read once, at publish time; later edits to the release body are not picked up.
Wait / check (all automatic, see section 3):
about 1 h: autobuild attaches the archives to the release;
≤ 3 h after that: the apt repo has the new .debs;
≤ 1 h after the archives: both websites show the new version.
To skip the waiting, once the archives are attached use Run workflow on
publish (mccode-dev/debian), then pages (mccode-dev/mcstas, mccode-dev/mcxtrace).
conda-forge: conda-forge/mcstas-suite-feedstock and mcxtrace-suite-feedstock:
version and sha256 in recipe/meta.yaml (recipe/release_sync.sh X.Y.Z prints them).
The update usually happens pr. bot PR, may also be done by by hand from the feedstocks.
Manual step:
Major (4.0.0) and minor (3.11.0), require announcement, increments/bugfixes (3.10.3) do not
Add newsflashes on front pages (edit contents/main.html/, …)
McStas/McXtrace FaceBook pages
3. What runs automatically on a release
Workflow
Repo
Trigger
Does
Needs
mcstas-autobuild, mcxtrace-autobuild
McCode
push of tag v*
Builds all platforms; assemble-release uploads <flavor>-debian-{x86_64,arm64}.tgz, -macOS-conda.tgz, -Windows-{MinGW,MSVC}-x86_64.tgz to the release (creates a draft if none exists)
—
install-docs
McCode
release published (not pre-release), or dispatch with a tag
Opens the INSTALL docs PR
Ruleset: the bot may only create external/** branches
McCode Pooch Registries Dispatch
McCode
any tag created/deleted
Notifies mccode-dev/mccode-pooch-registries
secret RECEIVER_TOKEN
publish
debian
every 3 h (23 */3 * * *), dispatch
Adds the newest releases that have all four debian tgz; latest cif2hkl from SOLEIL GitLab; any .deb uploaded by hand to the apt release; re-signs; install test on amd64 + arm64; re-enables itself on scheduled runs (keepalive)
secret APT_GPG_KEY
pages
mcstas, mcxtrace
hourly (41 * * * *), push to main/master, dispatch
Finds the newest published release with <flavor>-debian-x86_64.tgz, installs its .debs (apt, using the debian repo), runs mcdoc/mxdoc, builds the site with createweb.pl, deploys; re-enables itself on scheduled runs (keepalive). On a new version a bot commit updates contents/download/current, the manual PDFs and (McStas) CHANGES*
the debian repo must already carry the release's dependencies (cif2hkl, mcpl, ncrystal)
Hand-written index.html; links mcstas.org, mcxtrace.org and root-relative /debian/, /mcstas-nightly/, … As the org site, its custom domain also moves every project site without its own domain to mccode.org/<repo>/ (github.io URLs redirect).
The packages themselves are assets of the apt release (github.com/mccode-dev/debian/releases/download/apt/), so the apt URL doesn't depend on Pages or the domain.
packages.mccode.org/debian: redirects old [trusted=yes] … stable main clients to the new repo; mccode.list/mccode.sources there point to the new repo.
download(s).mcstas.org/current, download(s).mcxtrace.org/current: redirect to INSTALL-McStas / INSTALL-McXtrace on GitHub.
Old download archive (download.mcstas.org/mcstas-*), workshops, … TODO: Decide what to keep and what not to keep. Migrage to 'frozen' pages on ESS infrastructure?
5. Interconnections and things to keep an eye on
Order matters at release time: CHANGES merged → release published → autobuild
archives → apt repo (needs all four debian tgz) → websites (install from the apt repo).
If the apt repo is behind, the website build can't resolve the new .debs' dependencies.
Scheduled workflows run only from the default branch, and GitHub disables
them in a public repo after 60 days without repository activity. publish
(debian) commits nothing, so it re-enables itself via the API on every scheduled
run, which resets the clock; pages (mcstas/mcxtrace) does the same in its hourly
release job. If updates still stop, check gh workflow list -a -R mccode-dev/<repo>
and re-enable with gh workflow enable <name> -R <repo>.
Secrets that expire:APT_GPG_KEY (debian; the signing key expires
2029-11-01, extend it and re-publish mccode-apt.gpg/.asc before then),
NIGHTLY_TOKEN (McCode + both nightly repos), RECEIVER_TOKEN (McCode). TODO: token expiry dates.
apt release asset limit: GitHub allows 1000 assets per release. Now 351
(346 .debs + 5 index files); each McCode release adds about 86, so room for about
7 more releases before old 3.x versions must be pruned (or moved to a second release).
Bot branch ruleset in McCode: "Limit Registrar to external/ branches", so any
new bot that pushes to McCode must use external/....
Metapackage dependencies are unversioned (mcstas-suite-python depends on mcstas,
not mcstas (= X.Y.Z)), so apt install mcstas-suite-python=<old> doesn't roll back.
Fixed revisions can be added with gh release upload apt <pkg>_X.Y.Z-1_all.deb -R mccode-dev/debian
and a publish run.
Legacy packages in the apt repo: McStas 2.7.2 and McXtrace 1.7.1
(*-suite-{python,perl}-legacy), side by side with 3.x; Perl tools need pgplot5 (multiverse).
Pages CDN cache: up to 10 minutes. After a domain or prefix change, pages can
show stale HTML (broken images) for that long; hard reload.
Custom domains: mcstas.org / mcxtrace.org / mccode.org are set in each repo's
Settings → Pages; the website build takes its URL prefix from that setting
(configure-pages), so changing a domain needs one pages rebuild.