Specifying a milestone (version)¶
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
On the End of Each Milestone¶
Close milestone using GitHub UI.
python docs/generate_changelog.py MILESTONE_NAMEto generate changelog for given release; paste command's output to the top of
Follow Release Procedure.
Follow Deployment Procedure.
Write user-friendly release notes and share them in release announcements on Slack - use
#core-teamfor admin-only changes and
#generalfor community-facing changes.
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
Make sure you have configured repositories:
carpentries/amyrepo on GitHub
For example, this is the correct configuration:
$ git remote -v origin firstname.lastname@example.org:carpentries/amy.git (fetch) origin email@example.com:carpentries/amy.git (push)
Make sure your local
mainbranches are up to date:
$ git checkout develop $ git pull origin develop $ git checkout main $ git pull origin main
Create a release branch
release/vX.Y.Z. Major/minor release branches should be based on the
develop, but bugfix releases may be based on older commits, such as the previous release branch or
main, to avoid including features intended for the next major/minor release. For more details on managing branches, see https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow.
Bugfix releases only: Cherry-pick commits from
release/vX.Y.Zas required to fix bugs. Skip any commits that add new features.
mainbranch (be careful, as there are sometimes conflicts that need to be manually resolved):
$ git checkout main $ git merge --no-ff release/vX.Y.Z
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"
-sflag if you cannot create signed tags. See Git documentation for more info about signed tags.
mainand the new tag everywhere:
$ git push origin 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 origin develop
Deployment procedure using Ansible¶
Back up the database through the AWS console (RDS > Databases > (cluster name) > Actions (top right) > Take snapshot). Use the naming scheme
vA-B-C-YYYY-MM-DDfor version A.B.C (the version before the one that will be deployed) and date YYYY-MM-DD, e.g.
Check for pending maintenance through the AWS console (RDS > Databases > (cluster name) > Maintenance and Backups (below Summary section)) and complete it if needed.
Complete any Manual Deployment Steps noted for before deployment of this release.
Run the Ansible deployment as described in the relevant repository
Complete any Manual Deployment Steps noted for after deployment of this release.