Add release and deployment documentation to the WebUI repo

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)
+- [Conventions for Developers](./documentation/CONVENTIONS.md)
+- [Release and Deployment Process](./documentation/RELEASE_AND_DEPLOYMENT.md)

documentation/RELEASE_AND_DEPLOYMENT.md

@@ -0,0 +1,73 @@
+# Release
+
+## 1. Prepare the Jira Release
+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 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/[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 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
+   - 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 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
+![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 then and create a new branch and PR (named `[gui/<prefix_gui>/<release_version>]`) 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
+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. 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
+![Deployment Diagram](./images/deployment_diagram.svg)

documentation/images/deployment_diagram.drawio

@@ -0,0 +1,91 @@
+<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:140.0) Gecko/20100101 Firefox/140.0" version="29.2.7">
+  <diagram name="Page-1" id="v3FHTbixeeevl2tdh_Tu">
+    <mxGraphModel dx="2440" dy="1253" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-1" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;div&gt;Developer&lt;/div&gt;" vertex="1">
+          <mxGeometry height="40" width="280" x="-40" y="120" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-3" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="GitLab" vertex="1">
+          <mxGeometry height="40" width="280" x="280" y="120" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-4" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="GitLab CI/CD" vertex="1">
+          <mxGeometry height="40" width="280" x="600" y="120" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-5" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="P2 / Operations" vertex="1">
+          <mxGeometry height="40" width="280" x="920" y="120" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-33" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" target="z1Yb0Au4B88DAZNOzut0-7" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-6" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Update System Configuration versions" vertex="1">
+          <mxGeometry height="40" width="280" x="280" y="200" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-34" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-7" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" target="z1Yb0Au4B88DAZNOzut0-9" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-7" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Fill in branch name and create PR" vertex="1">
+          <mxGeometry height="40" width="280" x="280" y="280" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-35" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-9" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" target="z1Yb0Au4B88DAZNOzut0-32" value="">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-9" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Add release notes, yourself as creator and O2-FLP Group Leader as reviewer.&amp;nbsp;" vertex="1">
+          <mxGeometry height="40" width="280" x="280" y="360" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-37" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-10" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" target="z1Yb0Au4B88DAZNOzut0-11">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-10" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Sync with people at P2" vertex="1">
+          <mxGeometry height="40" width="280" x="920" y="600" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-38" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" target="z1Yb0Au4B88DAZNOzut0-12">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-44" connectable="0" parent="z1Yb0Au4B88DAZNOzut0-38" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="Once done" vertex="1">
+          <mxGeometry relative="1" x="0.1802" y="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-11" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Start deployment pipeline" vertex="1">
+          <mxGeometry height="40" width="280" x="600" y="680" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-50" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-12" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="z1Yb0Au4B88DAZNOzut0-49">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-12" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Go to production application, check version number and new features added." vertex="1">
+          <mxGeometry height="40" width="280" x="-40" y="760" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-45" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="z1Yb0Au4B88DAZNOzut0-10">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-46" connectable="0" parent="z1Yb0Au4B88DAZNOzut0-45" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" value="once succesful" vertex="1">
+          <mxGeometry relative="1" x="-0.3074" y="2" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-13" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Start integration testing pipeline" vertex="1">
+          <mxGeometry height="40" width="280" x="600" y="520" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-36" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-32" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="z1Yb0Au4B88DAZNOzut0-13">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="670" y="510" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-32" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="Check that no integration tests are running" vertex="1">
+          <mxGeometry height="40" width="280" x="280" y="440" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-48" edge="1" parent="1" source="z1Yb0Au4B88DAZNOzut0-47" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;" target="z1Yb0Au4B88DAZNOzut0-6">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-47" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="START" vertex="1">
+          <mxGeometry height="40" width="280" x="-40" y="200" as="geometry" />
+        </mxCell>
+        <mxCell id="z1Yb0Au4B88DAZNOzut0-49" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="FINISH" vertex="1">
+          <mxGeometry height="40" width="280" x="-40" y="840" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>