Development workflow

Basic Git workflow for maintaining superbuild-workflow. Aligned with LibesSys esysdox-ops practice: develop for day-to-day work, master for stable consumption, Conventional Commits enforced by pre-commit.

Branches

Branch	Role
develop	Working branch — all day-to-day commits and merge requests
master	Stable branch — fast-forwarded from develop when work is ready (and CI is green when CI exists)

Protected branches: develop, master (and release/*, hotfix/* if used).

Day-to-day flow

develop (commit, push) → CI green → fast-forward master → consumers bump submodule

1. Clone and setup

git clone --recursive ssh://git@gitlab-ai/libesys/ai-workflows/superbuild-workflow.git
cd superbuild-workflow
git checkout develop
./scripts/setup-dev.sh

2. Work on develop

git checkout develop
git pull origin develop
# edit docs, templates, cursor rules
git add <files>
git commit -m "docs(migration): Clarify Windows dual-generator CI gates"
git push origin develop

Do not commit routine work directly to master.

Optional: use a short-lived topic branch from develop for large changes, then merge back to develop (fast-forward or squash per team preference on GitLab).

3. Land on master

When develop is ready and CI is green (when .gitlab-ci.yml exists):

git checkout master
git pull origin master
git merge --ff-only origin/develop
git push origin master

Or open a GitLab merge request develop → master and use Fast-forward merge.

No merge commits on master — --ff-only only.

4. Catch up develop with master

If master moved (e.g. hotfix):

git checkout develop
git fetch origin
git rebase origin/master
git push origin develop

Never git merge master into develop — rebase to keep history linear.

Commits

• Format: commit-messages.md (Conventional Commits + optional AI: footer)
• Checklist: commit-checklist.md
• Prefer one coherent commit per logical change set
• Policy/doc semantic changes: update related docs in the same change set (see .cursor/rules/10-doc-sync.mdc)

Examples:

feat(migration): Add legacy superbuild migration specification

AI: yes

docs: Add Windows dual-generator policy (Ninja + VS for debug and installers)

AI: mixed

Pre-commit hooks

Installed by scripts/setup-dev.sh:

pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg

Hooks:

Hook	When	Purpose
trailing-whitespace, end-of-file-fixer, etc.	pre-commit	File hygiene on Markdown/YAML
gitlint	commit-msg	Enforce commit message format

Run manually:

pre-commit run --all-files

CI (when configured)

When .gitlab-ci.yml is added:

• Pipeline runs on pushes to develop
• Do not fast-forward master until develop pipeline is green
• Tag or submodule bump guidance for consumers lives in workflow.md

Until CI exists, use review and local pre-commit run --all-files before ff-merge to master.

Submodule consumers

Consuming superbuild repos pin tools/ai-rules to a commit on master (or a tagged release). After ff-merge to master, announce bumps so consumers can update submodule pointers.

Agents

• Commit on develop unless explicitly asked otherwise
• Do not push, ff-merge to master, or amend without explicit user request
• Follow commit-messages.md; include AI: footer when assisted
• See AGENTS.md and .cursor/rules/00-governance.mdc

Related documents

• governance.md — what belongs in this repo
• workflow.md — how consumers roll out submodule updates
• commit-messages.md — message format