Update deployment process docs vol 5622

docs/pre-release-process.md

@@ -0,0 +1,89 @@
+# VOL-APP Pre-Release Process
+
+## Overview
+
+This document outlines the process for creating and managing pre-releases of VOL-APP, allowing for thorough testing before formal releases.
+
+:::warning
+
+It is important that no other merges to main happen during the pre-release process. This ensures that the pre-release branch can be merged back into main without introducing new changes.
+:::
+
+## Process Steps
+
+### 1. Creating a Pre-Release Branch
+
+1. Start from either:
+    - The main branch for standard releases
+    - A feature branch requiring specific testing
+2. Create the pre-release branch using the helper script:
+    ```bash
+    ./create-prerelease.sh <version>
+    # Example: ./create-prerelease.sh 1.1.0
+    ```
+    This will:
+    - Create the `prerelease` branch
+    - Copy CHANGELOG.md to CHANGELOG-PRERELEASE.md
+    - Create the Release-As commit for the RC1 version
+
+### 2. Managing the Pre-Release
+
+When Release-Please creates the PR:
+
+1. Review the PR contents
+2. Merge the PR to create version `v<version>-rc1` (e.g., v1.1.0-rc1)
+3. This triggers the CD pipeline which will:
+    - Deploy through dev, int, and prep environments
+    - Run all automated tests
+    - Stop before production - ready for manual acceptance testing on prep
+
+### 3. Making Changes During Testing
+
+If issues are found during testing:
+
+1. Create a fix branch from prerelease:
+    ```bash
+    git checkout prerelease
+    git checkout -b fix/issue-description
+    ```
+2. Make changes using conventional commits
+3. Create and merge a PR back to prerelease
+4. Release-Please will automatically create a PR for the next RC version (e.g., rc2)
+5. Merge the Release-Please PR to deploy the new RC version
+
+### 4. Pre-Release Sign-Off/Approval
+
+Testing a pre-release is complete when:
+
+1. All automated tests have passed
+2. Stakeholders sign-off on their manual acceptance testing
+
+### 5. Synchronising with Main
+
+If no issues arise during the testing of the first release-candidate (e.g., `v1.1.0-rc1`), and the code on `prerelease` is effectively identical to `main` except for version/changelog commits:
+
+1. Confirm that **no additional commits** were made to `main` after you created the `prerelease` branch.
+2. Verify via `git diff main prerelease` (or a GitHub comparison) that the only differences are those Release-Please made to create the RC version.
+3. If there are **no other changes**, then no sync PR is needed—simply merge the existing Release-Please PR for the final version (e.g., `v1.1.0`) into `main`, which will trigger the normal release pipeline.
+
+If any changes have been required, the pre-release branch must be merged into main.
+
+1. Create a PR to merge prerelease into main
+2. Use a conventional commit message summarising all changes:
+
+    ```
+    feat: merge tested prerelease features
+
+    Merges pre-release changes tested in v1.1.0-rc1 through rc3:
+    - Change 1
+    - Change 2
+    ```
+
+3. Review the PR carefully to ensure:
+    - All needed changes are included
+    - No unintended changes are present
+
+### 6. Proceed to full Release Process
+
+The main branch is now ready for the full release process, documented in the [VOL-APP Release Process](release-process.md).
+Nothing should be merged to main between the pre-release and the full release.

docs/release-process.md

