Merge pull request #13 from uclahs-cds/nwiltsie-alias-release

Add workflow to update major alias tags, templates
uclahs-cds · Sep 30, 2024 · 6c046d8 · 6c046d8
2 parents abbe8ec + 668db63
commit 6c046d8
Show file tree

Hide file tree

Showing 22 changed files with 1,103 additions and 165 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,20 @@
+---
+version: 2
+updates:
+  # GitHub Actions in use by this repository
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  # Python packages in use by this repository
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  # The template workflows demonstrating use _of_ this repository
+  - package-ecosystem: "github-actions"
+    directory: "/templates"
+    schedule:
+      interval: "weekly"
diff --git a/.github/workflows/internal-alias.yaml b/.github/workflows/internal-alias.yaml
@@ -0,0 +1,20 @@
+---
+name: 🛠️ Update release alias tags
+
+run-name: Update alias for ${{ github.event.action }} ${{ github.event.release.name }}
+
+on:
+  release:
+    types:
+      - published
+      - deleted
+
+permissions:
+  actions: read
+  contents: write
+
+jobs:
+  update-alias:
+    uses: ./.github/workflows/wf-alias-release.yaml
+    # Secrets are only required until tool-create-release is made public
+    secrets: inherit
diff --git a/.github/workflows/internal-finalize.yaml b/.github/workflows/internal-finalize.yaml
@@ -1,5 +1,7 @@
 ---
-name: Finalize release
+name: 🛠️ Finalize release
+
+run-name: Finalize release from branch `${{ github.event.pull_request.head.ref }}`
 
 on:
   pull_request:

diff --git a/.github/workflows/internal-prepare.yaml b/.github/workflows/internal-prepare.yaml
@@ -1,5 +1,5 @@
 ---
-name: Prepare new release
+name: 📦 Prepare new release
 
 run-name: Open PR for new ${{ inputs.bump_type }} release
 
@@ -8,14 +8,15 @@ on:
     inputs:
       bump_type:
         type: choice
-        description: >-
-          Semantic version bump type
+        description: Semantic version bump type
         required: true
         options:
           - major
           - minor
           - patch
-          - prerelease
+      prerelease:
+        type: boolean
+        description: Create a prerelease
 
 permissions:
   actions: read
@@ -27,5 +28,6 @@ jobs:
     uses: ./.github/workflows/wf-prepare-release.yaml
     with:
       bump_type: ${{ inputs.bump_type }}
-      exact_version: ''
+      prerelease: ${{ inputs.prerelease }}
+    # Secrets are only required until tool-create-release is made public
     secrets: inherit
