1. Create a feature branch from develop:

   git checkout develop
   git pull origin develop
   git checkout -b feature/lstm-layers

2. Develop the feature with regular commits:

   git add .
   git commit -m "Implement LSTM forward pass"
   git push origin feature/lstm-layers

3. When feature is complete, create a pull request to develop

4. After code review and approval, merge to develop:

   git checkout develop
   git pull origin develop
   git merge --no-ff feature/lstm-layers
   git push origin develop
   git branch -d feature/lstm-layers

This is the sequence actually used from 0.51.0 onward — it differs from a textbook GitFlow release in one important way: the tag lives on the release branch’s own commit, independent of main, because the Maven Central publish workflow triggers on the tag push (on: push: tags: '*' in .github/workflows/publish.yml), not on anything landing on main. main is updated *after a successful publish, as an explicit last step — never before, and never as a side effect of tagging.

1. Create a release branch from develop:

   git checkout develop
   git pull origin develop
   git checkout -b release/1.2.0

2. Perform release preparations, each as its own commit:

   • CHANGELOG.md: full entry for the release

   • README.md: short "What’s New" highlights for this release only, pointing to CHANGELOG.md for history — do not let a "Previously, in …​" cascade accumulate here again

   • docs/antora.yml (skainet_version) and any hardcoded dependency-coordinate snippets in the tutorials (grep for the previous version string across docs/ and README.md to catch drift)

   • ./gradlew generateKernelMatrix generateDocs — run this after the version bump below, not before, or the regenerated docs stamp the wrong version

   • gradle.properties (VERSION_NAME) — its own commit, last, matching release: X.Y.Z

   • Run final tests; fix any release-blocking bugs on the branch

3. Open a PR from the release branch to develop and merge it once CI is green — this is what actually brings the version bump back into the integration branch:

   git push origin release/1.2.0
   gh pr create --base develop --head release/1.2.0 --title "Release 1.2.0"
   # wait for CI to go green, then merge

4. Tag the release branch’s own release: X.Y.Z commit directly — not a commit on main, which doesn’t have this release yet:

   git tag -a 1.2.0 <release-commit-sha> -m "SKaiNET 1.2.0 — <headline>"
   git push origin 1.2.0

   Pushing the tag triggers the publish workflow. Wait for it to go green before the next step — a red publish run means the tag exists but nothing actually shipped to Maven Central; do not treat tagging alone as "released."

5. Once the publish workflow succeeds, merge main up to the release — the step every release before 0.51.0 skipped:

   git fetch origin
   git push origin <release-commit-sha>:refs/heads/main   # fast-forward; main has no protection to route around

   This is a manual step by design (see the main Branch section above) — not automated on publish success. Do it as part of closing out the release, not as an afterthought.

6. Delete the release branch once both merges (into develop and main) are done:

   git push origin --delete release/1.2.0

1. Create a hotfix branch from main:

   git checkout main
   git pull origin main
   git checkout -b hotfix/1.2.1

2. Implement the fix:

   git add .
   git commit -m "Fix memory leak in tensor operations"

3. Merge to main:

   git checkout main
   git merge --no-ff hotfix/1.2.1
   git tag -a v1.2.1 -m "Hotfix version 1.2.1"
   git push origin main --tags

4. Merge to develop:

   git checkout develop
   git merge --no-ff hotfix/1.2.1
   git push origin develop
   git branch -d hotfix/1.2.1

• Use descriptive names that reflect the purpose

• Include issue numbers when applicable: feature/ISSUE-123-transformer-embeddings

• Use lowercase with hyphens: feature/add-attention-mechanism

• Use present tense: "Add feature" not "Added feature"

• Keep first line under 50 characters

• Provide detailed description for complex changes

• Reference issue numbers: "Fix gradient clipping in LSTM (closes #123)"

• Always create pull requests for merging to main and develop

• Require code review before merging

• Include comprehensive description of changes

• Ensure all tests pass before merging

• Use --no-ff flag to preserve branch history

• Follow Semantic Versioning

• Tag all releases with version numbers

• Update version in project files before release

• Maintain CHANGELOG.md with release notes

• Run tests on all feature branches

• Run comprehensive test suite on develop and main

• Block merges if tests fail

• A pushed tag (any branch, in practice always the release/* branch’s own commit) is what triggers the Maven Central publish workflow — not landing on main.

• main is a read-only mirror of "what’s been published," updated manually after the fact (see the Release Process above); it has no deploy step of its own.

• develop is where CI runs on every push/PR; there is no separate staging deploy.

• develop is protected today: required build-job status check, no force-pushes, no deletions, enforced for admins too.

• main is not currently protected — turning that on (required status checks at minimum) is a TODO, tracked so this document doesn’t quietly drift from reality again.