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.

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 of CHANGELOG.md file.
Follow Release Procedure.
Consider manual steps to do before the release: manual deployment steps.
Follow Deployment Procedure.
Consider manual steps to do after the release: manual deployment steps.
Write user-friendly release notes and share them in release announcements on Slack - use #core-team for admin-only changes and #general for community-facing changes.

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) using cd command.
Make sure you have configured repositories:
- origin for carpentries/amy repo on GitHub
For example, this is the correct configuration:
```
$ git remote -v
origin  git@github.com:carpentries/amy.git (fetch)
origin  git@github.com:carpentries/amy.git (push)
```

Make sure your local develop and main branches 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 HEAD of 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 develop to release/vX.Y.Z as required to fix bugs. Skip any commits that add new features.
Merge release/vX.Y.Z into main branch (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 `pyproject.toml` and `package.json`
$ # use non-dev version string, e.g. `"v3.3.0"`
$ git add pyproject.toml 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.
Complete any Manual Deployment Steps noted for before deployment of this release.
Push main and the new tag everywhere:
```
$ git push origin main --tags
```
Note: this will trigger deployment to production environment. A manual confirmation is required in Github Actions UI to proceed.
Complete any Manual Deployment Steps noted for after deployment of this release.

Bump version on develop (dev version corresponding to the milestone):

$ git checkout develop
$ # manually edit version in `pyproject.toml` and `package.json`
$ # use dev version string, e.g. `"v3.4.0-dev"`
$ git add pyproject.toml 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
```
Note: this will trigger deployment to testing environment.