Update CI/CD documentation and workflows

Updated the README to include detailed descriptions of Continuous Integration (CI) and Continuous Deployment (CD) workflows. Included explanations for the push and pull request workflows, with a description of actions taken during each workflow. Added future work recommendations for enhanced workflows. Updated the pull request checks and push check workflows, with clear instructions for code formatting, linting, and type-checking steps.

Signed-off-by: Giovanni Ravalico <[email protected]>

.github/workflows/pull-request-checks-workflow.yml

@@ -0,0 +1,69 @@
+name: 🔗Pull Request Checks Workflow
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+jobs:
+  checks:
+    name: 🫸 Pull Request Checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v4
+
+      - name: 📦 Install pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+          run_install: false
+
+      - name: 🗂️ Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: 🛠️ Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: current
+          cache: 'pnpm'
+
+      - name: 🗄️ Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: 🧩 Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: 📝 Format code
+        # this step should:
+        # - only be run on the code that has been changed
+        # - not apply automatic fixes
+        # - add a comment to the pull request with the changes
+        run: pnpm format
+
+      - name: 🚨 Lint code
+        # this step should:
+        # - only be run on the code that has been changed
+        # - not apply automatic fixes
+        # - add a comment to the pull request with the changes
+        run: pnpm lint
+
+      - name: 🔍 Typecheck code
+        # this step should:
+        # - only be run on the code that has been changed
+        # - not apply automatic fixes
+        # - add a comment to the pull request with the changes
+        run: pnpm typecheck
+
+      - name: 🧪 Run tests
+        run: pnpm test

.github/workflows/push-checks-workflow.yml

@@ -9,6 +9,12 @@ jobs:
   cheks:
     name: 🫸 Push Checks
     runs-on: ubuntu-latest
+    # TODOS:
+    # missing steps:
+    # persist the changes to the code with a commit message
+    # define the failure conditions for the workflow:
+    # - format changes are good to go in even if the workflow fails
+    # - autofix lint changes are good to go in even if the workflow fails
 
     steps:
       - name: 📥 Checkout code

README.md

@@ -17,28 +17,43 @@ $ docker compose up
 ## CI / CD
 ```mermaid
 graph TD
-    subgraph "Continuous Integration (CI)"
-        A[Local Development] -->|Push code| B[Remote Branch]
-        B -->|Open PR| C[Pull Request]
-        C --> D{PR Checks}
-        D -->|Linting| E[Lint Action]
-        D -->|Typechecking| F[Typecheck Action]
-        D -->|Formatting| G[Format Action]
-        D -->|Unit Testing| H[Unit Test Action]
-        D -->|Integration Testing| I[Integration Test Action]
-        D -->|Smoke Testing| J[Smoke Test Action]
-        D -->|Building| K[Build Action]
-        B -->|Push to Remote Branch| P{Push Checks}
-        P -->|Formatting| Q[Format Action]
-        P -->|Linting| R[Lint Action]
-        P -->|Typechecking| S[Typecheck Action]
-        P -->|Unit Testing| T[Unit Test Action]
-        P -->|Building| U[Build Action]
-    end
-    subgraph "Continuous Deployment (CD)"
-        C -->|PR Approved| L[Merge PR]
-        L --> M{Deploy}
-        M -->|Building| N[Build Action]
-        M -->|Deployment| O[Deploy Action]
-    end
+	subgraph "Continuous Integration (CI)"
+		A[Local Development] -->|Push code| B[Remote Branch]
+		B -->|Open PR| C[Pull Request]
+		C --> D{PR Checks}
+		D -->|Linting| E[Lint Action]
+		D -->|Typechecking| F[Typecheck Action]
+		D -->|Formatting| G[Format Action]
+		D -->|Unit Testing| H[Unit Test Action]
+		D -->|Integration Testing| I[Integration Test Action]
+		D -->|Smoke Testing| J[Smoke Test Action]
+		D -->|Building| K[Build Action]
+		B -->|Push to Remote Branch| P{Push Checks}
+		P -->|Formatting| Q[Format Action]
+		P -->|Linting| R[Lint Action]
+		P -->|Typechecking| S[Typecheck Action]
+	end
+	subgraph "Continuous Deployment (CD)"
+		C -->|PR Approved| L[Merge PR]
+		L --> M{Deploy}
+		M -->|Building| N[Build Action]
+		M -->|Deployment| O[Deploy Action]
+	end
 ```
+### Workflows
+
+#### Push Workflow
+This workflow is triggered on every push to a branch that is not main.
+It's designed to be quick and provide immediate feedback to developers.
+It runs lightweight checks such as linting and formatting, and can automatically fix and commit certain types of issues. This ensures that the code in all branches follows the same coding standards and prevents "fix lint" or "fix formatting" commits from cluttering the commit history.
+
+#### Pull Request Workflow
+This workflow is triggered when a pull request is opened or updated.
+It runs a full suite of checks and tests to ensure that the changes are safe to merge.
+More extensive checks are run in this workflow, as it's the last line of defense before the changes are merged into the main branch. However, automatic fixes should generally not be applied in this workflow, as they could potentially introduce unexpected changes. Instead, any issues should be reported back to the developer for manual resolution.
+
+### Future Work
+-[ ] Encapsulate common steps in shared actions or scripts to reduce duplication and improve maintainability.
+-[ ] Implement a step in the pull request workflow to add a comment to the pull request with the changes from the formatting, linting, and typechecking steps.
+-[ ] Implement visual-regression testing in the pull request workflow.
+-[ ]Implement a step in the push workflow to automatically commit and push any changes made by the formatting and linting steps.