Skip to content

Commit 4258609

Browse files
amcclainamcclain
committed
Add README + additional doc comments to new reusable actions
1 parent 14602b9 commit 4258609

6 files changed

Lines changed: 192 additions & 5 deletions

File tree

‎.github/README.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Shared GitHub Actions & Workflows
2+
3+
This directory contains reusable [composite actions](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action)
4+
and CI/CD workflows for the Hoist framework ecosystem. Because this is a public repository, these
5+
actions can be referenced by any GitHub repository. They are used by Hoist ecosystem projects —
6+
including hoist-dev-utils itself, hoist-react, and hoist-core — to standardize release and snapshot
7+
deployment processes. Changes to these actions are documented in the root `CHANGELOG.md` and
8+
reflected in semantic versioning.
9+
10+
## Reusable Composite Actions
11+
12+
Reference these from any workflow in the `xh` organization:
13+
14+
```yaml
15+
uses: xh/hoist-dev-utils/.github/actions/<action-name>@master
16+
```
17+
18+
### `validate-release-version`
19+
20+
Validates that a proposed release version is well-formed semver and a strict single increment
21+
(major, minor, or patch) from the latest existing tag. Supports hotfix releases to older version
22+
lines.
23+
24+
| Input | Required | Description |
25+
|---|---|---|
26+
| `version` | Yes | Release version to validate (e.g. `12.0.0`) |
27+
| `is-hotfix` | No | Set to `true` for hotfix releases to older version lines |
28+
29+
**Prerequisites:**
30+
- The calling workflow must check out with `fetch-depth: 0` and `fetch-tags: true`
31+
so that all git tags are available for comparison.
32+
- Release tags must follow the `v{X.Y.Z}` convention (e.g. `v12.0.0`). Tags that do not match
33+
this pattern are ignored.
34+
35+
### `prepare-npm-snapshot-version`
36+
37+
Prepares a `-SNAPSHOT` version string and writes it to `package.json`. Optionally appends a
38+
millisecond timestamp for uniqueness (enabled by default), producing versions like
39+
`12.0.0-SNAPSHOT.1711814400000`.
40+
41+
| Input | Required | Description |
42+
|---|---|---|
43+
| `version` | No | Override version (read from `package.json` if omitted) |
44+
| `append-timestamp` | No | Append millisecond timestamp (default: `true`) |
45+
46+
| Output | Description |
47+
|---|---|
48+
| `snapshot-version` | The resolved snapshot version string |
49+
50+
### `prepare-gradle-snapshot-version`
51+
52+
Prepares a `-SNAPSHOT` version string and writes it to `gradle.properties`. Designed for Java/Grails
53+
projects like hoist-core. Timestamp appending defaults to `false` for Maven Central compatibility.
54+
55+
| Input | Required | Description |
56+
|---|---|---|
57+
| `version` | No | Override version (read from `gradle.properties` if omitted) |
58+
| `version-prop` | Yes | Property name in `gradle.properties` (e.g. `xhReleaseVersion`) |
59+
| `append-timestamp` | No | Append millisecond timestamp (default: `false`) |
60+
61+
| Output | Description |
62+
|---|---|
63+
| `snapshot-version` | The resolved snapshot version string |
64+
65+
### `create-tag-and-github-release`
66+
67+
Creates a git tag (`v{version}`), pushes it, and creates a GitHub Release with auto-generated
68+
release notes scoped to the previous semver tag.
69+
70+
| Input | Required | Description |
71+
|---|---|---|
72+
| `version` | Yes | Release version (e.g. `12.0.0`) |
73+
| `is-hotfix` | No | Set to `true` to mark the release as non-latest |
74+
75+
**Prerequisites:**
76+
- The calling workflow must check out with `fetch-depth: 0` and `fetch-tags: true`.
77+
- Release tags must follow the `v{X.Y.Z}` convention (e.g. `v12.0.0`). This action both creates
78+
and expects tags in this format.
79+
- The `GH_TOKEN` environment variable must be set (typically `${{ secrets.GITHUB_TOKEN }}`).
80+
81+
## Supporting Scripts
82+
83+
The `scripts/` directory contains shell scripts used internally by the composite actions:
84+
85+
- **`validate-release-version.sh`** — Core validation logic for release versions.
86+
- **`find-latest-version.sh`** — Finds the latest semver tag or the latest tag before a given
87+
version.
88+
89+
## Tests
90+
91+
The `test/` directory contains unit tests for the scripts, run by `unitTestActions.yml` on PRs.
92+
93+
## Workflows
94+
95+
The `workflows/` directory contains workflows for hoist-dev-utils' *own* CI/CD:
96+
97+
- **`deployRelease.yml`** — Manually triggered workflow to publish numbered releases to npm.
98+
Uses `validate-release-version` and `create-tag-and-github-release` actions.
99+
- **`deploySnapshot.yml`** — Publishes a SNAPSHOT build to npm (tagged `next`) on every push to
100+
`develop`. Uses `prepare-npm-snapshot-version`.
101+
- **`unitTestActions.yml`** — Runs unit tests for the shared actions and scripts on PRs that
102+
modify files under `.github/`.
103+
104+
These workflows also serve as reference examples for how to integrate the shared actions, but are themselves dedicated
105+
to actually building and releasing this library itself.
106+
107+
## Usage Example
108+
109+
A typical release workflow in a consuming repo:
110+
111+
```yaml
112+
name: Deploy Release
113+
on:
114+
workflow_dispatch:
115+
inputs:
116+
version:
117+
description: Release version (e.g. 12.0.0)
118+
required: true
119+
type: string
120+
is-hotfix:
121+
description: Hotfix to an older version line?
122+
required: true
123+
type: boolean
124+
default: false
125+
126+
concurrency:
127+
group: deploy-release
128+
cancel-in-progress: false
129+
130+
jobs:
131+
release:
132+
runs-on: ubuntu-latest
133+
permissions:
134+
contents: write
135+
steps:
136+
- uses: actions/checkout@v6
137+
with:
138+
fetch-depth: 0
139+
fetch-tags: true
140+
141+
- uses: xh/hoist-dev-utils/.github/actions/validate-release-version@master
142+
with:
143+
version: ${{ inputs.version }}
144+
is-hotfix: ${{ inputs.is-hotfix }}
145+
146+
# ... build and publish steps ...
147+
148+
- uses: xh/hoist-dev-utils/.github/actions/create-tag-and-github-release@master
149+
with:
150+
version: ${{ inputs.version }}
151+
is-hotfix: ${{ inputs.is-hotfix }}
152+
env:
153+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
154+
```

