From fb4aecf6a2ae8191c9a3ecac58ba5fb13d898b8b Mon Sep 17 00:00:00 2001 From: spwoodcock Date: Fri, 12 Jul 2024 11:02:11 +0100 Subject: [PATCH] docs: add deployment flow to dev practices doc --- docs/dev-practices.md | 76 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 75 insertions(+), 1 deletion(-) diff --git a/docs/dev-practices.md b/docs/dev-practices.md index cabb68c..d256567 100644 --- a/docs/dev-practices.md +++ b/docs/dev-practices.md @@ -54,7 +54,7 @@ software development practices. - Discussions can also be used on our Git tracker for more general user input or feedback. - Most often this will be bug reports, which should generally be high priority for - the next release (or a hotfix to production if `critical` priority). + the next release (or a [hotfix](#hotfixes) to production if `critical` priority). - The PO / Tech Lead should triage tasks, assign priorities, and group into milestones or releases. @@ -279,3 +279,77 @@ Example: - Higher level info on bugs fixed, new features added, things improved. - Add screenshots throughout. + +### Deployment Flow + +These stages go in order, from local development, through to production deployment. + +#### Local Development + +- Devs develop features on their local instance. +- Use `docker-compose.yml` setup for testing. +- Once feature and testing complete, make a PR to the `dev` branch. + +#### Development Deployment + +- Once a PR is approved, it is merged to `dev`. +- This triggers a workflow to automatically deploy the code changes on the dev server. +- The purpose of this stage is for: + - Fast CI, i.e. the developer sees their code in action quickly. + - Easy QA tests by the project manager on the dev server. + +#### Staging Deployment + +- The purpose of this step is to regularly release versions of the software that + power users (and the project owners) can test. + - Anyone who doesn't mind occasional breakage is welcome to use this server publicly. +- At a set interval (approx bi-weekly), the updates made on `dev` are merged into + `staging` for feature stabilisation. + - This can be done via PR, although sometimes there may be merge conflicts to resolve. + - Alternatively, the branch can be reset to the latest `dev` and built upon: + `git reset --hard origin/dev` +- Once merged, the functionality is thoroughly tested and patched (if required). + - Patches can either me made on `dev` and merged into `staging`. + - Or be made directly to `staging` if there branches have diverged significantly. +- Once approved, the `staging` branch auto-deploys to the staging server. + +#### Production Deployment + +- The staging server instance is thoroughly tested by the product owner, and + bug reports filed. +- The release is hardened into longer interval (approx bi-monthly) production releases. +- A PR is made from `staging` to `main` branch. +- Once approved and the code merged, a Github **release** is made. +- A release is available on Github, including all relevant release notes for + what has been updated. +- The **release** will trigger the workflow to deploy to the production server. + +##### Hotfixes + +- If an issue is found after a production release is made, a hotfix can be used to + patch the production code. +- There are two methods to do this: + - If the `dev` and `main` branches have diverged significantly, the hotfix can + be made as a PR directly to `main`, then reconciled later with `dev`. + - Otherwise, the fix can be made as a PR to `dev`, then `cherry-picked` upstream + through `staging` then to `main`. + +#### Other: Feature Demo Releases + +- A feature demo release is a throwaway instance of the tool with a particular purpose. +- Functionality is developed here for various reasons: + - Specific updates for a single project that won't be used elsewhere. + - Very fast updating of the server, without interfering with the typical release + flow. +- The key point is that these branch instances are **single use** and will be + **shut down** once the project has ended. +- The easiest approach is probably to: + - Create and login to a server. + - Clone the repo and checkout to the feature branch `feature-demo/some-feature`. + - Run the commands to build and run the tool. +- Alternatively, a workflow can be made to auto-deploy: + - Triggering on a branch naming convention: `feature-demo/some-feature`. + - The user will have to enter an SSH key into the Gitlab secrets. + - The workflow will deploy to the server remotely when the branch is pushed to. + - This approach is less preferred, as the user requires write access to the + Github repo.