From f3b45991d7ea6465bede1a630254b347ab5c3f59 Mon Sep 17 00:00:00 2001
From: Jasper H <50981003+Houwie7000@users.noreply.github.com>
Date: Mon, 15 Dec 2025 15:57:08 +0100
Subject: [PATCH 1/6] Create RELEASEANDDEPLOYMENT.md
---
documentation/RELEASEANDDEPLOYMENT.md | 70 +++++++++++++++++++++++++++
1 file changed, 70 insertions(+)
create mode 100644 documentation/RELEASEANDDEPLOYMENT.md
diff --git a/documentation/RELEASEANDDEPLOYMENT.md b/documentation/RELEASEANDDEPLOYMENT.md
new file mode 100644
index 000000000..10ee5827b
--- /dev/null
+++ b/documentation/RELEASEANDDEPLOYMENT.md
@@ -0,0 +1,70 @@
+# Release
+
+Go to release section of Jira.
+
+Look at all the tickets assigned to the release. Moves ones that aren't "Ready for release"/"Closed" to the next release and change their "Fix Version" field to the next one.
+
+On your local machine checkout the main branch of the Github repository that contains the GUI application.
+
+Check the tickets' changes are present, that there are no errors in the browser or server logs and that all the normal usecases work as expected.
+
+
+
+Run `npm version patch/minor/major`.
+
+To check and fix vulnerabilities run: `npm audit fix`.
+
+Create the release branch `git checkout -b release/[name of GUI]/[version]`.
+
+Git add the changes. Push the branch.
+
+Raise the PR for it, add the release and associated GUI tag.
+
+Github create new release, title: Jira release name, exact. E.G. `@aliceo2/bookkeeping@1.15.0`
+
+Copy release notes from Jira, replace H2 with H4 and remove the title.
+
+Release notes developer text should be rewritten to user-friendly text, move subtasks to be grdouped under their parent task. Developer oriented text can be removed.
+
+Github workflow covers specific logic based on release name.
+
+If name is wrong the Github action will fail. To fix this: delete the release AND the tag and start over.
+
+When you click make release it will deploy the NPM module and other related actions see the workflow if want more detail.
+
+Github workflow publishes to npm
+Github workflow publishes to CERN S3
+
+This workflow takes care of the following steps:
+1. Publishes the NPM module to the ALICE O2 NPM registry. This is for people installing outside of CERN.
+2. Installs production dependencies and creates the dedicated CERN release publishes it to our private CERN NPM registry called s3 (cern.s3.registry - linux training section).
+3. Creates the Tarball with `NPM pack` and attaches it to the release's assets via the GH CLI. This can be used to manually install the release at P2 if needed.
+
+If at this point everything is green in GitHub actions the release is done, the GitHub release package is created.
+
+Click on the release button in Jira.
+
+Diagram:
+LINK
+
+---
+# Deployment
+
+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).
+
+Commit then and create a new branch with the name `[gui/${applicationNames}/${version}]`, **NO SLASH** in name allowed as it will cause the flp-setup-tool to fail.
+
+Copy the release notes into the PR from the GitHub release, add yourself as the creator and O2-FLP Group Leader as reviewer.
+
+Sync with the people at P2 from an accelerator and detector point of view: make sure no runs are going on and the detectors are in a safe state.
+
+If something is merged after a pipeline has started: then we need to rebase the PR and that pipeline will not be useful anymore. Any pipeline with 5 stages means someone has already triggered a deployment. Make the PR and assign it to Vasco and expect him to see the train of PRs to be merged so we won't trigger a new pipeline in this case we will wait for Vasco to do. Go back to PR and set it to auto-merge.
+
+Go to pipelines in GitLab and start the deployment pipeline, you don't need to change any pipeline paramters.
+
+Once the PR is merged the release there is nothing else left to be done and when there is a slot free the deployment will happen.
+
+When GUIs is green on pipeline can see release and can check version is new one in about of the application and play with the new features.
+
+Diagram:
+LINK
From 2059c5be9fba2bc8d66e3eb13c1cb48e5256aed6 Mon Sep 17 00:00:00 2001
From: Isaac Hill <71404865+isaachilly@users.noreply.github.com>
Date: Mon, 15 Dec 2025 16:09:38 +0100
Subject: [PATCH 2/6] Added diagrams and adjusted name of file
---
...EPLOYMENT.md => RELEASE_AND_DEPLOYMENT.md} | 5 +-
.../images/deployment_diagram.drawio | 91 ++++++++++++++
documentation/images/deployment_diagram.svg | 4 +
documentation/images/release_diagram.drawio | 115 ++++++++++++++++++
documentation/images/release_diagram.svg | 4 +
5 files changed, 217 insertions(+), 2 deletions(-)
rename documentation/{RELEASEANDDEPLOYMENT.md => RELEASE_AND_DEPLOYMENT.md} (97%)
create mode 100644 documentation/images/deployment_diagram.drawio
create mode 100644 documentation/images/deployment_diagram.svg
create mode 100644 documentation/images/release_diagram.drawio
create mode 100644 documentation/images/release_diagram.svg
diff --git a/documentation/RELEASEANDDEPLOYMENT.md b/documentation/RELEASE_AND_DEPLOYMENT.md
similarity index 97%
rename from documentation/RELEASEANDDEPLOYMENT.md
rename to documentation/RELEASE_AND_DEPLOYMENT.md
index 10ee5827b..be7630c76 100644
--- a/documentation/RELEASEANDDEPLOYMENT.md
+++ b/documentation/RELEASE_AND_DEPLOYMENT.md
@@ -45,7 +45,7 @@ If at this point everything is green in GitHub actions the release is done, the
Click on the release button in Jira.
Diagram:
-LINK
+
---
# Deployment
@@ -67,4 +67,5 @@ Once the PR is merged the release there is nothing else left to be done and when
When GUIs is green on pipeline can see release and can check version is new one in about of the application and play with the new features.
Diagram:
-LINK
+
+
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 @@
+
+
+
+
\ 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 @@
+
+
+
+
\ No newline at end of file
From a941b649b1989fd6346219f151ad1a239abb716e Mon Sep 17 00:00:00 2001
From: Isaac Hill <71404865+isaachilly@users.noreply.github.com>
Date: Mon, 15 Dec 2025 16:11:14 +0100
Subject: [PATCH 3/6] Added link from readme to release and deployment doc
---
README.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
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
From 0bdedaf870e1eca943d4b572f36e8fc0d283687d Mon Sep 17 00:00:00 2001
From: Isaac Hill <71404865+isaachilly@users.noreply.github.com>
Date: Mon, 15 Dec 2025 16:14:42 +0100
Subject: [PATCH 4/6] Update reviewer assignment in deployment instructions
---
documentation/RELEASE_AND_DEPLOYMENT.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/documentation/RELEASE_AND_DEPLOYMENT.md b/documentation/RELEASE_AND_DEPLOYMENT.md
index be7630c76..b7bc07751 100644
--- a/documentation/RELEASE_AND_DEPLOYMENT.md
+++ b/documentation/RELEASE_AND_DEPLOYMENT.md
@@ -58,7 +58,7 @@ Copy the release notes into the PR from the GitHub release, add yourself as the
Sync with the people at P2 from an accelerator and detector point of view: make sure no runs are going on and the detectors are in a safe state.
-If something is merged after a pipeline has started: then we need to rebase the PR and that pipeline will not be useful anymore. Any pipeline with 5 stages means someone has already triggered a deployment. Make the PR and assign it to Vasco and expect him to see the train of PRs to be merged so we won't trigger a new pipeline in this case we will wait for Vasco to do. Go back to PR and set it to auto-merge.
+If something is merged after a pipeline has started: then we need to rebase the PR and that pipeline will not be useful anymore. Any pipeline with 5 stages means someone has already triggered a deployment. Make the PR and assign it to O2 FLP Group Leader and expect him to see the train of PRs to be merged so we won't trigger a new pipeline in this case we will wait for O2 FLP Group Leader to do. Go back to PR and set it to auto-merge.
Go to pipelines in GitLab and start the deployment pipeline, you don't need to change any pipeline paramters.
From 0bf9f321b9e5a9c5f4eab78e835f90f8ae692c88 Mon Sep 17 00:00:00 2001
From: Isaac Hill <71404865+isaachilly@users.noreply.github.com>
Date: Mon, 15 Dec 2025 22:32:33 +0100
Subject: [PATCH 5/6] Restructured release and deployment docs
Added section headings, improved formatting, and clarified the workflow for both release and deployment processes.
---
documentation/RELEASE_AND_DEPLOYMENT.md | 121 ++++++++++++------------
1 file changed, 62 insertions(+), 59 deletions(-)
diff --git a/documentation/RELEASE_AND_DEPLOYMENT.md b/documentation/RELEASE_AND_DEPLOYMENT.md
index b7bc07751..3e2f09a30 100644
--- a/documentation/RELEASE_AND_DEPLOYMENT.md
+++ b/documentation/RELEASE_AND_DEPLOYMENT.md
@@ -1,71 +1,74 @@
# Release
-Go to release section of Jira.
-
-Look at all the tickets assigned to the release. Moves ones that aren't "Ready for release"/"Closed" to the next release and change their "Fix Version" field to the next one.
-
-On your local machine checkout the main branch of the Github repository that contains the GUI application.
-
-Check the tickets' changes are present, that there are no errors in the browser or server logs and that all the normal usecases work as expected.
-
-
-
-Run `npm version patch/minor/major`.
-
-To check and fix vulnerabilities run: `npm audit fix`.
-
-Create the release branch `git checkout -b release/[name of GUI]/[version]`.
-
-Git add the changes. Push the branch.
-
-Raise the PR for it, add the release and associated GUI tag.
-
-Github create new release, title: Jira release name, exact. E.G. `@aliceo2/bookkeeping@1.15.0`
-
-Copy release notes from Jira, replace H2 with H4 and remove the title.
-
-Release notes developer text should be rewritten to user-friendly text, move subtasks to be grdouped under their parent task. Developer oriented text can be removed.
-
-Github workflow covers specific logic based on release name.
-
-If name is wrong the Github action will fail. To fix this: delete the release AND the tag and start over.
-
-When you click make release it will deploy the NPM module and other related actions see the workflow if want more detail.
-
-Github workflow publishes to npm
-Github workflow publishes to CERN S3
-
-This workflow takes care of the following steps:
-1. Publishes the NPM module to the ALICE O2 NPM registry. This is for people installing outside of CERN.
-2. Installs production dependencies and creates the dedicated CERN release publishes it to our private CERN NPM registry called s3 (cern.s3.registry - linux training section).
-3. Creates the Tarball with `NPM pack` and attaches it to the release's assets via the GH CLI. This can be used to manually install the release at P2 if needed.
-
-If at this point everything is green in GitHub actions the release is done, the GitHub release package is created.
-
-Click on the release button in Jira.
-
-Diagram:
+## 1. Prepare the Jira Release
+1. Go to Release section of Jira
+2. Review all the tickets 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
+
+
+## 2. Validate the Release Locally
+1. Checkout the main branch of the Github repository that contains the GUI application
+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. Bump Version and Fix Vulnerabilities
+1. Update the version number: `npm version patch/minor/major`
+2. Check and fix known vulnerabilities: `npm audit fix`
+
+## 4. Create Release Branch and PR
+1. Create a release branch: `git checkout -b release/[name of GUI]/[version]`
+2. Stage and commit the changes
+3. Push the branch to the remote repository
+4. Open a Pull Request (PR) for the release branch
+5. Add the release and associated GUI tag to the PR
+
+## 5. Create the GitHub Release
+1. Create new GitHub release from the branch created in the previous step.
+ - Title of the release must match exactly the Jira release name, e.g., `@aliceo2/bookkeeping@1.15.0`
+2. Copy the release notes from Jira and edit them:
+ - Replace H2 headings with H4
+ - Remove the title.
+ - Rewrite developer text should be rewritten to user-friendly text
+ - Group subtasks under their parents tasks
+ - Remove developer oriented text
+
+> [!CAUTION]
+> Github workflow covers specific logic based on release name.
+> If name is wrong the Github action will fail. To fix this: delete the release AND the tag and start over.
+
+## 6. GitHub Release Workflow (Automated)
+When you click "Create release", 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 at P2 if needed)
+4. If at this point everything is green in GitHub actions the release is done, the GitHub release package is created
+5. Click "Release" in Jira to finalise the release
+
+## Diagram
---
# Deployment
-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).
-
-Commit then and create a new branch with the name `[gui/${applicationNames}/${version}]`, **NO SLASH** in name allowed as it will cause the flp-setup-tool to fail.
-
-Copy the release notes into the PR from the GitHub release, add yourself as the creator and O2-FLP Group Leader as reviewer.
-
-Sync with the people at P2 from an accelerator and detector point of view: make sure no runs are going on and the detectors are in a safe state.
+## 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 then and create a new branch with the name `[gui/${applicationNames}/${version}]`, **NO SLASH** in name allowed as it will cause the flp-setup-tool to fail
+3. Copy the release notes into the PR from the GitHub release, add yourself as the creator and O2-FLP Group Leader as reviewer
If something is merged after a pipeline has started: then we need to rebase the PR and that pipeline will not be useful anymore. Any pipeline with 5 stages means someone has already triggered a deployment. Make the PR and assign it to O2 FLP Group Leader and expect him to see the train of PRs to be merged so we won't trigger a new pipeline in this case we will wait for O2 FLP Group Leader to do. Go back to PR and set it to auto-merge.
-Go to pipelines in GitLab and start the deployment pipeline, you don't need to change any pipeline paramters.
-
-Once the PR is merged the release there is nothing else left to be done and when there is a slot free the deployment will happen.
-
-When GUIs is green on pipeline can see release and can check version is new one in about of the application and play with the new features.
+## 2. Trigger Deployment Pipeline
+1. Sync with the people at P2 from an accelerator and detector point of view: make sure no runs are going on and the detectors are in a safe state
+2. Go to pipelines in GitLab and start the deployment pipeline, you don't need to change any pipeline parameters
+3. Once the PR is merged the release there is nothing else left to be done and when there is a slot free the deployment will happen
-Diagram:
-
+## 3. Post-Deployment Verification
+1. Confirm the GUI/s deployment statuses in the pipeline turn green
+2. Verify the new version appears in the About section of the application
+3. test the newly deployed features
+## Diagram
+
\ No newline at end of file
From f985b99fab49f8a3f07ef22ec9d95864ed779a3d Mon Sep 17 00:00:00 2001
From: George Raduta
Date: Tue, 16 Dec 2025 17:50:11 +0100
Subject: [PATCH 6/6] Improve documentation on release
---
documentation/RELEASE_AND_DEPLOYMENT.md | 49 ++++++++++++-------------
1 file changed, 24 insertions(+), 25 deletions(-)
diff --git a/documentation/RELEASE_AND_DEPLOYMENT.md b/documentation/RELEASE_AND_DEPLOYMENT.md
index 3e2f09a30..d9838a95f 100644
--- a/documentation/RELEASE_AND_DEPLOYMENT.md
+++ b/documentation/RELEASE_AND_DEPLOYMENT.md
@@ -1,36 +1,37 @@
# Release
## 1. Prepare the Jira Release
-1. Go to Release section of Jira
+1. Go to Release section of your Jira project
2. Review all the tickets 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
+4. Use the bulk editor from Jira to move all tickets from "Ready for release" to "Closed"
## 2. Validate the Release Locally
-1. Checkout the main branch of the Github repository that contains the GUI application
+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. Bump Version and Fix Vulnerabilities
-1. Update the version number: `npm version patch/minor/major`
-2. Check and fix known vulnerabilities: `npm audit fix`
-## 4. Create Release Branch and PR
-1. Create a release branch: `git checkout -b release/[name of GUI]/[version]`
-2. Stage and commit the changes
-3. Push the branch to the remote repository
-4. Open a Pull Request (PR) for the release branch
-5. Add the release and associated GUI tag to the PR
+## 3. Create Release Branch and PR
+1. Create a release branch: `git checkout -b release/[BKP/QCG/COG/ILG/FRM]/[version]`
+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 Pull Request (PR) for the release branch
+7. Add the release and associated GUI tag to the PR
+8. Merge the PR once tests have passed and one approval has been received
## 5. Create the GitHub Release
-1. Create new GitHub release from the branch created in the previous step.
+1. Create new GitHub release from the default branch created in the previous step.
- Title of the release must match exactly the Jira release name, e.g., `@aliceo2/bookkeeping@1.15.0`
2. Copy the release notes from Jira and edit them:
- Replace H2 headings with H4
- - Remove the title.
+ - Remove the title
- Rewrite developer text should be rewritten to user-friendly text
- Group subtasks under their parents tasks
- Remove developer oriented text
@@ -43,7 +44,7 @@
When you click "Create release", 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 at P2 if needed)
+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 everything is green in GitHub actions the release is done, the GitHub release package is created
5. Click "Release" in Jira to finalise the release
@@ -55,20 +56,18 @@ When you click "Create release", GitHub Actions will automatically:
## 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 then and create a new branch with the name `[gui/${applicationNames}/${version}]`, **NO SLASH** in name allowed as it will cause the flp-setup-tool to fail
+2. Commit then and create a new branch and PR (named `[gui//]`) and branch with the name `gui-${applicationNames}-${version}`, **NO SLASH** in name allowed for the branch name as it will cause the flp-setup-tool to fail
3. Copy the release notes into the PR from the GitHub release, add yourself as the creator and O2-FLP Group Leader as reviewer
-
-If something is merged after a pipeline has started: then we need to rebase the PR and that pipeline will not be useful anymore. Any pipeline with 5 stages means someone has already triggered a deployment. Make the PR and assign it to O2 FLP Group Leader and expect him to see the train of PRs to be merged so we won't trigger a new pipeline in this case we will wait for O2 FLP Group Leader to do. Go back to PR and set it to auto-merge.
-
-## 2. Trigger Deployment Pipeline
-1. Sync with the people at P2 from an accelerator and detector point of view: make sure no runs are going on and the detectors are in a safe state
-2. Go to pipelines in GitLab and start the deployment pipeline, you don't need to change any pipeline parameters
-3. Once the PR is merged the release there is nothing else left to be done and when there is a slot free the deployment will happen
+4. Check if any existing pipelines are already running.
+ 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. Go to pipelines in GitLab and start the default pipeline FOR YOUR BRANCH, you don't need to change any pipeline parameters.
+ 3. Go back to the PR and set it to auto-merge for when pipeline will be successful.
+5. 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
## 3. Post-Deployment Verification
-1. Confirm the GUI/s deployment statuses in the pipeline turn green
-2. Verify the new version appears in the About section of the application
-3. test the newly deployed features
+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 test that the changes are working as expected
## Diagram
\ No newline at end of file