Release Procedure.md

Release Procedure

Follow this document every time you are ready to release changes into production.

Overview

• Always work in develop branch, never in the main branch.
• When all changes are ready for a release on your development machine:
  • consult CHANGELOG.md and choose the new version number (see below)
  • merge into main from develop (with --no-ff) (see below)
  • tag the new merge commit in main
  • push changes and tags to Github
• On the production server:
  • record the commit hash tag at the current HEAD of main
  • pull the main branch to load the new release from Github
  • check that the HEAD of main has the correct version label or commit hash
  • backup the database
  • notify the client that the site is about to be updated
  • recursively copy from the git repo to the live code folders
  • test the live site.
• If necessary to rollback,
  • checkout the previous commit point to roll back the git repo
  • recursively copy from the git repo to the live code folders
  • test the live site - has it reverted correctly?

These steps are described in detail below.

Choose a new version number

• Read https://semver.org/ for advice on how to update from the current version number
• Given a version number MAJOR.MINOR.PATCH, increment the:
  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards compatible manner, and
  3. PATCH version when you make backwards compatible bug fixes.
• For example, if the latest version is 1.3.0,
  1. changes that cannot easily be rolled back should be numbered 2.0.0
  2. changes that can easily be rolled back should be numbered 1.4.0
  3. defect fixes only should be numbered 1.3.1.

Merge from develop into main branch

On your development repo, ensure that all changes in develop have been committed and pushed.

Merge develop into your local main branch and tag with the version number:

git checkout main
git pull -v
git merge --no-ff --no-edit develop
git tag -a v1.3.1 -m "Release 1.3.1"
# Now push these changes to Github:
git push
git push origin v1.3.1

TODO finish this document...

On the production server

Prepare the production server before loading any changes:

• record the commit hash and tag at the current HEAD of main
• backup the database
• backup any file stores, as required

Negotiate and plan for the site outage during the update:

• notify the client (backoffice users) that the site is about to be updated
• consider impact on current visitors to the site

Prepare to go live with the latest version:

• pull the main branch to load the new release from Github
• check that the HEAD of main has the correct version label or commit hash

Go live with the latest version:

• recursively copy from the git repo to the live code folders
  • this could be scripted (best practice)
• test the live site. Rollback if necessary. Notify the client as appropriate.

Rollback

If necessary to rollback:

• rewind the git repository to the initial state recorded above
• recursively copy from the git repo to the live code folders
• test the live site - has it reverted correctly?

To rewind the git repository

Using the commit hash or tag as noted during preparation:

git checkout <commit>

where <commit> is a commit hash or release tag.

See https://git-scm.com/docs/git-checkout for details.