Follow this document every time you are ready to release changes into production.
- Always work in
develop
branch, never in themain
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
fromdevelop
(with--no-ff
) (see below) - tag the new merge commit in
main
- push changes and tags to Github
- consult
- 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.
- record the commit hash tag at the current HEAD of
- 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.
- Read https://semver.org/ for advice on how to update from the current version number
- Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes.
- For example, if the latest version is 1.3.0,
- changes that cannot easily be rolled back should be numbered 2.0.0
- changes that can easily be rolled back should be numbered 1.4.0
- defect fixes only should be numbered 1.3.1.
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
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.
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?
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.