@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 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 release"
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 patch version to latest
95
- yarn release -v=patch -t=latest
113
+ # Release a minor version to latest
114
+ yarn release -v minor
96
115
 
97
- # Release a minor version to next (beta)
98
- yarn release -v=minor -t=next
116
+ # Release a beta, choosing the increment from a prompt
117
+ yarn beta-release
99
118
 
100
- # Release an experimental version
101
- yarn release -v=patch -t=experimental
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=patch -t=latest -d
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 (`patch`, `minor`, `major`, `prerelease`)
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 and requires 2FA codes
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.4",
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 release",
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"