FujiNet Firmware Versioning

Version numbers are manually increased by developers in the include/version.h file. This doc describes what constitutes a change to the version number and the process for pushing a new release build.

Semantic Versioning

Rules for version bumps go here

Initiate a Release Build

Release builds are triggered by pushing a Tag in the form of vXX.XX.XX where X contains digits (the version number). Any tag beginning with v will trigger a release. The build system uses the Tag description as a display for the end user to show any relevant important changes to the end user. This description should be succinct describing the most important notable changes.

In addition to the description, a change log is created in the release that can be referenced. This change log contains a bulleted list of the commit messages since the last release. It is important for developers to describe commit changes clearly so that end users and other developers can understand what changes have been made. Non descriptive messages such as Tweaks should not be used.

The following steps are to be followed when creating a release build:

Phase 1: The Release

Verify all platforms build with master branch (check Github Actions)
Ensure latest CONFIG binary is pushed into all platforms on master
Test that all officially released platforms can boot/use firmware built from master branch (as of July 2023: ATARI, APPLE2, ADAM)
Create a new branch for the release:
```
git checkout -b release/v1.n.0 master
```

Modify include/version.h in master branch with version and version date/time.

./debug_version.py --set_version v1.n.0 > new_version.h
mv new_version.h include/version.h

Commit the change and open a PR

git commit -a
git push -u origin $(git symbolic-ref --short HEAD)

After PR is merged then
```
git checkout master ; git pull
```

Tag new release:

git tag -a v1.n.0 -m "FujiNet Firmware v1.n.0 May 2026"

Push new tag:
```
git push origin v1.n.0
```

Phase 2: The Kickoff

We do this immediately so that any code written after this moment is clearly marked as "Work in Progress." This prevents development builds from being misidentified as the stable release in bug reports.

Create a branch for the release:

git checkout -b kickoff/v1.n.1-dev master

Bump include/version.h to the next patch level with a -dev suffix (e.g., v1.n.1-dev)

./debug_version.py --set_version v1.n.1-dev > new_version.h
mv new_version.h include/version.h

Commit the change and open a PR and merge it into master
NO TAG: Do not tag the -dev commit. Tags are strictly for frozen release snapshots; the -dev string in the code is the only identifier needed to begin the next cycle.

FujiNet Hotfix Procedure

Use this procedure when a critical bug must be fixed in a previous release (e.g., v1.6.0) while master is already far ahead.

Phase 1: Fix the Bug in Master

CRITICAL: Never apply a fix that hasn't landed in master first to an old release. This ensures the bug does not "re-spawn" in the next major release.

Create a fix branch from master:

git checkout master
git pull
git checkout -b fix/critical-bug-name

Fix and Verify: Apply the fix and test it against the current development environment.

Merge to Master: Open a PR, get it approved by senior devs, and merge to master.

Phase 2: Create the Hotfix Release

Backport that fix to the older version to create the point release (e.g., v1.6.1).

Create a Fix Branch from the old Tag:

git checkout -b fix/v1.6.x v1.6.0

(Replace v1.6.0 with the specific version users are reporting the bug against.)

Cherry-pick the fix: Bring the specific fix from master into this maintenance branch:

git cherry-pick <commit-id-of-fix>

Update Version: Modify include/version.h to the new patch level:

./debug-version --set_version v1.6.1 > new_version.h
mv new_version.h include/version.h

Tag the Hotfix:

git commit -a -m "Bump version to v1.6.1 for hotfix"
git tag -a v1.6.1 -m "FujiNet Firmware v1.6.1 Hotfix - May 2026"

Push:

git push origin maint/v1.6.x --tags

Phase 3: Version Re-Sync (The "Kickoff" Check)

To prevent master from appearing "older" than the hotfix, we must ensure the development version is incremented.

Check master: If master is currently at v1.6.1-dev, it is now technically "older" or conflicting with the v1.6.1 stable you just released.

Immediate Kickoff: Run the Kickoff Procedure on master to move it to v1.6.2-dev. This ensures that any user building from the latest source is always on a higher version number than the latest hotfix.

Join us on Discord: https://discord.gg/7MfFTvD