Branching Model & Release Lifecycle

TraceForge uses a streamlined two-branch Git model designed for predictability, defensiveness, and continuous stability:

                     master  (Stable Public Releases)
                       ▲
                       │  Release PR (Validated & Tagged)
                       │
                      beta   (Active Development & Release Candidates)
                   ▲   ▲   ▲
                   │   │   │  Pull Requests
              feature fix docs  (Short-Lived Working Branches)

Branch	Role	Mutability	Release Policy
`master`	Stable Public Release	Protected (No direct commits)	Merged strictly from `beta` via reviewed Release PRs
`beta`	Active Integration & RC	Protected (CI & review required)	Merged from temporary `feature/`, `fix/`, `docs/*` branches

1. Branch Roles & Rules

`master` (Stable)

Contains exclusively tested, production-ready, release-tagged code.
Every commit on master corresponds to a semantic release tag (e.g. v1.0.0, v1.0.1, v1.1.0).
Zero direct pushes: Changes enter master only via a reviewed and CI-verified pull request from beta.

`beta` (Development & Integration)

The default target branch for all feature additions, platform improvements, bug fixes, and documentation updates.
Remains stable and runnable at all times (not an unstable dumping ground).
Receives release candidate tags (e.g. v1.1.0-beta.1) when staging major features before merging to master.

2. Working Branches (Short-Lived)

All active development occurs on short-lived branches created from beta:

Branch Prefix	Purpose	Example	Target
`feature/`	New tools, investigation capabilities, or export formats	`feature/termux-storage`	`beta`
`fix/`	Bug fixes, platform compatibility patches	`fix/catalog-tsv-parser`	`beta`
`docs/`	Documentation improvements, legal guides	`docs/responsible-use`	`beta`
`security/`	Defensive hardening and vulnerability mitigations	`security/path-traversal-guard`	`beta`
`hotfix/`	Urgent production fixes targeting `master` directly	`hotfix/1.0.1-export-crash`	`master` + backport

[!NOTE] Delete working branches immediately after their pull request is merged to keep the repository clean.

3. Pull Request (PR) Workflow

Fork or Clone
     ↓
git checkout beta
git pull origin beta
git checkout -b feature/<name>
     ↓
Implement & Verify Functionality
     ↓
traceforge doctor
     ↓
Open Pull Request targeting 'beta'
     ↓
Automated CI Passes + Maintainer Review
     ↓
Squash / Rebase Merge into 'beta'

Pull Request Rules:

Target beta: Normal PRs must NEVER target master.
Verify Functionality: Every new feature or bug fix must be tested and verified with traceforge doctor and catalog audits.
Update Documentation & Changelog: Document user-facing changes under ## [Unreleased] in the repository changelog.
Zero Secret Leakage: Ensure no credentials, test tokens, or private case data exist in commits.

4. Release Promotion: `beta` ➔ `master`

When beta has accumulated validated features or fixes for a release:

Pre-Release Freeze: Ensure beta passes all validation checks on macOS, Linux, and Termux:
```
./scripts/release_check.sh beta
```

Version Bump: Update canonical VERSION and pyproject.toml:

python3 scripts/bump_version.py minor  # or patch / major

Changelog Finalization: Move items from ## [Unreleased] to ## [X.Y.Z] - YYYY-MM-DD in CHANGELOG.md and update RELEASE_NOTES.md.
Open Release PR: Create PR from beta to master titled Release vX.Y.Z.

Merge & Tag:

git checkout master
git merge --ff-only beta
git tag -a v1.1.0 -m "Release v1.1.0"
git push origin master --tags

5. Hotfix & Security Emergency Protocol

If a critical vulnerability or blocker affects the live master release:

 master ➔ hotfix/<version> ➔ test ➔ PR to master ➔ tag patch release
                                           │
                                           ▼
                                 Backport merge to beta

Create a hotfix/ branch from master.
Apply the fix and write a regression test.
Merge into master and tag the patch release (e.g. v1.0.1).
Immediately backport the commit to beta (git checkout beta && git merge master or git cherry-pick) to prevent regressions in future releases.