Refactor draft release workflow: Implement shared release engine with categorised changelog generation

- Introduced a composite action for draft releases, consolidating the release process.
- Added a new script to compile release notes from a shared changelog template.
- Created a structured YAML template for changelog categories and exclusions.
- Updated README to reflect new structure and usage instructions.
- Removed previously implemented reusable workflow and streamlined the workflow for better maintainability.

Author: yaswant

.github/workflows/draft-release.yaml

@@ -1,26 +1,20 @@
-# Draft Release
-
-A reusable GitHub Actions [workflow](../.github/workflows/draft-release.yaml)
-that automates the creation of a draft GitHub release with an auto-generated
-changelog, driven by a centralised shared release template.
-
-## Features
-
-- **Zero Boilerplate:** Fetches a centralised configuration template from
-  [MetOffice/growss](https://github.com/MetOffice/growss) and injects it into
-  the calling repository at runtime. Downstream repositories do not need to
-  maintain a local `.github/release.yml` file.
-- **Strict Label Prioritisation:** Generates a structured changelog dynamically
-  grouped by PR labels using the centralised
-  [release template](../.github/templates/release.yml).
-- **Safe Review Gate:** Creates the release in **draft** state, allowing
-  maintainers to audit or adjust notes before going live.
-- **Secure Architecture:** Native platform authentication passes `GITHUB_TOKEN`
-  seamlessly to handle both public and private repository cross-boundary
-  checkouts securely.
-- **Skip Empty Releases:** Automatically skips draft release creation if no
-  merged PRs are found within the release window.
-- Tags the draft release with the triggering Git ref name (e.g. `v1.2.3`).
+# Draft Release - a Shared Global Release Engine
+
+Composite [action](action.yml) that generates categorised draft release notes
+from merged pull requests and updates (or creates) a draft GitHub Release for
+the current tag.
+
+## Location
+
+This action is intentionally located at repository root level and has the
+following components:
+
+- `draft-release/action.yml` (composite action)
+- `draft-release/bin/compile-release-notes.sh` (compiler script)
+- `draft-release/templates/release.yml` (release category template)
+- `draft-release/README.md` (this document)
+
+The changelog template source of truth is `draft-release/templates/release.yml`.
 
 ## Changelog Categories for Simulation Systems
 
@@ -36,10 +30,15 @@ for comprehensive changelog organisation.
 | ⚠️ Deprecations | `deprecated` | Features or APIs that are being phased out, but still functional. |
 | 🐛 Bug Fixes | `bugfix` | Code corrections or hotfixes resolving functional issues. |
 | ✨ New Features | `feature` | Customer-facing features, enhancements, or structural additions. |
-| 🔬 Scientific & Algorithmic Updates | `science`, `technical` | **science:** Domain-specific mathematical changes or model updates.<br>**technical:** Deep algorithmic optimisations or background logic shifts. |
+| 🔬 Scientific & Algorithmic Updates | `science`, `technical` | **science**: Domain-specific mathematical changes or model updates.<br>**technical**: Deep algorithmic optimisations or background logic shifts. |
 | 📚 Documentation | `documentation` | Changes isolated to READMEs, inline code docstrings, scientific documentation, working practices, or other non-functional documentation updates. |
 | ⚡ Performance Improvements | `optimisation` | Direct speed execution metrics, runtime improvements, memory, storage, or other resource optimisations. |
 | ♻️ Refactoring | `refactor` | Code cleanup, modularisation, or other internal improvements without behavior changes. |
+| 🛠️ Maintenance | `build`, `chore`, `ci` | **build**: Changes affecting build tools or external compiler toolchains.<br>**chore**: General housekeeping, licence updates, or minor administrative tasks.<br>**ci**: Changes to GitHub Actions workflows, CI/CD pipelines, or other automation.|
+
+> [!NOTE]
+> First time contributors are added automatically when the merged PR has an
+> `author_association` of `FIRST_TIME_CONTRIBUTOR`.
 
 ### Excluded Labels
 
@@ -48,109 +47,85 @@ output entirely, regardless of any other labels they carry:
 
 | Label | Purpose |
 | ----- | ------- |
-| `build` | Changes affecting build tools or external compiler toolchains. |
-| `chore` | General housekeeping, license updates, or minor administrative tasks. |
-| `ci` | Modifications to GitHub Actions workflows or automation systems. |
 | `ignore-changelog` | Escape-hatch label to manually suppress a specific PR from the logs. |
 | `test` | Changes related to testing frameworks or test cases. |
 | `wip` | Work in progress PRs that are not ready for release. |
 
-## Permissions
-
-The calling execution job block must explicitly declare `contents: write` to
-authorise the native GitHub CLI runner to write assets and publish release
-footprints:
-
-```yaml
-permissions:
-    contents: write
-    pull-requests: read
-```
-
-## Usage
+## How It Works
 
-To ensure deterministic behaviour across versions, use the same reference for
-both the workflow and `template-ref`.
+1. Checks out the caller repository into `local-code` with full tag history.
+2. Runs `draft-release/bin/compile-release-notes.sh` to:
+    - find release commits,
+    - map merged PRs to changelog categories from
+      `draft-release/templates/release.yml`,
+    - write `release-notes.md` and set `has_commits` output.
+3. If commits exist, creates or updates a draft release for the current tag.
 
-### Variant A: Production Tag Auto-Trigger (Recommended)
+```mermaid
+graph TD
+    %% Define Node Styles for Scannability
+    classDef trigger style fill:#f9f,stroke:#333,stroke-width:2px,font-weight:bold;
+    classDef step style fill:#bbf,stroke:#333,stroke-width:1px;
+    classDef desc style fill:#fff,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5,font-size:12px;
 
-```yaml
-name: Draft Release Deployment
+    %% Workflow Connections
+    Trigger([Tag Push Event]) --> Step1[1. Checkout Caller Repository]
+    Step1 --> Step2[2. Compile Release Notes]
+    Step2 --> Step3{Has Merged PRs?}
+    Step3 -->|Yes| Step4[3. Create or Update Draft Release]
+    Step3 -->|No| Skip[Skip Release Creation]
 
-on:
-  push:
-    tags:
-      - "v*" # Triggers automatically for semantic production tags
+    %% Step Explanations (Side-nodes)
+    Step1 -.-> Desc1[Checks out the calling repository into <code>local-code</code><br>with full history and tags]
+    Step2 -.-> Desc2[Executes <code>compile-release-notes.sh</code><br>using action-local template <code>release.yml</code>]
+    Step4 -.-> Desc3[Executes <code>gh release create/edit</code><br>with categorised changelog notes in draft state]
+    Skip -.-> Desc4[Workflow completes early<br>if no merged PRs found in release window]
 
-jobs:
-  release:
-    uses: MetOffice/growss/.github/workflows/draft-release.yaml@main
-    with:
-      template-ref: "main"
-    permissions:
-      contents: write
-      pull-requests: read
+    %% Assign Classes to Nodes
+    class Trigger trigger;
+    class Step1,Step2,Step3,Step4,Skip step;
+    class Desc1,Desc2,Desc3,Desc4 desc;
 ```
 
-### Variant B: Hybrid Trigger (Tag Push + Manual Run)
+## Usage
 
 ```yaml
-name: Draft Release Deployment
+name: Automated Release Notes
 
 on:
-  push:
-    tags:
-      - "v*"
-  workflow_dispatch:
+    push:
+        tags:
+            - "v*"
 
 jobs:
-  release:
-    uses: MetOffice/growss/.github/workflows/draft-release.yaml@main
-    with:
-      template-ref: "main"
-    permissions:
-      contents: write
+    release:
+        runs-on: ubuntu-slim
+        permissions:
+            contents: write
+            pull-requests: read
+        steps:
+            - name: Draft Release
+              uses: MetOffice/growss/draft-release@main  # or tag or sha
 ```
 
-> [!WARNING] **Important Trigger Caveat:** The draft release title, tag mapping,
-> and PR delta history bounds are determined dynamically from
-> `${{ github.ref_name }}`.
->
-> - Triggering via **Tag Push** ensures the title matches the target version tag
->   (e.g. `v1.2.3`).
-> - Triggering via **Workflow Dispatch** uses the active branch name (e.g.
->   `main`) as the release name target, which will include all historical
->   unreleased commits instead of a bounded tag delta window.
+## Required Permissions
 
-## How It Works
+- `contents: write` to create/edit draft releases.
+- `pull-requests: read` to read merged PR metadata for changelog generation.
 
-```mermaid
-graph TD
-    %% Define Node Styles for Scannability
-    classDef trigger style fill:#f9f,stroke:#333,stroke-width:2px,font-weight:bold;
-    classDef step style fill:#bbf,stroke:#333,stroke-width:1px;
-    classDef desc style fill:#fff,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5,font-size:12px;
+## Outputs
 
-    %% Workflow Connections
-    Trigger([Tag Push Event]) --> Step1[1. Fetch Shared Template]
-    Step1 --> Step2[2. Fetch Target Workspace]
-    Step2 --> Step3[3. Compile Release Notes]
-    Step3 --> Step4{Has Merged PRs?}
-    Step4 -->|Yes| Step5[4. Create Draft Release]
-    Step4 -->|No| Skip[Skip Release Creation]
+The compile step exposes:
 
-    %% Step Explanations (Side-nodes)
-    Step1 -.-> Desc1[Checks out <code>MetOffice/growss</code> to parse <code>.github/templates/release.yml</code>]
-    Step2 -.-> Desc2[Checks out the calling repository's<br>workspace directory branch with full history]
-    Step3 -.-> Desc3[Executes <code>.github/bin/compile-release-notes.sh</code><br>to extract merged PRs and categorise by labels]
-    Step5 -.-> Desc4[Executes <code>gh release create/edit</code><br>with categorised changelog notes in draft state]
-    Skip -.-> Desc5[Workflow completes early<br>if no merged PRs found in release window]
+- `has_commits`: `true` when release notes were generated from commits,
+  otherwise `false`.
 
-    %% Assign Classes to Nodes
-    class Trigger trigger;
-    class Step1,Step2,Step3,Step4,Step5,Skip step;
-    class Desc1,Desc2,Desc3,Desc4,Desc5 desc;
-```
+## Notes
+
+- The action uses `${{ github.token }}` internally for `gh` API commands.
+- `release-notes.md` is generated in the GitHub Actions workspace root.
+- The release body is grouped by labels defined in
+  `draft-release/templates/release.yml`.
 
 ## Licence
 

draft-release/README.md

@@ -0,0 +1,49 @@
+# ------------------------------------------------------------------------------
+# (c) Crown copyright Met Office. All rights reserved.
+# The file LICENCE, distributed with this code, contains details of the terms
+# under which the code may be used.
+# ------------------------------------------------------------------------------
+
+name: Shared Global Release Engine
+description: Automates draft releases using centralised assets
+
+runs:
+  using: "composite"
+  steps:
+    - name: Checkout caller repository with full history
+      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      with:
+        path: local-code
+        fetch-depth: 0
+        fetch-tags: true
+        persist-credentials: false
+
+    - name: Compile categorised release notes from template labels
+      id: compile-release-notes
+      shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        CALLER_REPO: ${{ github.repository }}
+        GITHUB_REF_NAME: ${{ github.ref_name }}
+        GITHUB_SHA: ${{ github.sha }}
+      run: |
+        set -euo pipefail
+        bash "${{ github.action_path }}/bin/compile-release-notes.sh" \
+          "$CALLER_REPO" "$GITHUB_SHA" "$GITHUB_REF_NAME"
+
+    - if: steps.compile-release-notes.outputs.has_commits == 'true'
+      shell: bash
+      working-directory: local-code
+      env:
+        GH_TOKEN: ${{ github.token }}
+        GITHUB_REF_NAME: ${{ github.ref_name }}
+      run: |
+        set -euo pipefail
+        TITLE="Release ${GITHUB_REF_NAME} (Draft)"
+        if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
+          gh release edit "${GITHUB_REF_NAME}" --draft --title "${TITLE}"  \
+            --notes-file ../release-notes.md
+        else
+          gh release create "${GITHUB_REF_NAME}" --draft --title "${TITLE}" \
+            --notes-file ../release-notes.md
+        fi