Releasing & versioning

Versioning scheme

neoOMSI follows Semantic Versioning (MAJOR.MINOR.PATCH) during pre-1.0 development:

1.0.0 is reserved for achieving comprehensive behavioral parity across the OMSI 2.2.032 baseline, not simply for elapsed development time.

Tags

Milestone git tags are created strictly for official releases:

v0.2.0-rc.1
v0.2.0-rc.2
v0.2.0
v0.2.1

Nightly releases update a rolling nightly tag on GitHub Releases rather than creating a permanent git tag per run.

Release workflow

main branch (trunk)
    │
    ├── Nightly builds (scheduled 00:00 UTC & manual dispatch)
    │
    └── Create release branch: release/0.2
            │
            ├── Tag: v0.2.0-rc.1 (testing)
            ├── Tag: v0.2.0-rc.2 (blocker fixes)
            │
            └── Tag: v0.2.0      (final release commit)

1. Nightly builds

Automated CI builds run nightly at 00:00 UTC (and on manual workflow dispatch) for Windows, macOS, and Linux. Nightlies provide immediate visibility into recent changes but carry no guarantee against regressions. Android packages are built locally using scripts/build-android.sh.

2. Preparing a Stable release

When main reaches a stabilization milestone:

1. Create a dedicated branch: release/x.y.
2. Enter feature freeze: only critical bug fixes, documentation corrections, and packaging fixes may be committed to this branch.
3. Keep main open for ongoing feature and parity development. Ensure all fixes on the release branch are cherry-picked back into main.

3. Release Candidates (RCs)

1. Tag the first candidate from the release branch (e.g. v0.4.0-rc.1).
2. Conduct testing across supported operating systems, maps, buses, and hardware configurations.
3. If release blockers are discovered, apply the fix to the release branch and tag v0.4.0-rc.2.

4. Tagging the Stable release

Once an RC exhibits no known release blockers:

• Tag the exact commit of the final accepted RC as the Stable release (e.g. v0.4.0).
• Avoid pushing last-minute, unvalidated changes between the final RC and the release tag.

5. Patch releases

If critical issues are identified post-release:

• Fixes are applied directly to the corresponding release/x.y branch.
• Tag and publish a patch release (e.g. v0.4.1).
• Mirror the fix into main.

Changelog management

To prevent merge conflicts across concurrent pull requests, contributors add small fragment files under .changes/ instead of editing CHANGELOG.md directly:

.changes/<pr-number>.<category>.md

• Nightly CI: Aggregates pending fragments into release summaries without deleting them.
• Stable Releases: A release automation script compiles all accumulated fragments into a new section in CHANGELOG.md and deletes the processed fragment files.
• Fragment Guide: See .changes/README.md for naming rules, categories, and fragment formatting.