braidlab workflow

braidlab workflow

This page is a practical, step-by-step maintainer guide.

For full CI (Continuous Integration: automatic checks that run after you push code, including build and packaging jobs in GitHub Actions) details and release knobs, see:

• devel/CI-WORKFLOW.md
• devel/RELEASE-CONFIG.md
• .github/workflows/build-braidlab-packages.yml

General branch structure

The repository is maintained in a GitFlow-style pattern:

• master is the release branch.
• develop is the main development branch.
• Most work happens in feature branches off develop, usually named issXXX-<description>.

New features are merged into develop when ready, typically with --no-ff so the merge commit records branch context.

Build and packaging model (current)

The CMake build is split into three parts:

1. Build rules (compile/link) in CMakeLists.txt.
2. Package layout install rules in cmake/BraidlabPackage.cmake.
3. GMP bundling rules in cmake/BraidlabBundledGMP.cmake.

Local build quickstart

From repository root:

cmake -S . -B build
cmake --build build -j
cmake --install build --prefix .

GMP modes:

• -DBRAIDLAB_GMP_LINKAGE=system (default)
• -DBRAIDLAB_GMP_LINKAGE=bundled
• -DBRAIDLAB_GMP_LINKAGE=off

Note: static is reserved but not implemented yet.

Before creating a release

Use this as a pre-release reminder list:

• Close or retarget issues in the milestone.
• Confirm CHANGELOG.md is current.
• Check whether copyright year/email boilerplate needs updates.
• Check README.md links, years, and contributor acknowledgements.
• Check guide examples and expected output.
• Check whether bundled external code needs refresh (extern/).
• Run tests with and without 'nomex'.
• Make sure develop is pushed.

Typical test commands from MATLAB:

addpath(pwd)
cd testsuite
test_braidlab
test_braidlab('NoMEX')

Creating a release (step-by-step)

1. On develop, finish release notes in CHANGELOG.md. Update version number and release date. (Leave unreleased section; it will be removed in the master branch.)

   • Also update the links in CHANGELOG.md at the bottom giving differences between versions.
   • Commit those changes to CHANGELOG.md in develop.

2. Create a release branch from develop:

   git checkout -b release-X.Y.Z-branch

3. Commit release-only edits on the release branch, including:

   • hardwired doc/getrelease.tex (set X.Y.Z explicitly),
   • final CHANGELOG.md cleanup (remove the Unreleased section on the release branch),
   • any other release polish.

   Typical commit command:

   git add CHANGELOG.md doc/getrelease.tex
   git commit -m "Prepare release-X.Y.Z metadata and guide"

4. Remove devel/ from the release branch before merging to master, and commit that removal on the release branch:

   git rm -r devel
   git commit -m "Remove devel from release branch before merge to master"

5. Merge release branch into master and tag the release:

   git checkout master
   git pull
   git merge --no-ff release-X.Y.Z-branch
   # resolve merge conflicts in CHANGELOG.md and doc/getrelease.tex
   git commit
   git tag -a release-X.Y.Z -m "Release X.Y.Z"
   git push
   git push --tags

6. The git push command above starts GitHub Actions, which builds the release zip/tar files for tag release-X.Y.Z. To download package files:

   • open Actions in GitHub,
   • open Build Braidlab Packages,
   • select the run started by tag release-X.Y.Z (not the separate run started by a branch push),
   • scroll to the Artifacts section and download the generated .zip/.tar.gz files. Attach those downloaded files to the GitHub Release page. (Historical note: older releases used makedist-release-X.Y.Z tags and ./devel/makedist to build archives locally. Those extra makedist tags are no longer needed.)

7. After the release is tagged, return to develop and check release-only edits:

   • Keep edits that should remain in day-to-day development.
   • If doc/getrelease.tex was hardwired only for release prep, restore the non-release form on develop.

Gotchas and reminders during release

• If merge conflicts appear in release files, clean all conflict markers before committing.
• The most common conflict files are CHANGELOG.md and doc/getrelease.tex.
• Keep release-only edits out of develop unless they should persist there.
• The PDF guide is built by GitHub Actions during release packaging, so it does not need to be committed to the repository for release archives.
• If a package file is missing expected files, check the staging and packaging steps in the GitHub Actions job output.

Merging a feature branch

Typical flow:

git checkout <feature-branch>
git pull
git checkout develop
git pull
git merge --no-ff <feature-branch>
git push
git branch -d <feature-branch>
git push origin --delete <feature-branch>

Hotfix procedure

For urgent fixes that must go directly into a release:

git checkout master
git pull
git checkout -b hotfix-<short-description>
# make and commit the fix
git checkout master
git merge --no-ff hotfix-<short-description>
git tag -a release-<next-version> -m "Hotfix release <next-version>"
git push
git push --tags
git checkout develop
git pull
git merge --no-ff hotfix-<short-description>
git push

Pulling and rollback tips

To reduce unnecessary merge commits on pull, git pull --rebase is often useful.

For undo operations, avoid git reset --hard as a routine step. Safer choices are:

• git restore <path> for local unstaged file changes.
• git revert <commit> for undoing already-published commits.