Development workflow

Basic Git workflow for docs-portal. Aligned with LibESys esysdox-ops and superbuild-workflow practice: develop for day-to-day work, master for stable publication, Conventional Commits enforced by pre-commit.

Branches

Branch	Role
develop	Working branch — all day-to-day commits
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 → publish site

1. Clone and setup

git clone ssh://git@gitlab.com/libesys/ai-workflows/docs-portal.git
cd docs-portal
git checkout develop
./scripts/setup-dev.sh

Windows (PowerShell):

git clone ssh://git@gitlab.com/libesys/ai-workflows/docs-portal.git
cd docs-portal
git checkout develop
.\scripts\setup-dev.ps1

setup-dev installs npm dependencies and pre-commit hooks (including gitlint on commit-msg).

2. Work on develop

git checkout develop
git pull origin develop
# edit docs-common/, docusaurus.config.ts, sync workflow docs, etc.
git add <files>
git commit -m "docs(portal): Clarify content ownership boundaries"
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 preferred).

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 (Conventional Commits + optional AI: footer)
• Checklist: Commit checklist
• Prefer one coherent commit per logical change set
• Portal structure changes: update related docs in the same change set

Examples:

feat: Bootstrap ai workflows docs portal

AI: yes

feat(superbuild): Sync workflow docs and extend sidebar

AI: mixed

Pre-commit hooks

Installed by scripts/setup-dev.sh or scripts/setup-dev.ps1:

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

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

Run manually:

pre-commit run --all-files

Local site verification

After navigation, config, or sync changes:

npm run build

onBrokenLinks: 'throw' in docusaurus.config.ts fails the build on broken internal links.

CI (GitLab Pages)

Pipeline: .gitlab-ci.yml. Runs on pushes to develop and master.

Branch	Publish target
develop	https://docs-portal-1c6c85.gitlab.io
master	Production at https://esys-ai.org

Jobs: audit:website, typecheck → docs:build → pages (+ docs:smoke on master).

• Do not fast-forward master until develop pipeline is green
• Custom domain and DNS: GitLab Pages

Before ff-merge to master, use review, pre-commit run --all-files, and npm run build locally.

Publishing

After master is updated:

1. Sync workflow docs at pinned refs (if not done in CI)
2. npm ci && npm run build
3. Deploy build/ to static hosting

See Publishing model.

Agents

• Commit on develop unless explicitly asked otherwise
• Do not push, ff-merge to master, or amend without explicit user request
• Follow Commit messages; include AI: footer when assisted
• See root AGENTS.md and .cursor/rules/*.mdc (Cursor adapters)
• Edit only docs-portal unless the user approves changes in workflow or sibling repos

Related documents

• Content ownership — what belongs in the portal vs workflow repos
• Publishing model — sync, build, deploy
• Commit messages — message format
• Commit checklist — pre-commit checklist