diff --git a/.github/workflows/wf-alias-release.yaml b/.github/workflows/wf-alias-release.yaml
@@ -0,0 +1,55 @@
+---
+on:
+  workflow_call:
+
+jobs:
+  alias-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Get the version of _this_ repository that is in use so that we can use
+      # sidecar scripts
+      - id: workflow-parsing
+        name: Get SHA of reusuable workflow
+        env:
+          REPO: ${{ github.repository }}
+          RUN_ID: ${{ github.run_id }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ACTION_DATA=$(gh api "repos/$REPO/actions/runs/$RUN_ID")
+          echo "::debug::$ACTION_DATA"
+          SHA=$(echo "$ACTION_DATA" | jq -r '.referenced_workflows | .[] | select(.path | startswith("uclahs-cds/tool-create-release")).sha')
+          echo "SHA=$SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout reusable repository
+        uses: actions/checkout@v4
+        with:
+          repository: uclahs-cds/tool-create-release
+          path: reusable
+          ref: ${{ steps.workflow-parsing.outputs.SHA }}
+          token: ${{ secrets.UCLAHS_CDS_REPO_READ_TOKEN }}
+
+      - name: Checkout calling repository
+        uses: actions/checkout@v4
+        with:
+          path: caller
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Set up python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      # Install the bundled package
+      - run: pip install ./reusable
+
+      # Update the alias if necessary
+      - id: alias-release
+        run: |
+          git config --file "$REPO_DIR/.git/config" user.name "github-actions[bot]"
+          git config --file "$REPO_DIR/.git/config" user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          alias-release "$REPO_DIR" "$GITHUB_REF"
+        env:
+          REPO_DIR: caller
+          GH_TOKEN: ${{ github.token }}
diff --git a/.github/workflows/wf-finalize-release.yaml b/.github/workflows/wf-finalize-release.yaml
@@ -38,6 +38,8 @@ jobs:
         env:
           INPUT_DRAFT: ${{ inputs.draft }}
         with:
+          # Use the separate token so that `published` events will be fired
+          github-token: ${{ secrets.UCLAHS_CDS_REPO_READ_TOKEN }}
           script: |
             const script = require('./scripts/finalize-release.js')
             await script({github, context, core})
diff --git a/.github/workflows/wf-prepare-release.yaml b/.github/workflows/wf-prepare-release.yaml
@@ -9,11 +9,16 @@ on:
         default: CHANGELOG.md
       bump_type:
         type: string
-        description: Semantic version bump type. Must be one of `major`, `minor`, `patch`, `prerelease`, or `exact`. Using the first four options will compute the next appropriate semantic version tag based on the most recent tag available from the main branch. Using `exact` is required for repositories without semantic version tags and allows specifying the exact next tag to use with the `exact_version` argument.
+        description: Semantic version bump type. Must be one of `major`, `minor`, `patch`, or `exact`. Using the first three options will compute the next appropriate semantic version tag based on the most recent tag available from the main branch. Using `exact` is required for repositories without semantic version tags and allows specifying the exact next tag to use with the `exact_version` argument.
         required: true
+      prerelease:
+        type: boolean
+        description: Mark this semantic version bump as a pre-release. Only used if bump_type is not set to `exact`.
+        required: false
+        default: false
       exact_version:
         type: string
-        description: Exact version number to target. Only used if bump_type is set to `exact`.
+        description: Exact non-semantic version number to target. Only used if bump_type is set to `exact`.
         required: false
         default: ""
       timezone:
@@ -28,6 +33,7 @@ jobs:
 
     env:
       BUMP_TYPE: ${{ inputs.bump_type }}
+      PRERELEASE: ${{ inputs.prerelease }}
       EXACT_VERSION: ${{ inputs.exact_version }}
       CHANGELOG_TIMEZONE: ${{ inputs.timezone }}
 
@@ -71,7 +77,7 @@ jobs:
 
       # Get the next version using the package's script
       - id: get-next-version
-        run: get-next-version "$REPO_DIR" "$BUMP_TYPE" "$EXACT_VERSION"
+        run: get-next-version "$REPO_DIR" "$BUMP_TYPE" "$PRERELEASE" "$EXACT_VERSION"
         env:
           REPO_DIR: caller
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,16 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Documentation that versions must begin with a digit
 - Documentation that git tags must begin with a `v`
+- Template workflows to copy
+- Enable Dependabot for GitHub Actions, pip, and template workflows
+- Unit tests for version updates
+- Workflow to update major tag (e.g. `v2`) when new releases are published or deleted
+- Unit tests for aliasing
+
+### Changed
+
+- Change `prerelease` from an input "bump type" to a separate boolean
+- Create "prerelease" GitHub Releases from prerelease versions
 
 ### Fixed
 

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Automations for GitHub Releases
 
-This pair of reusable workflows manage the complexity of creating and tagging new software releases on GitHub.
+This set of reusable workflows manage the complexity of creating and tagging new software releases on GitHub.
 
 ## Versioning Standards
 
@@ -15,97 +15,64 @@ These workflows make the following assumptions:
 
 ## Usage
 
+Usage of this tool requires adding three workflows to each calling repository (non-semantic repositories only need two). Complete versions of these workflows can be copied from the [templates/](templates/) directory.
+
 `wf-prepare-release.yaml` is triggered manually (via a `workflow_dispatch`) and takes the following actions:
 
-1. Compute the target version number based on existing tags and user input for `major`/`minor`/`patch`/`prerelease`.
+1. Compute the target version number.
+  * Semantic repositories compute the version based on existing tags and user input for the bump type (`major`/`minor`/`patch`) and the prerelease flag.
+  * Non-semantic repositories accept the next version as an input.
 1. Re-write the `CHANGELOG.md` file to move unreleased changes into a new dated release section.
 1. Open a PR listing the target version number and release tag.
 
+```mermaid
+    gitGraph
+        commit id: " "  tag: "v1" tag: "v1.0.0"
+        commit id: "  "
+        commit id: "   "
+
+        checkout main
+        branch prepare_patch
+        commit id: "target: v1.0.1"
+```
+
 `wf-finalize-release.yaml`, triggered when a release PR is merged, takes the following actions:
 
 1. Create a new release with auto-generated notes and the target tag.
   * By default the new release is a draft, so no public release or tag are created without user intervention.
 1. Comment on the release PR with a link to the new release.
 
-## Example Usage
-
-Usage of this tool requires adding two workflows to each calling repository:
-
-**`prepare-release.yaml`**
-
-```yaml
----
-name: Prepare new release
-
-run-name: Open PR for new ${{ inputs.bump_type }} release
-
-on:
-  workflow_dispatch:
-    inputs:
-      bump_type:
-        type: choice
-        description: >-
-          Semantic version bump type. Using `exact` is required for repositories
-          without semantic version tags and allows specifying the exact next tag
-          to use with the `exact_version` argument.
-        required: true
-        options:
-          - major
-          - minor
-          - patch
-          - prerelease
-          - exact
-      exact_version:
-        type: string
-        description: >-
-          Exact version number to target. Only used if bump_type is set to
-          `exact`. Do not include a leading `v`.
-        required: false
-        default: ''
-
-permissions:
-  actions: read
-  contents: write
-  pull-requests: write
-
-jobs:
-  prepare-release:
-    uses: uclahs-cds/tool-create-release/.github/workflows/wf-prepare-release.yaml@v1
-    with:
-      bump_type: ${{ inputs.bump_type }}
-      exact_version: ${{ inputs.exact_version }}
-    # Secrets are only required until tool-create-release is made public
-    secrets: inherit
+```mermaid
+    gitGraph
+        commit id: " "  tag: "v1" tag: "v1.0.0"
+        commit id: "  "
+        commit id: "   "
+
+        checkout main
+        branch prepare_patch
+        commit id: "target: v1.0.1"
+
+        checkout main
+        merge prepare_patch tag: "v1.0.1"
 ```
 
-**`finalize-release.yaml`**
-
-```yaml
----
-name: Finalize release
-
-on:
-  pull_request:
-    branches:
-      - main
-    types:
-      - closed
-
-permissions:
-  actions: read
-  contents: write
-  pull-requests: write
-
-jobs:
-  finalize-release:
-    # This conditional ensures that the reusable workflow is only run for
-    # release pull requests. The called workflow repeats these checks.
-    if: ${{ github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'automation-create-release') }}
-    uses: uclahs-cds/tool-create-release/.github/workflows/wf-finalize-release.yaml@v1
-    with:
-      draft: true
-    # Secrets are only required until tool-create-release is made public
-    secrets: inherit
+> [!NOTE]
+> `wf-alias-release.yaml` is only applicable for repositories using semantic versioning.
+
+`wf-alias-release.yaml`, triggered when a release is published or deleted, synchronizes the corresponding [major tag alias](https://docs.github.com/en/actions/sharing-automations/creating-actions/about-custom-actions#using-tags-for-release-management) to the highest non-prerelease release tag:
+
+```mermaid
+    gitGraph
+        commit id: " " tag: "v1.0.0"
+        commit id: "  "
+        commit id: "   "
+
+        checkout main
+        branch prepare_patch
+        commit id: "target: v1.0.1"
+
+        checkout main
+        merge prepare_patch tag: "v1" tag: "v1.0.1"
 ```
 
 ## Parameters
@@ -114,7 +81,8 @@ Parameters can be specified using the [`with`](https://docs.github.com/en/action
 
 | Workflow | Parameter | Type | Required | Description |
 | ---- | ---- | ---- | ---- | ---- |
-| `wf-prepare-release.yaml` | `bump_type` | string | yes | Kind of semantic release version to target. Must be one of `major`, `minor`, `patch`, `prerelease`, or `exact`. Using `exact` requires `exact_version`. |
+| `wf-prepare-release.yaml` | `bump_type` | string | yes | Kind of semantic release version to target. Must be one of `major`, `minor`, `patch`, or `exact`. Using `exact` requires `exact_version`. |
+| `wf-prepare-release.yaml` | `prerelease` | boolean | no | If true, mark the bumped semantic release as a prerelease (only used if `bump_type` is not `exact`). |
 | `wf-prepare-release.yaml` | `exact_version` | string | no | The exact version to assign to the next release (only used if `bump_type` is `exact`). Must not include a leading `v` - use `1XXXX`, not `v1XXXX`. |
 | `wf-prepare-release.yaml` | `changelog` | string | no | Relative path to the CHANGELOG file. Defaults to `./CHANGELOG.md`. |
 | `wf-prepare-release.yaml` | `timezone` | string | no | IANA timezone to use when calculating the current date for the CHANGELOG. Defaults to `America/Los_Angeles`. |