Branch and release management

Version numbering

This project uses calendar versioning. The scheme is YEAR.MINOR.MICRO, for instance 2023.0.0 or 2023.2.1.

• The major version number is the current year expressed as a 4-digit numeral.
• The minor version number begins with 0 and is incremented for releases that contain significant new features.
• The micro (or "patch") version number begins with 0 and is incremented for release that provide bug fixes or other small changes.

Shared branches

At any time, three branches are in use by the whole team:

• main should always contain the code version that is deployed in production.
• There is a development branch for the next patch version. If the current version is 2023.1.1, then there is a branch named release-2023.1.2.
• And there is a development branch for the next minor or major version. If the current version is 2023.1.1, then there is a branch named release-2023.2.0. Near the end of the year, there may instead be a branch for release-2024.0.0.

Note that there is no other dev branch. A common scenario in other projects is to maintain a single dev branch and only commit version-specific changes, like bumping the version number, to release branches. However, we want to allow for parallel development of changes for minor and patch releases, so we have two release branches and no other dev branch. Whenever a patch is released, the minor release branch should be rebased to it (or the patch can be merged into the minor release branch if changes are complex).

Feature branches: How to manage your changes

In general, development for each issue you work on should be done in its own feature branch. Your code reviewer will merge this branch into the appropriate release branch.

1. Decide whether your changes will belong to the next major/minor or patch release. You can change your mind later and rebase your feature branch, but this is troublesome.
2. In your local development environment, check out the the release branch you decided upon, and pull changes from GitHub. For instance, if your changes will go in version 2023.2.0, run

git checkout release-2023.2.0

# Or you haven't yet fetched the release branch:
git checkout -b release-2023.2.0 origin/release-2023.2.0

# Make sure your copy of the branch is up to date:
git pull

3. Create a new local feature development branch. Name the branch in a way that describes your intended changes, and use kebab-case. For instance, your branch might be named some-new-feature. If you wish, you may use a path-like naming scheme that includes your GitHub username and its number, as in jstone-uw/20/some-new-feature to refer to issue #20.

git checkout -b some-new-feature

4. Make your changes locally and commit them to your local branch.
5. Push your feature branch to a new remote branch on the origin remote. For example:

git push -u origin some-new-feature

6. On GitHub, create a pull request asking to pull the feature branch into the release branch. (In our example, we want to pull some-new-feature branch into release-2023.2.0.)

How to release a major/minor version or a patch

Before doing this, you should make sure that the release branch is based on main. If not, rebase it to main (or, in complex cases, merge main into the release branch). This should not be necessary if the procedure given below has been followed for prior releases.

1. Resolve any pull requests for the patch's release branch.
2. Check out and pull the release branch to your development environment.

git checkout release-2023.1.2

# Or you haven't yet fetched the release branch:
git checkout -b release-2023.1.2 origin/release-2023.1.2

# Make sure your copy of the branch is up to date:
git pull

3. Edit src/mavedb/__init__.py. Bump the version number to match the intended release version.
4. Commit this change and push to GitHub.

git add src/mavedb/__init__.py
git commit -m 'Bumped the version number.'
git push

5. Reset main to point to the head of the release branch. (We are assuming that no other changes have been made to main that are not included in the release branch's history! If they have, go back and rebase the release branch first or merge main into it.)

git checkout main
git pull
git reset --hard release-2023.1.2
git push

6. On GitHub, create a new release.

• Name the release vYEAR.MINOR.MICRO, e.g. v2023.1.2.
• Set a new tag, with the same text as the release name, e.g. v2023.1.2. The tag will be applied to the latest commit of main when GitHub creates the release.
• Enter a description for the release. This might look like

**Release notes**

- Description of change 1
- Description of change 2
- Etc.

7. Release the application to production.
8. Publish the package to PyPi.

poetry publish --build

9. If this was a patch release, rebase the next major/minor release branch onto main. In complex cases, you may instead merge main into the next major/minor release branch.

# In our example, we have just released v2023.1.2 into main.
git rebase main release-2023.2.0
git push -f origin release-2023.2.0

10. On GitHub, delete the release branch you have just released. You can do this on GitHub's "branches" screen, where the branch should appear as merged and ready to delete.
11. In your local environment, switch to the main branch and optionally delete obsolete branches:

git checkout main
git pull

# This is optional. It will remove the branch (origin/some-new-feature) which tracks a now-deleted remote branch.
git remote prune origin

12. In your local environment, delete the local release branch.

git branch --delete some-new-feature

13. Create a new major/minor release branch if this was a major/minor release, or a new patch release branch if this was a patch release.

git checkout -b release-2023.1.3
git push origin release-2023.1.3