Repository navigation
Release and branch strategy
The release number scheme follows the major.minor.patch convention. Periodic minor releases to provide new features or to fix non-critical bugs will be made directly from a commit on main and will be numbered X.Y.0, where Y is incremented by 1 from the previous release.
For a sufficiently major update (incompatibility with previous Avitab data files or similar) then X will be incremented and Y restarted from 0.
Patch releases will be made to fix critical bugs which slip through release testing and cannot be left unaddressed until the next feature release. X and Y remain unchanged, and the patch number increments for each subsequent patch release.
Since Avitab is a public repository and we anticipate forks being created, our policy will be to avoid doing anything that could change the history of any branch in the repository.
Generally we will keep all ongoing development on the main branch, and avoid proliferation of branches.
Completed feature branches will be removed once they have been merged.
We won't create or use release branches as a matter of course. They will only be created if required when main has further commits not appropriate to the release being made.
The most likely scenario for this is when a patch release is required to fix a critical bug for which no mitigation or workaround can be found. In this case a release branch will be created for the patch, branching from the tag it is patching.
The other scenario is when a major release of Avitab has been made, but it is considered appropriate to fix a bug in the previous version. This is unlikely, but in this event a release branch will be created for maintaining the previous version.
We may want to create branches for updates or features that involve many collaborators and/or will be long running. If these branches are to remain up-to-date with normal development on the main branch then rebasing would be the usual way to achieve this, and simplifies later integration into main. However, since rebasing changes history this is not appropriate for branches in the public repository.
Another alternative is to periodically merge commits from main into the feature branch. This should be straightforward, but can complicate subsequent integration back to main.
A compromise alternative which we may use is to periodically rebase the feature development onto the latest main commit by creating a new feature branch and then continuing development on this new branch. To support this, feature branch names will be given a _nn suffix (starting with _00, implied if no suffix was initially created).
When it is deemed useful to bring the branch up-to-date with main, then a new feature branch will be created with the next suffix (in a cloned repo) and this branch will be rebased (in the cloned repo) onto main and verified, before being before being published to the Avitab primary repo.
Further contributions should be PR'd to target the latest variant of the feature branch, but obsolete feature branches will be kept for a short time to allow all contributors time to migrate, and PRs to an obsolete feature branch can still be applied and then cherry-picked onto the active feature branch.
There is an implied limit of 99 rebases. If any feature branch gets to be that old then something has gone badly wrong!