Merge pull request #24 from ajschofield/docs/dev-notes

pr: developer notes changes

1 files changed, 81 insertions, 36 deletions

diff --git a/DEVNOTES.md b/DEVNOTES.md
index 00f06ec..00b4ddd 100644
--- a/DEVNOTES.md
+++ b/DEVNOTES.md
@@ -1,55 +1,100 @@
 # Workflow
 
-## Commits
+## References
 
-### Make small and focused commits
-- Please avoid mixing unrelated changes in a single commit
-- Commit at regular points to revert changes easily if needed
+https://nvie.com/posts/a-successful-git-branching-model/ \
+https://learn.microsoft.com/en-us/azure/devops/repos/git/merging-with-squash?view=azure-devops
 
-### Write clear commit messages
-- Limit subject line to 50 characters
-- Provide more detailed explainations in the commit body (if required)
-- Use the imperative mood in the subject line (e.g. 'add' instead of 'added')
 
-```
-$ ~ git commit
-```
+## Branching
+
+*Based off GitFlow but slightly modified*
+
+- There are two main branches
+  - `main` - production-ready code
+  - `development` - integration branch for features
+  - `staging` - represents the current staging state
+- In addition, there are additional branches 
+  - Feature branches - for new features and non-urgent bugfixes
+  - Hotfix branches - probably won't be used but for critical bugs in production (this is what testing should prevent)
+  - Release branches - for preparation of production releases
+
+- Feature branches - e.g. `feature/short-description`
+- Bugfix branches - e.g. `bugfix/short-description`
+- Hotfix branches - e.g. `hotfix/short-description`
+- Release branches - e.g. `release/vX.Y.Z`
 
+### Examples
 ```
-[Type]: [Short Subject]
----[Blank Line]---
-[Body, Limit to 72 Characters]
+feature/add-data-extractor
+bugfix/fix-s3-upload-error
+hotfix/security-patch
+release/v1.0.0
 ```
-- Types: feat, fix, docs, style, refactor, test, chore, ci, perf
-  - See [here](https://eagerworks.com/blog/conventional-commits) for more information
 
-## Branches
+## Environments
+
+1. Development - where active development and initial testing occur
+2. Staging - for integration testing and final checks before production
+3. Production - live and stable environment
+
+## Deployment
+
+1. `main` - represents the current production state
+2. `develop` - represents the integration branch for features and non-urgent fixes
+3. `staging` - represents the current staging state
+
+## Staging Flow
+
+1. Create feature branches from `develop` & merge completed features back into `develop`
+2. When the `develop` branch is ready for testing, create a `staging` branch from `develop`
+3. Deploy the `staging` branch to the staging environment and perform our unit-tests
+4. If staging tests pass, create a `release/vX.Y.Z` branch from `staging`
+5. Make any final adjustments in the `release/vX.Y.Z` branch
+6. Once we have approved the changes in the `release/vX.Y.Z` branch, merge into `main`
+7. Tag the release in `main`
 
-### Naming Conventions
+### Notes
 
-- Use lowercase with hyphens
-- Include type and change with small description
+- No new features should be included in the release branches and any new features should be merged into `develop` for the next release cycle
 
+## Commit Messages
+
+Please follow the conventional commits specification:
+  
 ```
-[type]/[brief-description] :: e.g. feature/api
+<type>[optional scope]: <description>
+
+<optional body>
+
+[optional footer(s)]
 ```
-### Base Branch
 
-- Branch from `develop` for features and non-urgent fixes
-- Branch off from `main` for urgent changes (project deadline) - this should be rarely used
+### Types
+- feat: new features
+- fix: bugfixes
+- docs: documentation-only changes
+- style: changes that do not affect the meaning of the code
+- refactor: code changes that neither fix bugs nor adds features
+- perf: code changes that improve performance
+- test: adding tests or correcting existing tests
+- chore: changes to build process or tools/libraries (probably not needed)
+- infra: changes to infrastructure configuration (e.g. Terraform)
+
+### Examples
+```
+feat(extract): add automatic scheduling for data ingestion
+docs: update README with project setup instructions
+```
 
-### Keep branches updated
+Configuration files for things such as Terraform isn't native to Conventional Commits, but we can add our own:
 
-- Regularly merge and also delete branches when stale
+```
+infra(tf): update S3 bucket policy
+```
 
-## PRs
+If the Terraform change involves a fix, you may combine `fix` and `infra`:
 
-1. Create a pull request for each feature or fix (link to related issues)
-2. Write a clear description which...
-   1. Summarises the changes
-   2. Explains the reasoning behind the changes
-   3. Lists any areas of concerns (i.e. breaking changes)
-3. Keep PRs focused - split changes into multiple PRs if needed
-4. Assign someone to review
-5. Merge ONLY after team approval - resolve conflicts & ensure CI checks pass
-6. Use [squash and merge](https://learn.microsoft.com/en-us/azure/devops/repos/git/merging-with-squash?view=azure-devops) when needed to keep main branch history clean
\ No newline at end of file
+```
+fix(infra): ...
+```