Repository navigation
Release Process
Branch model: feature → staging → main. Releases are cut from main
via an annotated vX.Y.Z tag, which triggers
main.yml
to build platform binaries, installers, the SDK, the WASM bundle, and a
GitHub Release.
- All tasks in
doc/dev-notes/vX.Y.Z-requirements.mdare DONE or explicitly deferred. -
staging.ymlis green on the lateststagingcommit (all 22 jobs). - Versioned files are bumped to
X.Y.Zin one commit:-
src/CMakeLists.txt—MNE_CPP_VERSION_MAJOR/MINOR/PATCH -
doc/Doxyfileanddoc/Doxyfile.internal—PROJECT_NUMBER -
CITATION.cff—version:anddate-released: -
README.md— version badge -
CHANGELOG.md— new section with highlights -
doc/website/docusaurus.config.ts— site version
-
- Doxygen passes with zero warnings for new/changed code.
- Website builds without broken links.
- Run Release Candidate (
release-candidate.yml, Run workflow onstaging). It is GO only when the Staging run of that commit is green,scripts/release/preflight.pypasses, every dashboard criterion is met (generate_quality_report.py --gates), the signing credentials are set and the evidence bundle verifies. Approve thereleaseenvironment; the bundle stays attached to the run for 90 days. - Release exactly the approved commit
<SHA>;main.ymlrefuses a tag whose commit has no successful candidate run:
python3 scripts/release/preflight.py --commit <SHA> --remote origin
git checkout main
git pull --ff-only origin main
git merge --ff-only <SHA>
git push origin main
git tag -a vX.Y.Z -m "Release vX.Y.Z — <codename>" <SHA>
git push origin vX.Y.ZEvery release step can be rerun: assets are uploaded with --clobber, the
evidence job rewrites SHA256SUMS, release-evidence.json and its section of
the release notes in place, and the website deploy replaces the site.
| Situation | Action |
|---|---|
| A platform/installer job failed |
Re-run failed jobs on the tag's main.yml run, then re-run ReleaseEvidence and VerifyRelease. |
| An asset is missing or corrupt on the release page | Re-run the job that uploads it; VerifyRelease fails until SHA256SUMS and the asset agree. |
| Website deploy failed | Re-run the Website job; nothing else depends on it. |
dev_build is broken or deleted |
Run staging.yml manually; it recreates the pre-release from the last commit whose builds all compiled. |
| A wrong commit was tagged | Do not move the tag. Fix forward with vX.Y.(Z+1); deleting a published tag needs the maintainers' explicit approval because downstream mirrors and Zenodo have already archived it. |
Recovery never needs credentials on a local machine: signing, notarization and uploads run only in CI from repository secrets.
| Workflow file | Output |
|---|---|
main.yml |
Orchestrator — calls the workflows below and creates the GitHub Release |
release-linux.yml |
Linux dynamic + static .tar.gz
|
release-macos.yml |
macOS dynamic + static .tar.gz
|
release-windows.yml |
Windows dynamic + static .zip
|
release-installer.yml |
QtIFW cross-platform installers |
release-sdk.yml |
mnecpp-X.Y.Z-sdk-<plat>.tar.gz (CMake find_package) |
Tagged releases are signed or they fail, unless a platform is opted out below.
The macOS staging and main builds are signed and notarized too; their
Windows builds stay unsigned. release-evidence.json and the release notes record the status of
every artifact, and SHA256SUMS covers all of them.
Windows (Authenticode via SignPath Foundation).
The signpath-sign
action submits the deployment .zip files and the installer .exe to the
SignPath project mne-cpp (signing policy release-signing) and verifies
every signed file with signtool verify /pa /all /tw. Repository settings:
| Kind | Name | Value |
|---|---|---|
| Secret | SIGNPATH_API_TOKEN |
API token of a submitter in the SignPath project |
| Variable | SIGNPATH_ORGANIZATION_ID |
SignPath organization ID |
The two artifact configurations (files are uploaded unwrapped) are kept in the repository and must be pasted unchanged into SignPath:
| SignPath slug | Repository file | Signs |
|---|---|---|
windows-archive |
.signpath/artifact-configurations/windows-archive.xml |
mne_*.exe, mne_*.dll and mne_*_plugins/*.dll inside the deployment .zip files; Qt and other third-party DLLs are not signed |
windows-installer |
.signpath/artifact-configurations/windows-installer.xml |
the Qt Installer Framework .exe itself |
Both restrict every signed file to product-name="MNE-CPP" and
product-version="${version}", as the SignPath Foundation requires. The action
passes version (from src/CMakeLists.txt) with each request and first runs
scripts/release/pe_metadata.py check against the same XML, so a binary without
the version resource of
cmake/mne_version_info.rc.in
fails the build with its name. The installer template installerbase.exe gets
that resource from pe_metadata.py stamp before binarycreator runs.
macOS (Developer ID, paid Apple Developer Program). The apps, tools and
libraries of the dynamic build, the .dmg images and the QtIFW installer are
signed with the hardened runtime, notarized with notarytool, stapled and
verified before upload; see MacOS-Code-Signing.md for the
pipeline, the three operating modes and the secrets (APPLE_APPLICATION_CERT_BASE64,
APPLE_APPLICATION_CERT_PASSWORD, APPLE_ID, APPLE_ID_PASSWORD, APPLE_TEAM_ID).
The .tar.gz archives contain the notarized code and are covered by SHA256SUMS.
To release without an Apple Developer ID, set the repository variable
MACOS_SIGNING to unavailable. The macOS builds are then only ad-hoc signed,
the release candidate no longer asks for the Apple secrets, the release notes
mark both .dmg images as unsigned and explain how to open them, and the
release verification requires exactly that. Delete the variable once the Apple
secrets are configured.
Likewise, to release before SignPath's release certificate is active, set
WINDOWS_SIGNING to unavailable. The Windows .zip and .exe assets are
then not submitted to SignPath, the release notes mark them as unsigned and
explain the SmartScreen warning, and the release verification requires exactly
that. Delete the variable once the release-signing policy is valid.
- Verify all artifacts are attached to the release page.
- Verify the website's "Latest version" banner updated
(auto via Docusaurus
versionfield). - Check Zenodo minted a new versioned DOI (concept DOI is
10.5281/zenodo.593102). - Open the next release's task sheet (
doc/dev-notes/vX.Y.(Z+1)-requirements.md).
For vX.Y.(Z+1):
- Cherry-pick fixes from
stagingontomain. - Bump
CHANGELOG,CITATION.cff,READMEbadge. - Tag
vX.Y.(Z+1)onmain.
MNE-CPP — BSD-3-Clause licensed · Maintained by the MNE-CPP authors · Website · API · Source
Edit this wiki via
doc/wiki/— direct edits in the GitHub UI are overwritten on next push tomain.