@hubspot/npm-scripts 0.3.4-beta.0 → 0.3.4-experimental.0

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,86 @@ 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
115
+
116
+ # Release a beta, choosing the increment from a prompt
117
+ yarn beta-release
96
118
 
97
- # Release a minor version to next (beta)
98
- yarn release -v=minor -t=next
119
+ # Release a patch to the previous major version, from previousBranch
120
+ yarn previous-release -v patch
99
121
 
100
- # Release an experimental version
101
- yarn release -v=patch -t=experimental
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, and that the branch is pushed: it has an upstream and `HEAD` matches `origin/<branch>`
159
+ 2. Show the expected 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, print its URL, and stream it with `gh run watch`
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.
112
167
 
113
168
  #### Features
114
169
 
115
170
  - **Branch protection**: Ensures releases are made from the correct branch
116
171
  - **Version validation**: Checks local version against published versions
117
- - **Interactive prompts**: Confirms release details and requires 2FA codes
172
+ - **Interactive prompts**: Confirms release details before publishing
118
173
  - **Automatic tagging**: Creates git tags and pushes to repository
119
174
  - **GitHub integration**: Opens PR and release pages automatically
175
+ - **Clean working tree required**: Fails before changing anything if `git status` shows uncommitted changes, because the rollback runs `git checkout .`
120
176
  - **Rollback support**: Cleans up on failure
121
177
 
122
178
  ### Repo Sync Script Builder (`buildRepoSyncScript`)
@@ -183,3 +239,20 @@ yarn repo-sync -v=1.0.0 -d
183
239
  - **Cleanup support**: Removes temporary directories after completion
184
240
 
185
241
  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`.
242
+
243
+ ## Releasing `@hubspot/npm-scripts`
244
+
245
+ 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`.
246
+
247
+ ```bash
248
+ # latest (from master): opens a release PR, and merging it publishes
249
+ yarn release -v patch
250
+
251
+ # next (from master)
252
+ yarn beta-release -v minor
253
+
254
+ # experimental (from a pushed feature branch): runs the Experimental Release workflow
255
+ yarn experimental-release
256
+ ```
257
+
258
+ 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hubspot/npm-scripts",
3
- "version": "0.3.4-beta.0",
3
+ "version": "0.3.4-experimental.0",
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"