@hubspot/npm-scripts 0.3.4 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -11
- package/package.json +4 -2
- package/src/__tests__/release.test.js +490 -10
- package/src/constants/release.d.ts +3 -0
- package/src/constants/release.js +7 -0
- package/src/release.js +124 -39
- package/src/types.d.ts +5 -2
- package/src/utils/__tests__/git.test.js +3 -3
- package/src/utils/__tests__/logging.test.js +15 -1
- package/src/utils/__tests__/npm.test.js +18 -1
- package/src/utils/git.js +1 -1
- package/src/utils/logging.d.ts +1 -0
- package/src/utils/logging.js +6 -0
- package/src/utils/npm.d.ts +1 -0
- package/src/utils/npm.js +5 -0
- package/src/utils/release/__tests__/steps.test.js +596 -6
- package/src/utils/release/__tests__/validate.test.js +9 -1
- package/src/utils/release/__tests__/version.test.js +40 -34
- package/src/utils/release/steps.d.ts +29 -4
- package/src/utils/release/steps.js +355 -17
- package/src/utils/release/types.d.ts +22 -2
- package/src/utils/release/validate.d.ts +3 -0
- package/src/utils/release/validate.js +6 -0
- package/src/utils/release/version.d.ts +2 -1
- package/src/utils/release/version.js +22 -6
package/README.md
CHANGED
|
@@ -71,6 +71,8 @@ buildReleaseScript({
|
|
|
71
71
|
postLatestRelease: async () => {
|
|
72
72
|
// Optional function to run after latest releases
|
|
73
73
|
},
|
|
74
|
+
publishFromCI: false, // optional, see "Publishing from CI" below
|
|
75
|
+
experimentalWorkflow: 'experimental-release.yml', // optional, used with publishFromCI
|
|
74
76
|
},
|
|
75
77
|
});
|
|
76
78
|
```
|
|
@@ -80,7 +82,10 @@ Then add to your `package.json`:
|
|
|
80
82
|
```json
|
|
81
83
|
{
|
|
82
84
|
"scripts": {
|
|
83
|
-
"release": "tsx ./scripts/release.ts
|
|
85
|
+
"release": "tsx ./scripts/release.ts latest",
|
|
86
|
+
"beta-release": "tsx ./scripts/release.ts next",
|
|
87
|
+
"experimental-release": "tsx ./scripts/release.ts experimental",
|
|
88
|
+
"previous-release": "tsx ./scripts/release.ts previous"
|
|
84
89
|
},
|
|
85
90
|
"publishConfig": {
|
|
86
91
|
"registry": "https://registry.npmjs.org/"
|
|
@@ -88,35 +93,88 @@ Then add to your `package.json`:
|
|
|
88
93
|
}
|
|
89
94
|
```
|
|
90
95
|
|
|
96
|
+
Don't name a script `prerelease`: Yarn 1 runs it as a pre-hook of `release`.
|
|
97
|
+
|
|
91
98
|
#### Release Commands
|
|
92
99
|
|
|
100
|
+
The script registers one command per tag, plus the combined `release` command:
|
|
101
|
+
|
|
102
|
+
| Command | Tag | `-v` choices |
|
|
103
|
+
| --- | --- | --- |
|
|
104
|
+
| `latest` | `latest` | `patch`, `minor`, `major` |
|
|
105
|
+
| `next` | `next` | `patch`, `minor`, `major`, `prerelease` |
|
|
106
|
+
| `previous` | `previous` | `patch`, `minor`, `major` |
|
|
107
|
+
| `experimental` | `experimental` | none, the version comes from npm (see below) |
|
|
108
|
+
| `release -v <increment> -t <tag>` | any | all |
|
|
109
|
+
|
|
110
|
+
With the scripts above:
|
|
111
|
+
|
|
93
112
|
```bash
|
|
94
|
-
# Release a
|
|
95
|
-
yarn release -v
|
|
113
|
+
# Release a minor version to latest
|
|
114
|
+
yarn release -v minor
|
|
96
115
|
|
|
97
|
-
# Release a
|
|
98
|
-
yarn release
|
|
116
|
+
# Release a beta, choosing the increment from a prompt
|
|
117
|
+
yarn beta-release
|
|
99
118
|
|
|
100
|
-
# Release
|
|
101
|
-
yarn release -v
|
|
119
|
+
# Release a patch to the previous major version, from previousBranch
|
|
120
|
+
yarn previous-release -v patch
|
|
121
|
+
|
|
122
|
+
# Release an experimental version of the current branch
|
|
123
|
+
yarn experimental-release
|
|
102
124
|
|
|
103
125
|
# Dry run (test without publishing)
|
|
104
|
-
yarn release -v
|
|
126
|
+
yarn release -v patch -d
|
|
127
|
+
|
|
128
|
+
# Non-interactive release (e.g. run by an agent or script)
|
|
129
|
+
yarn beta-release -v minor -y
|
|
105
130
|
```
|
|
106
131
|
|
|
132
|
+
Experimental versions are based on the current `latest` dist-tag: the script finds the highest published `<latest>-experimental.N` and uses `N + 1`, or `0` if there isn't one. For example, with `latest` at `8.1.0` and `8.1.0-experimental.2` published, the next experimental release is `8.1.0-experimental.3`.
|
|
133
|
+
|
|
107
134
|
#### Parameters
|
|
108
135
|
|
|
109
|
-
- `-v, --versionIncrement`: SemVer increment type
|
|
110
|
-
- `-t, --tag`: Release tag (`latest`, `next`, `experimental`)
|
|
136
|
+
- `-v, --versionIncrement`: SemVer increment type. Required for `release`. For `latest`, `next`, and `previous`, you're prompted to choose when it's omitted.
|
|
137
|
+
- `-t, --tag`: Release tag (`latest`, `next`, `experimental`, `previous`). Only for `release`.
|
|
111
138
|
- `-d, --dryRun`: Run without actually publishing
|
|
139
|
+
- `-y, --yes`: Skip all prompts. The "not yet released in beta" warning is still printed, but the release continues. If `-v` is missing, or you aren't logged in to npm, the release fails with instructions instead of prompting.
|
|
140
|
+
- `--skipBranchValidation`: Bypass the branch validation check
|
|
141
|
+
- `--skipVersionCheck`: Bypass checking that the local version matches the published version
|
|
142
|
+
|
|
143
|
+
#### Publishing from CI (`publishFromCI`)
|
|
144
|
+
|
|
145
|
+
Set `publishFromCI: true` when GitHub Actions workflows publish to npm. Both paths need the [GitHub CLI](https://cli.github.com) (`gh`), installed and logged in. The script checks this before changing anything. Nothing is built or published locally, and npm auth isn't checked.
|
|
146
|
+
|
|
147
|
+
**`latest`, `next`, and `previous`** open a release PR:
|
|
148
|
+
|
|
149
|
+
1. Run the same branch and version validation as the default flow. `previous` releases must run from `previousBranch` and match the `previous` dist-tag.
|
|
150
|
+
2. Create the `v<version>-publish` branch (when run from the main or previous branch)
|
|
151
|
+
3. Bump `package.json` with `yarn version --no-git-tag-version`. No git tag is created, so CI should tag the merge commit.
|
|
152
|
+
4. Commit `chore: release v<version>`, push the branch, and open a PR against the main branch, or against `previousBranch` for `previous`. The PR body names the tag it publishes to.
|
|
153
|
+
|
|
154
|
+
Merging the PR should trigger your publish workflow. Dist-tags aren't changed locally, and `postLatestRelease` doesn't run. With `-d`, the script prints the commit, push, and PR commands without running them and reverts the version bump. If any step fails, the local changes are rolled back and you end up back on your original branch.
|
|
155
|
+
|
|
156
|
+
**`experimental`** dispatches a workflow that publishes the current branch:
|
|
157
|
+
|
|
158
|
+
1. Check that you're not on the main or previous branch, that your active `gh` account can access the repository, and that the branch is pushed: `HEAD` matches `origin/<branch>`
|
|
159
|
+
2. Show the current `latest` version, the last experimental release, and the new version, and confirm. The workflow recomputes the final version.
|
|
160
|
+
3. Run `gh workflow run <experimentalWorkflow> --ref <mainBranch> -f branch=<branch> -f sha=<HEAD sha>`. The workflow always runs from the main branch.
|
|
161
|
+
4. Find the run, link to it, and print each job as it finishes
|
|
162
|
+
5. Download the `experimental-version` artifact and print the published version and its `yarn add` command
|
|
163
|
+
|
|
164
|
+
With `-d`, the script runs the checks and prints the `gh workflow run` command without dispatching it.
|
|
165
|
+
|
|
166
|
+
The workflow (`experimental-release.yml` by default, set with `experimentalWorkflow`) must accept `branch` and `sha` inputs, set `run-name: "Experimental release ${{ inputs.branch }}@${{ inputs.sha }}"` so the script can find the run, and upload an artifact named `experimental-version` with a `version.txt` file that contains the published version.
|
|
167
|
+
|
|
168
|
+
Run your publish jobs in a [GitHub environment](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) that only the main branch can deploy to, and set that environment on the package's npm trusted publishers. Otherwise anyone with write access can publish by running a modified workflow from another branch.
|
|
112
169
|
|
|
113
170
|
#### Features
|
|
114
171
|
|
|
115
172
|
- **Branch protection**: Ensures releases are made from the correct branch
|
|
116
173
|
- **Version validation**: Checks local version against published versions
|
|
117
|
-
- **Interactive prompts**: Confirms release details
|
|
174
|
+
- **Interactive prompts**: Confirms release details before publishing
|
|
118
175
|
- **Automatic tagging**: Creates git tags and pushes to repository
|
|
119
176
|
- **GitHub integration**: Opens PR and release pages automatically
|
|
177
|
+
- **Clean working tree required**: Fails before changing anything if `git status` shows uncommitted changes, because the rollback runs `git checkout HEAD -- .`
|
|
120
178
|
- **Rollback support**: Cleans up on failure
|
|
121
179
|
|
|
122
180
|
### Repo Sync Script Builder (`buildRepoSyncScript`)
|
|
@@ -183,3 +241,22 @@ yarn repo-sync -v=1.0.0 -d
|
|
|
183
241
|
- **Cleanup support**: Removes temporary directories after completion
|
|
184
242
|
|
|
185
243
|
This script supports a `PUBLIC_README.md` pattern that allows you to maintain an internal readme file that does not sync to the target repo. The `PUBLIC_README.md` file will sync into the target repo as `README.md`.
|
|
244
|
+
|
|
245
|
+
## Releasing `@hubspot/npm-scripts`
|
|
246
|
+
|
|
247
|
+
This package releases itself with `publishFromCI`. You need the [GitHub CLI](https://cli.github.com) logged in to `github.com` with an account that can access `HubSpotEngineering`.
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
# latest (from master): opens a release PR, and merging it publishes
|
|
251
|
+
yarn release -v patch
|
|
252
|
+
|
|
253
|
+
# next (from master)
|
|
254
|
+
yarn beta-release -v minor
|
|
255
|
+
|
|
256
|
+
# experimental (from a pushed feature branch): runs the Experimental Release workflow
|
|
257
|
+
yarn experimental-release
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
The [Release](.github/workflows/release.yml) workflow builds and dry-run publishes each release PR, then publishes when the PR merges. It also tags the merge commit, moves the `next` dist-tag to each `latest` release, and creates the GitHub release for `latest`. The [Experimental Release](.github/workflows/experimental-release.yml) workflow publishes the given branch commit on the `experimental` tag.
|
|
261
|
+
|
|
262
|
+
Both publish jobs run in the `npm-publish` environment, which only `master` can deploy to. The package's npm trusted publishers require that environment.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hubspot/npm-scripts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.1",
|
|
4
4
|
"description": "Scripts for working with npm packages in the HubSpot ecosystem",
|
|
5
5
|
"author": "",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -13,7 +13,9 @@
|
|
|
13
13
|
"lint:local": "eslint . && prettier --list-different './**/*.{ts,tsx,js,json}'",
|
|
14
14
|
"local-dev": "yarn build && cd dist && yarn link && cd .. && tsc -w",
|
|
15
15
|
"prettier:write": "prettier --write './**/*.{ts,js,json}'",
|
|
16
|
-
"release": "yarn tsx ./scripts/release.ts
|
|
16
|
+
"release": "yarn tsx ./scripts/release.ts latest",
|
|
17
|
+
"beta-release": "yarn tsx ./scripts/release.ts next",
|
|
18
|
+
"experimental-release": "yarn tsx ./scripts/release.ts experimental",
|
|
17
19
|
"repo-sync": "yarn tsx ./scripts/repo-sync.ts repo-sync",
|
|
18
20
|
"test": "vitest run --coverage",
|
|
19
21
|
"test-dev": "vitest"
|