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)

Multi-root migration development

When changing eai-supmig or migration policy while executing a consumer migration, open ai-workflows/esysrepo-migration.code-workspace in Cursor (consumer esysrepo_dev + upstream superbuild-workflow). See multi-root-development.md.

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.com/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 (Linux/macOS/Git Bash) or scripts/setup-dev.ps1 (Windows):

./scripts/setup-dev.sh

.\scripts\setup-dev.ps1

On Windows, setup-dev.ps1 runs scripts/fix-git-ssl.ps1 first so pre-commit can download hook repos from GitHub. If HTTPS Git fails elsewhere, run that script once:

.\scripts\fix-git-ssl.ps1

Common cause: a stale global http.sslcainfo pointing at a deleted project venv certifi/cacert.pem. The fix sets http.sslBackend=schannel (Windows certificate store) and removes that override. Do not point global Git SSL settings at per-project venv paths.

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
ruff, ruff-format	pre-commit	Python lint and format (src/, tests/; same rules as CI)
gitlint	commit-msg	Enforce commit message format

Run manually:

pre-commit run --all-files

CI

.gitlab-ci.yml runs on pushes to develop, master, merge requests, and tags:

• lint: pre-commit run --all-files (.pre-commit-config.yaml; includes ruff, file hygiene, YAML checks). The job installs git in python:3.11-slim because pre-commit requires it. gitlint (commit-msg) remains local-only.
• test: pytest with coverage
• Do not fast-forward master until the develop pipeline is green
• Tag or submodule bump guidance for consumers lives in workflow.md

If you changed hooks or Python style, run pre-commit run --all-files before push so CI matches local commits.

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