AMY follows Semantic Versioning when possible; however, since this is a web application and not a library, we have come up with these rules to bumping versions:
- hotfix or a fix release: bump patch version
- normal release: bump minor version
- major changes (e.g. big project gets merged): bump major version.
In future, once CI/CD is implemented, we may consider switching to commitizen which will help with generating changelogs and bumping versions accordingly.
Milestone name should indicate the release version. For example, if next release is
v3.15.0
, then the milestone collecting issues and PRs should be named v3.15
or v3.15.0
.
Developers are encouraged to use feature flags for development of new features in case they would have to be released to production in dark.
-
Close milestone using GitHub UI.
-
Run
python docs/generate_changelog.py MILESTONE_NAME
to generate changelog for given release; paste command's output to the top ofCHANGELOG.md
file. -
Follow Release Procedure.
-
Follow Deployment Procedure.
-
Write to amy@lists.carpentries.org mailing list. The suggested subject of the new thread is "[AMY] New release v2.X.Y".
We assume that you want to release AMY v2.X.Y.
Execute the following commands on your local machine, not production.
-
Move to AMY root directory (the one with
manage.py
file) usingcd
command. -
Make sure you have configured repositories:
origin
for your repository on GitHubupstream
forcarpentries/amy
repo on GitHub
For example, this is the correct configuration for
chrismedrela
:$ git remote -v origin git@github.com:chrismedrela/amy.git (fetch) origin git@github.com:chrismedrela/amy.git (push) upstream git@github.com:carpentries/amy.git (fetch) upstream git@github.com:carpentries/amy.git (push)
-
Make sure your local
develop
andmain
branches are up to date:$ git checkout develop $ git pull upstream develop $ git push origin develop $ git checkout main $ git pull upstream main $ git push origin main
Pushes to your
origin
remote are optional. -
Merge
develop
intomain
branch (be careful, as there are sometimes conflicts that need to be manually resolved):$ git checkout main $ git merge --no-ff develop
-
Bump version on
main
(non-dev version corresponding to the milestone):$ # manually edit version in `amy/__init__.py` and `package.json` $ # use non-dev version string, e.g. `"v3.3.0"` $ git add amy/__init__.py package.json $ git commit -m "Bumping version to vX.Y.0"
-
Just to be safe, run tests:
$ make test
-
Tag a release.
$ git tag -a "vX.Y.0" -s -m "AMY release vX.Y.0"
Omit
-s
flag if you cannot create signed tags. See Git documentation for more info about signed tags. -
Push
main
and the new tag everywhere:$ git push origin main --tags $ git push upstream main --tags
-
Bump version on
develop
(dev version corresponding to the milestone):$ git checkout develop $ # manually edit version in `amy/__init__.py` and `package.json` $ # use dev version string, e.g. `"v3.4.0-dev"` $ git add amy/__init__.py package.json $ git commit -m "Bumping version to vX.Y.0-dev"
This step is only needed if next development cycle begins (ie. no hotfix release was done).
-
And push it everywhere:
$ git push upstream develop $ git push origin develop
Note: it is acceptable to use a release branch as a base for release. This is very
useful for example if a bugfix release must be created, but a feature from upcoming
minor/major release has already been merged to develop
. This is also useful when multiple
features are worked on simultaneously.
What are the changes:
- Code is branched out from
develop
(not necessarily theHEAD
) torelease/vX.Y.Z
branch. - Optional cherry-picks follow from
develop
torelease/vX.Y.Z
. - Release branch is merged to
main
with--no-ff
option.
Moved to relevant repository README.md
.