@@ -0,0 +1,147 @@
+# VOL-APP Release Documentation
+
+This document explains two distinct release approaches for **vol-app**:
+
+1. **Simple Release Cycle**  
+   For small or routine changes we are confident can be properly tested in the `dev` and `int` nonprod environments.
+
+2. **Pre-Release Cycle**  
+    For larger or higher-risk changes requiring validation in prep environment, or access to something only available in prod acct.
+   If it is expected that we might need to make changes in response to testing, pre-release is the way to go.
+
+Both workflows rely on Release-Please in simple mode. The difference lies in whether you do a straightforward merge to main (simple release) or create a dedicated prerelease branch for iterative RC testing in prep.
+
+---
+
+## 1. Standard Release Cycle
+
+### Recommended when:
+
+-   Routine changes that do not require special pre-production `prep` environment testing before merging to main.
+-   Testing in dev and int provides enough confidence and we dont expect there may be multiple changes required as a result of testing.
+
+### Prerequisites
+
+1. All required changes (including any from olcs-etl) are already merged into main.
+2. A Release-Please Pull Request (PR) is open for the next version (e.g., v5.20.1).
+
+### Standard Release Steps
+
+1. Merge the pending Release-Please PR into main.
+
+    - This compiles conventional commit messages into the changelog and triggers a new semver release (e.g. v5.20.1).
+    - The CD pipeline will detect the “release” context and proceed in release mode.
+
+2. CD Pipeline Deploys to Nonprod
+
+    - Builds, tests, and deploys to dev, then int. Smoke tests run in dev.
+    - Smoke tests and regression tests run in int.
+
+3. Deployment to prep (Production Account)
+
+    - Pipeline then deploys to the pre-production (prep) environment.
+    - Further smoke tests are run in prep.
+
+4. Manual Approval for Production
+
+    - Pipeline pauses before deploying to prod.
+    - An authorised reviewer approves in GitHub, then the pipeline proceeds.
+    - Terraform, migrations, and final deployment to prod happen. No automated tests run on prod.
+
+5. Release Completed
+    - The final semver release (v5.20.1) is now live.
+    - Future changes will form a new release.
+
+---
+
+## 2. Pre-Release Cycle
+
+:::warning
+
+It is important that no other merges to main happen during the pre-release process. This ensures that the pre-release branch can be merged back into main without introducing new changes.
+:::
+
+### Why Use a Pre-Release?
+
+Sometimes changes are large or risky or need the PROD acct.
+
+-   Work needs final testing or acceptance in prep (prod account) with the data/resources only available in that environment.
+-   Confidence is lower that all issues have been caught in dev/int, and we want to avoid multiple releases and version bumps.
+-   For changes such as the Laminas 3 migration, or other changes which will likely yield lots of bugs throughout testing cycle.
+
+### Pre-Release Cycle Steps
+
+1. Decide to Create a Pre-Release
+
+    - For the reasons above, we want to promote changes to prep, and have a mechanism to iterate on them before merging to main for a full release.
+
+2. Create prerelease Branch
+
+    Example:
+
+    ```bash
+     git checkout main
+     ./create-prerelease.sh 5.21.0
+    ```
+
+    This script:
+
+    - Creates a new prerelease branch.
+    - Copies CHANGELOG.md -> CHANGELOG-PRERELEASE.md.
+    - Commits Release-As: v5.21.0-rc1.
+
+3. Open and Merge the Release-Please PR for RC1
+
+    - Release-Please sees the new branch, creates a PR for v5.21.0-rc1.
+    - Merge that PR into prerelease.
+    - CD pipeline runs in “release” mode for a pre-release, deploying to dev, int, prep.
+    - Does not go to prod. The pipeline config only allows deployment of non-rc semver version numbers.
+
+4. Iterate on Additional RCs
+
+    - If issues are found, create fix branches from prerelease, then merge back in.
+    - Release-Please generates the next RC (v5.21.2.0-rc2, etc.).
+    - Each new RC redeploys to dev/int/prep.
+
+5. Testing & Sign-Off
+
+    - Perform all required tests in prep.
+    - When stable, finalise by merging prerelease into main.
+
+6. Merge prerelease into main
+
+    - Create a PR from prerelease to main, summarise changes in a conventional commit (e.g., feat: merge tested prerelease).
+    - After review, merge to main. Now prerelease changes are in main.
+
+7. Perform the Final Release
+
+    - Release-Please will open a new PR for the official v5.21.0 release.
+    - Merge that PR to trigger the pipeline to prod, as per a standard release above.
+
+8. Cleanup (Optional)
+    - Remove the prerelease branch or tags if needed (e.g., ./cleanup-prerelease.sh).
+
+---
+
+## Roles and Responsibilities
+
+### vol-app developers / platform engineers
+
+-   Modify app code, Terraform, Dockerfiles, etc., to add features or fix bugs
+-   Merge the Release-Please PRs for standard releases
+-   Create and iterate on the `prerelease` branch when needed, merging the final result into `main`
+
+### vol-app QAs
+
+-   Manage and monitor automated tests run by the pipeline
+-   Perform additional manual testing in the relevant environments
+
+### DVSA staff
+
+-   Perform UAT in `prep`
+-   Prepare acceptance reports or any relevant validation
+
+### TSS staff
+
+-   Verify that testing and UAT are complete
+-   Approve progression to `prod` as authorised reviewers, if satisfied