‎.github/actions/create-tag-and-github-release/action.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@
33
# Tags the current commit, pushes the tag, and creates a GitHub release with auto-generated
44
# notes. Uses find-latest-version.sh to scope release notes to the semver-previous tag.
55
# Hotfix releases are marked as non-latest.
6-
#
7-
# Prerequisites: The calling workflow must checkout with fetch-depth: 0 and fetch-tags: true
8-
# so that all git tags are available locally.
6+
7+
# Prerequisites:
8+
# - Creates tags following the convention "v{X.Y.Z}" (e.g. v12.0.0) and expects existing release tags to use the same format.
9+
# - The calling workflow must checkout with `fetch-depth: 0` and `fetch-tags: true` so that all git tags are available locally.
910

1011
name: Create Tag & GitHub Release
1112
description: Tags the commit, pushes the tag, and creates a GitHub release with auto-generated notes.

‎.github/actions/validate-release-version/action.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@
44
# release version is valid semver, has not already been tagged, and is a strict single
55
# increment from the latest relevant tag. Supports hotfix releases to older version lines.
66
#
7-
# Prerequisites: The calling workflow must checkout with fetch-depth: 0 and fetch-tags: true
8-
# so that all git tags are available locally.
7+
# Prerequisites:
8+
# - Release tags must follow the convention "v{X.Y.Z}" (e.g. v12.0.0).
9+
# - The calling workflow must checkout with `fetch-depth: 0` and `fetch-tags: true` so that all git tags are available locally.
910

1011
name: Validate Release Version
1112
description: Validates that a release version is valid semver and a strict increment from the latest tag.

‎.github/scripts/find-latest-version.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ set -euo pipefail
33

44
# Find the latest semver release tag, or the latest tag before a given version for the current git repo.
55
#
6+
# Expects release tags to follow the convention "v{X.Y.Z}" (e.g. v12.1.0). Tags that do not match
7+
# this pattern are ignored.
8+
#
69
# Usage:
710
# find-latest-version.sh # prints the globally latest version (e.g. 12.1.0)
811
# find-latest-version.sh 11.2.0 # prints the highest version before 11.2.0 (e.g. 11.1.0)

‎.github/scripts/validate-release-version.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ set -euo pipefail
44
# Validates a release version, ensuring it is either a new latest release or a hotfix release for the current git repo.
55
# Prints an error and exits 1 if validation fails.
66
#
7+
# Expects release tags to follow the convention "v{X.Y.Z}" (e.g. v12.0.0). The VERSION input should
8+
# be a bare version string without the "v" prefix.
9+
#
710
# Env variables:
811
# VERSION - The new semantic version number (X.Y.Z).
912
# IS_HOTFIX - If false, must be exactly one increment ahead of the globally latest tag.

‎README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,31 @@ This example file:
136136
If required, rules and other settings extended from this base configuration can be overridden at the
137137
app level.
138138

139+
## Shared GitHub Actions
140+
141+
This repository provides a set of reusable [composite GitHub Actions](https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action)
142+
for CI/CD across the Hoist ecosystem. These actions standardize release validation, snapshot
143+
versioning, and tag/release creation for all `xh` repositories — including npm-based projects
144+
(hoist-react, hoist-dev-utils) and Gradle-based projects (hoist-core).
145+
146+
Available actions under `.github/actions/`:
147+
148+
* **`validate-release-version`** — Ensures a proposed release version is valid semver and a strict
149+
single increment from the latest tag. Supports hotfix releases.
150+
* **`prepare-npm-snapshot-version`** — Resolves and writes a SNAPSHOT version to `package.json`
151+
with an optional uniqueness timestamp.
152+
* **`prepare-gradle-snapshot-version`** — Resolves and writes a SNAPSHOT version to
153+
`gradle.properties` for Java/Grails projects.
154+
* **`create-tag-and-github-release`** — Tags a commit, pushes the tag, and creates a GitHub Release
155+
with auto-generated notes.
156+
157+
Because this is a public repository, these actions can be referenced by any GitHub repository.
158+
They are used by Hoist ecosystem projects and are available to any Hoist application or library.
159+
Consuming repos reference them at `xh/hoist-dev-utils/.github/actions/<name>@master`. Changes to these actions will be
160+
documented in `CHANGELOG.md` and reflected in semantic versioning alongside other updates to this
161+
package. See [`.github/README.md`](.github/README.md) for full documentation, inputs/outputs, and
162+
usage examples.
163+
139164
## Hoist Dev Utils Development
140165

141166
To develop improvements to this library, clone its repo into your workspace alongside a project

0 commit comments

Comments
 (0)