diff --git a/README.md b/README.md index 73c2c302d..b9aa9210f 100644 --- a/README.md +++ b/README.md @@ -12,4 +12,5 @@ ## General Documentation Documentation below can be applied to all the aforementioned projects with small changes applied depending on the project. - [NodeJS Profiling](./documentation/NODEJS_PROFILING.md) -- [Conventions for Developers](./documentation/CONVENTIONS.md) \ No newline at end of file +- [Conventions for Developers](./documentation/CONVENTIONS.md) +- [Release and Deployment Process](./documentation/RELEASE_AND_DEPLOYMENT.md) \ No newline at end of file diff --git a/documentation/RELEASE_AND_DEPLOYMENT.md b/documentation/RELEASE_AND_DEPLOYMENT.md new file mode 100644 index 000000000..af42c9a8d --- /dev/null +++ b/documentation/RELEASE_AND_DEPLOYMENT.md @@ -0,0 +1,101 @@ +# Release and Deployment Guide + +## Key + +- ``: one of `bkp`, `qcg`, `cog`, `ilg` +- ``: version number in the format `X.Y.Z` (e.g., `1.15.0`) +- `PR`: Pull Request +- `GH CLI`: GitHub Command Line Interface + +## Release + +### 1. Prepare the Jira Release + +1. Go to Release section of your Jira project +2. Review all the tickets (on the "issues in version" tab) assigned to the release +3. Move any ticket not in "Ready for release" or "Closed" to the next release and update its `Fix Version` field. Use the bulk editor, accessible via the issue navigator, to do this efficiently. +4. Move leftover tickets from "Ready for release" to "Closed" +5. Add any parent tasks that have subtasks in the release but are not yet included + +> [!TIP] +> When using the bulk editor, uncheck the option to send email notifications to avoid spamming team members with multiple emails about status changes. +> You can also use the bulk editor to change the `Status` field. +> You can also use the bulk editor to change the `Fix Version` field. + +### 2. Validate the Release Locally + +1. Checkout the default (`dev/main`) branch of the Github repository that contains the GUI application. Make sure to pull all latest changes +2. Verify that all changes related to the release tickets are present +3. Validate functionality: + - No errors in the browser console + - No errors in the server logs + - All common use cases work as expected + +### 3. Create Release Branch and PR + +1. Create a release branch: `git checkout -b release//` (e.g., `release/bkp/1.15.0`) +2. Update the version number: `npm version patch/minor/major` +3. Check and fix known vulnerabilities: `npm audit fix` +4. Stage and commit the changes +5. Push the branch to the remote repository +6. Open a PR for the release branch, add the `release` label and assign the PR to yourself +7. Once tests have passed and one approval has been received, merge the PR + +### 4. Create the GitHub Release + +1. Draft a new GitHub release. + - Title of the release must match exactly the Jira release name, (e.g., `@aliceo2/bookkeeping@1.15.0`, **NO WHITESPACE ALLOWED**) + - Tag must be the same as the title + - Target must be the default branch (e.g., `dev` or `main`) +2. Copy the html version of the release notes from Jira and edit them: + - Remove the title + - Replace H2 headings with H4 + - New features should always appear at the top + - Group subtasks under their parent tasks (even if parent is not closed) + - Developer text should be rewritten to user-friendly text +3. Set as latest release +4. Create the release + +> [!CAUTION] +> Github workflow covers specific logic based on the release name. +> If name is wrong the Github action will fail. To fix this: delete the release AND the tag and start over. + +### 5. GitHub Release Workflow (Automated apart from clicking "Create release" in Jira) + +When you click "Create release" in Github, GitHub Actions will automatically: + +1. Publish the NPM module to the ALICE O2 NPM registry. This is for people installing outside of CERN +2. Install production dependencies and publish the dedicated CERN release to our private CERN NPM registry called s3 (cern.s3.registry - linux training section) +3. Create the Tarball with `NPM pack` and attach it to the GitHub release's assets via the GH CLI. (This can be used to manually install the release if needed) +4. If at this point all GitHub Actions are green the release is done, the GitHub release package is created +5. Click "Release" in Jira to finalise the release, use today's date and click confirm. + +### Release Diagram + +![Release Diagram](./images/release_diagram.svg) + +--- + +## Deployment + +### 1. Update System Configuration and Create PR + +1. To deploy a release the version number/s must be changed in [system configuration repository](https://gitlab.cern.ch/AliceO2Group/system-configuration/-/blob/dev/ansible/roles/basevars/vars/main.yml?ref_type=heads) +2. Commit and create a new branch with name `gui--` **NO SLASH** in name allowed for the branch name as it will cause the flp-setup-tool to fail +3. Create the PR titled `[gui//]` (e.g., `[gui/bkp/cog/1.15.0]`) +4. Copy the release notes html from the GitHub release into the PR, add yourself as the creator and O2-FLP Group Leader as reviewer +5. Check if any existing pipelines are already running (`Build` tab then `Pipelines` in GitLab): + 1. If there ARE, do not start a pipeline and trust that the O2-FLP group leader will take care of the train of PRs + 2. If there ARE NOT then start the default pipeline FOR YOUR BRANCH, wait for the page to fully load and you don't need to change any pipeline parameters. Go back to the Gitlab release PR and set it to auto-merge for when pipeline will be successful + 3. Alert the O2-FLP group leader that release has been done and whether or not a new pipeline was started and if auto-merge is set +6. Once the release PR is merged there is nothing else left to be done and when there is a slot free the deployment will happen + +### 2. Post-Deployment Verification + +1. Once the SRC (Software Release Coordinator) of FLP gives the green light for software verification, ensure the GUI in specified environment runs as expected by: + 1. Checking the GUI version has been updated + 2. Briefly testing that the changes are working as expected + +### Deployment Diagram + +![Deployment Diagram](./images/deployment_diagram.svg) \ No newline at end of file diff --git a/documentation/images/deployment_diagram.drawio b/documentation/images/deployment_diagram.drawio new file mode 100644 index 000000000..92bf1be64 --- /dev/null +++ b/documentation/images/deployment_diagram.drawio @@ -0,0 +1,91 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/images/deployment_diagram.svg b/documentation/images/deployment_diagram.svg new file mode 100644 index 000000000..bdbf8f7ca --- /dev/null +++ b/documentation/images/deployment_diagram.svg @@ -0,0 +1,4 @@ + + + +
Developer
Developer
GitLab
GitLab
GitLab CI/CD
GitLab CI/CD
P2 / Operations
P2 / Operations
Update System Configuration versions
Update System Configuration versions
Fill in branch name and create PR
Fill in branch name and create PR
Add release notes, yourself as creator and O2-FLP Group Leader as reviewer. 
Add release notes, yourself as creator and O2-...
Sync with people at P2
Sync with people at P2
Once done
Once done
Start deployment pipeline
Start deployment pipeline
Go to production application, check version number and new features added.
Go to production application, check version nu...
once succesful
once succesful
Start integration testing pipeline
Start integration testing pipeline
Check that no integration tests are running
Check that no integration tests are running
START
START
FINISH
FINISH \ No newline at end of file diff --git a/documentation/images/release_diagram.drawio b/documentation/images/release_diagram.drawio new file mode 100644 index 000000000..842b2f1dc --- /dev/null +++ b/documentation/images/release_diagram.drawio @@ -0,0 +1,115 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/images/release_diagram.svg b/documentation/images/release_diagram.svg new file mode 100644 index 000000000..bafc6c61a --- /dev/null +++ b/documentation/images/release_diagram.svg @@ -0,0 +1,4 @@ + + + +
Developer
Developer
Jira
Jira
GitHub
GitHub
GitHub Actions
GitHub Actions
Artifacts
Artifacts
Go to release section of Jira
Go to release section of Jira
Move tickets that are not ready to next release
Move tickets that are not ready to next release
Verify changes locally
Verify changes locally
Create release branch
Create release branch
Open PR
Open PR
Create release
Create release
Build and publlsh public npm module
Build and publlsh public npm module
Create production tarball and upload
Create production tarball and upload
Github Release Asset
Github Release Asset
Mark release as done
Mark release as done
NPM public registry package
NPM public registry package
CERN S3
CERN S3
Tarball
Tarball
npm version and audit
npm version and audit
START
START
FINISH
FINISH \ No newline at end of file