Procedures¶
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 v3.15
or v3.15.0
.
Feature development¶
Developers are encouraged to use feature flags for development of new features in case they would have to be released to production in dark.
On the End of Each Milestone¶
-
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".
Release Procedure¶
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.
Deployment procedure using Ansible¶
Moved to relevant repository README.md
.