Git Workflow for Trento Documentation

This document explains how documentation changes move between main and latest in this repository. It covers branch roles, release promotion, partial release updates, and hotfix backports. For CI behavior, publication schedules, and build details, see CI and publishing overview and Documentation build pipeline overview.

Overview

main is the development branch and source of truth for upcoming documentation changes.
The docs hub publishes main as pre-release.
latest is the current release branch.
The docs hub publishes latest as latest: X.X.
Normal documentation changes start from main and are merged back into main.
Released content reaches latest only through reviewed Pull Requests by the documentation team.
Partial release updates move several already-merged main changes to latest without changing the current release label.
Hotfixes are merged into main first and then backported to latest.
Optional vX.Y branches preserve older published snapshots.

Branch Roles and Responsibilities

This workflow uses two protected, long-lived branches for normal work and one optional branch type for archived releases.

main

Development branch and source of truth for documentation that is still in progress. The docs hub publishes this branch as pre-release. Branch from main for normal work and open Pull Requests back to main.
latest

Current release branch and source of truth for the currently published release. The docs hub publishes this branch as latest: X.X. Do not target latest for normal content work. Update it only through reviewed Pull Requests for full release promotions, partial release updates, or hotfixes.

latest is always the branch name. latest: X.X is the user-facing label shown in the version switcher of the docs hub.

Ownership and Review Expectations

Ownership of the repository and its release branches is shared in practice, but each branch has a different role:

the repository is owned by the Trento team
main is the collaboration branch used by the Trento developers and the documentation team
latest is a shared release branch because it is the source for the current published user-facing documentation

Because latest feeds the current published user-facing documentation, changes under trento/ that are promoted to latest should be reviewed by a member of the documentation team.

Branch Protection

To keep the release flow predictable:

both main and latest are protected branches
all changes, including releases and hotfixes, go through Pull Requests

This prevents direct unreviewed changes and keeps the published branches auditable.

Workflows

Each documentation task follows one of four workflows: normal contribution, full release promotion, partial release update, or hotfix backport.

1. Developing New Content

Use this workflow for normal documentation work. It keeps latest stable while new material is developed on main.

Sync local main
```
git checkout main
git pull origin main
```

Create a feature branch

git checkout -b feature/describe-new-feature

Make and review your changes

Edit, preview, and commit your changes locally.
Open a Pull Request to main

Push your branch and open a Pull Request targeting main.

Normal documentation work is merged into main only. Do not open feature or content Pull Requests against latest.

2. Publishing a New Release

Use this workflow when the current state of main is ready to become the new current release on latest.

Sync local main
```
git switch main
git pull origin main
```

Sync local latest

git switch latest
git pull origin latest

Create a release branch from latest
```
git checkout -b release/prepare-vX.Y
```
Starting from latest keeps the promotion branch anchored to the current release state.
Merge main into the release branch
```
git merge --no-ff main
```
The --no-ff option keeps the promotion as an explicit merge commit, even when Git could fast-forward. This gives latest a clear history marker for the moment when a new release was promoted from main. Without it, the promotion could disappear into a linear history and look like a normal sequence of commits. Keeping the merge commit makes later review, release tracing, and hotfix analysis easier.
Resolve merge conflicts

Conflicts can happen at this point, especially in antora.yml. This deserves its own step because main and latest intentionally carry different version metadata in trento-docs-site/antora.yml. On main, the docs are configured as pre-release, while on latest, the same file identifies the current release as latest: X.X. When you merge main into a release branch created from latest, Git must reconcile those two different states before the new release metadata is set. Resolve conflicts first so the release branch has a clean, intentional merged state before you update the new release metadata.

Stage the resolved files and commit the merge result:
```
git add antora.yml
git commit
```
If more than one file conflicts, stage each resolved file before committing.
Update release metadata

Edit antora.yml so the current release label reflects X.Y, then commit that change.
Push the release branch and open the promotion Pull Request
```
git push origin release/prepare-vX.Y
```
Then open a Pull Request targeting latest. After review and approval by the documentation team, merge the Pull Request. At that point, latest represents the current release and the docs hub shows it as latest: X.X.

Content moves from main to latest only through reviewed Pull Requests.

For publication timing and CI behavior after the merge, see CI and publishing overview.

3. Applying a Partial Release Update

Use this workflow when the current release on latest needs documentation updates, but the published release label must stay the same. This is the preferred path when several reviewed changes are already on main and should move together to latest without repeated cherry-picks.

