From 36c1d1bc386063898eb583cc02337d206cbb366a Mon Sep 17 00:00:00 2001
From: Ricardo Amaral <ricardo@doist.com>
Date: Tue, 30 May 2023 16:27:33 +0100
Subject: [PATCH] ci: Add support to publish experimental releases (#278)

---
 .../publish-typist-package-release.yml        | 23 ++++++++++++++++++-
 .releaserc                                    |  6 ++++-
 CONTRIBUTING.md                               |  7 ++++++
 3 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/publish-typist-package-release.yml b/.github/workflows/publish-typist-package-release.yml
index 833e80bf..f2ab805c 100644
--- a/.github/workflows/publish-typist-package-release.yml
+++ b/.github/workflows/publish-typist-package-release.yml
@@ -1,6 +1,7 @@
 name: Typist Package Release
 
 on:
+    workflow_dispatch:
     workflow_run:
         workflows:
             - CI Validation
@@ -28,7 +29,11 @@ jobs:
         runs-on: ubuntu-latest
         timeout-minutes: 60
 
-        if: github.event.workflow_run.conclusion == 'success'
+        # Only run this job when manually triggered for the `experimental` branch, or when triggered
+        # by the `CI Validation` workflow for the `main` branch
+        if: |
+            (github.event_name == 'workflow_dispatch' && contains(github.ref, 'experimental')) ||
+            (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success')
 
         steps:
             - name: Checkout repository
@@ -90,3 +95,19 @@ jobs:
                   npm publish
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    fail-manual-trigger:
+        name: Release & Publish
+        runs-on: ubuntu-latest
+        timeout-minutes: 60
+
+        # Only run this job when manually triggered for all branches with the exception for the
+        # `experimental` branch (which is the only branch allowed to be manually triggered)
+        if: github.event_name == 'workflow_dispatch' && !contains(github.ref, 'experimental')
+
+        steps:
+            - name: Fail job with a message
+              uses: actions/github-script@v6
+              with:
+                  script: |
+                      core.setFailed('Triggering this workflow manually is only allowed for the `experimental` branch.')
diff --git a/.releaserc b/.releaserc
index b522a648..7331fa21 100644
--- a/.releaserc
+++ b/.releaserc
@@ -1,6 +1,10 @@
 {
     "branches": [
-        "main"
+        "main",
+        {
+            "name": "experimental",
+            "prerelease": true
+        }
     ],
     "plugins": [
         [
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 308bbafa..7b7b637f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,6 +66,13 @@ After cloning Typist and installing all dependencies, several commands are at yo
 
 The release process for Typist is almost fully automated with [`semantic-release`](https://github.com/semantic-release/semantic-release), only requiring a core team member to trigger [this workflow](https://github.com/Doist/typist/actions/workflows/publish-typist-package-release.yml) manually whenever a new release needs to be published.
 
+#### Experimental Releases
+
+Sometimes the need for an experimental release arises before a new feature or fix is ready for a stable release. In these cases, we can publish an experimental release by pushing code to the `experimental` branch, and manually triggering the [this workflow](https://github.com/Doist/typist/actions/workflows/publish-typist-package-release.yml). The version number will be automatically picked by `semantic-release`, and `-experimental.x` will be appended at the end of the version number, where `x` represents the number of experimental release published to the `experimental` branch.
+
+> **Warning**
+> The `experimental` branch should never be deleted nor rebased with `main`, otherwise we might lose the Git tags required for `semantic-release` to properly pick the next experimental version number. Instead, `main` should be merged into the `experimental` branch with a merge commit before pushing new code to the `experimental` branch, so that those experiments are always published with the latest published stable version.
+
 ### Visual Studio Code
 
 #### CSS Modules for Storybook