From aed018d90afe5b2edb0e474ca465c9028be3ee49 Mon Sep 17 00:00:00 2001
From: Andrew Newton <andy.newton@dvsa.gov.uk>
Date: Fri, 20 Dec 2024 10:00:40 +0000
Subject: [PATCH] feat: RFC on proposed release-please config changes, to
 support RC releases up to PREP

---
 docs/rfc/rfc-007-prereleases.md | 109 ++++++++++++++++++++++++++++++++
 prerelease-config.json          |   9 +++
 2 files changed, 118 insertions(+)
 create mode 100644 docs/rfc/rfc-007-prereleases.md
 create mode 100644 prerelease-config.json

diff --git a/docs/rfc/rfc-007-prereleases.md b/docs/rfc/rfc-007-prereleases.md
new file mode 100644
index 0000000000..83d088c01b
--- /dev/null
+++ b/docs/rfc/rfc-007-prereleases.md
@@ -0,0 +1,109 @@
+# Workflow for Pre-Releases with Release-Please
+
+## Summary
+
+This RFC proposes a branching strategy and workflow configuration to support pre-releases in a repository using `release-please`. Pre-releases will be managed via a dedicated `prerelease` branch, and version numbers for pre-releases will be explicitly controlled using the `Release-As` commit message annotation. Changes to the `cd.yaml` workflow are required to dynamically apply branch-specific configurations.
+
+## Motivation
+
+The new CD pipeline will only promote release-please releases beyond the nonprod account. It may be desireable to have pre-release code promoted up to the prod account (PREP env) for testing/access to certain resources etc. This proposed workflow allows the creation of pre-releases which can be promoted as far as desired, that will not interfere with normal version numbering, and will not consume the unreleased commit messages on `main` for subsequent real releases.
+
+---
+
+## General Approach to Pre-Releases
+
+### **Branching Strategy**
+
+-   Pre-releases will be handled on a dedicated branch named `prerelease`.
+-   To initiate a pre-release cycle:
+
+    1. Branch off `main`:
+        ```bash
+        git checkout main
+        git pull origin main
+        git checkout -b prerelease
+        ```
+    2. Specify the pre-release version explicitly in a commit:
+
+        ```bash
+        git commit --allow-empty -m "chore: release vX.Y.Z-rc1
+
+        Release-As: vX.Y.Z-rc1"
+        ```
+
+    3. Push the branch to the remote repository:
+        ```bash
+        git push origin prerelease
+        ```
+
+### **Version Management with `Release-As`**
+
+-   Pre-release identifiers (e.g., `-rc`, `-alpha`, `-beta`) are **not automatically appended by `release-please`**.
+-   The version must be explicitly specified using the `Release-As` annotation in a commit message. Examples:
+
+    -   For an initial release candidate:
+
+        ```bash
+        git commit --allow-empty -m "chore: release v1.2.3-rc1
+
+        Release-As: v1.2.3-rc1"
+        ```
+
+    -   For an alpha release:
+
+        ```bash
+        git commit --allow-empty -m "chore: release v1.2.3-alpha.1
+
+        Release-As: v1.2.3-alpha.1"
+        ```
+
+-   If no `Release-As` annotation is provided, `release-please` may default to stable versioning logic, potentially skipping the desired pre-release identifier.
+
+---
+
+## Proposed Changes to `cd.yaml`
+
+### **Current Workflow**
+
+The existing workflow assumes a single configuration file (`release-please-config.yaml`) for all releases and does not differentiate between `main` and `prerelease` branches.
+
+### **Updated Workflow**
+
+The workflow will dynamically apply the appropriate configuration based on the branch. Two configuration files will be introduced:
+
+1. `release-please-config.json` for stable releases.
+2. `prerelease-config.json` for pre-releases.
+
+#### **Updated `cd.yaml`**
+
+```yaml
+jobs:
+    release-please:
+        name: Release
+        runs-on: ubuntu-latest
+        permissions:
+            contents: write
+            pull-requests: write
+        outputs:
+            tag_name: ${{ steps.release.outputs.tag_name }}
+            release_created: ${{ steps.release.outputs.release_created }}
+        steps:
+            # Step 1: Checkout the repository
+            - name: Checkout Repository
+              uses: actions/checkout@v3
+
+            # Step 2: Configure release-please for the branch
+            - name: Configure Release-Please for Branch
+              run: |
+                  if [[ "${{ github.ref_name }}" == "prerelease" ]]; then
+                    echo "Configuring for pre-releases..."
+                    cp prerelease-config.json release-please-config.json
+                  fi
+
+            # Step 3: Run the release-please action
+            - name: Run Release-Please
+              id: release
+              uses: googleapis/release-please-action@v4
+              with:
+                  target-branch: ${{ github.ref_name }}
+```
diff --git a/prerelease-config.json b/prerelease-config.json
new file mode 100644
index 0000000000..aeab585060
--- /dev/null
+++ b/prerelease-config.json
@@ -0,0 +1,9 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "simple",
+  "prerelease": true,
+  "bootstrap-sha": "80555816d300ef64c15c0f40d89d10b7f8795c99",
+  "packages": {
+    ".": {}
+  }
+}