Sync local main
```
git switch main
git pull origin main
```

Sync local latest

git switch latest
git pull origin latest

Create an update branch from latest
```
git checkout -b update/current-release-docs
```
Starting from latest keeps the update branch anchored to the current published release.
Merge main into the update branch
```
git merge --no-ff main
```
The --no-ff option keeps the partial update as an explicit merge commit. A partial release update adds a merge-based promotion point to latest without changing the release version. The merged main commits become part of latest history through that merge, instead of being replayed one by one as cherry-picks. This preserves a clearer relationship between main and latest for grouped documentation maintenance.
Resolve merge conflicts

Conflicts can happen here for the same reason as in a full release promotion, especially in trento-docs-site/antora.yml. main identifies the docs as pre-release, while latest identifies the current published release as latest: X.X. When you merge main into an update branch created from latest, Git must reconcile those two states before the branch is ready. Resolve the conflicts so the documentation content changes from main are included, but the current latest release identity is preserved.

Stage the resolved files and commit the merge result:
```
git add antora.yml
git commit
```
If more than one file conflicts, stage each resolved file before committing.
Keep the current release metadata

Do not bump version or display_version in trento-docs-site/antora.yml. The goal is to update the current release content while keeping the existing latest: X.X label unchanged.
Push the update branch and open the Pull Request
```
git push origin update/current-release-docs
```
Then open a Pull Request targeting latest. After review and approval by the documentation team, merge the Pull Request. At that point, latest contains the promoted documentation updates, but the published release label remains latest: X.X.

Use partial release update when several already-reviewed documentation changes should move together from main to latest. Use the hotfix workflow when one urgent targeted fix must be backported independently.

4. Applying a Critical Hotfix

Use this workflow for urgent fixes that must reach the currently published documentation. Prefer the partial release update workflow when several already-reviewed documentation changes should move together from main to latest without a version bump.

Sync local main
```
git switch main
git pull origin main
```
Create a hotfix branch from main
```
git checkout -b fix/typo-in-command
```
Commit the fix and open a Pull Request targeting main. This keeps the development branch consistent with the published fix.
Use one logical hotfix per Pull Request

Handle one hotfix Pull Request on main at a time. For each merged hotfix, open one matching backport Pull Request on latest. Do not bundle unrelated urgent fixes into one backport unless there is a strong reason. One logical hotfix on main should normally produce one backport Pull Request to latest.

Sync local latest

git checkout latest
git pull origin latest

Create a backport branch from latest
```
git checkout -b hotfix/backport-typo
```
Identify the hotfix commit or commits

Find the merged commit hash or hashes from main. If the hotfix is one commit, use that commit. If the hotfix spans multiple commits, use the commits for that fix in their original order, oldest first. Git applies cherry-picked commits as patches, so later commits can depend on changes introduced by earlier ones. Keeping the original order makes the backport easier to apply cleanly and preserves the same logical fix sequence as main.
Cherry-pick the hotfix into the backport branch

Run the matching command:
```
git cherry-pick <commit-hash>
```
Or, for a multi-commit hotfix:
```
git cherry-pick <older-commit-hash> <newer-commit-hash>
```
Push the backport branch and open the Pull Request
```
git push origin hotfix/backport-typo
```
Open a Pull Request targeting latest.
Backport multiple hotfixes one at a time

If more than one hotfix must be backported, handle them one at a time whenever possible. After one hotfix Pull Request merges into latest, start the next backport branch from the updated latest. This avoids branch drift and reduces cherry-pick conflicts from outdated backport branches.

Hotfixes are never made only on latest. Merge the fix into main first, then cherry-pick it into latest so the branches do not drift apart.

Optional: Archiving Old Versions

Use this workflow only if older published versions should remain selectable in the docs hub after a new release is promoted.

Create an archive branch from the current latest
```
git checkout latest
git pull origin latest
git checkout -b vX.Y
git push origin vX.Y
```
Create the archive branch before promoting the next release so it captures the exact state of the current published documentation.
Add the archive branch to the Antora playbook

Include the archive branch in antora-playbook.yml:
```
content:
  sources:
    - url: .
      branches: [main, latest, vX.Y]
```
When archive branches are included in the playbook, they appear as additional selectable versions in the docs hub.

Summary

main is where normal documentation work happens and is published as pre-release.
latest is the current release branch and is updated through reviewed full release promotions, partial release updates, or hotfix Pull Requests.
Optional vX.Y branches preserve older published versions when needed.