feat: switch to changesets release PR workflow - #951
Conversation
kdaviduik
changed the title
018b0c0 to
c6173bc
Compare
c6173bc to
215a2cc
Compare
|
|
||
| If your PR doesn't need a new npm release (docs-only changes, test updates, CI changes, etc.), just don't include a changeset. No changeset = no release PR = no npm publish. | ||
|
|
||
| ### Rollback (update `latest` CDN version) |
There was a problem hiding this comment.
It's extremely rare that we'd need/want to do this, but this was in the old DEPLOYING.md and is helpful to have just in case, especially the info like how to purge the CDN cache
| @@ -1,29 +1,31 @@ | |||
| name: Release new NPM version | |||
| name: Release | |||
There was a problem hiding this comment.
Overall this is very similar to Hydrogen's release.yml workflow
215a2cc to
5ebe7c7
Compare
| "fixed": [], | ||
| "linked": [], | ||
| "access": "restricted", | ||
| "access": "public", |
There was a problem hiding this comment.
Must be public since this is a public package on npm, docs
5ebe7c7 to
e8de275
Compare
| uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 | ||
| with: | ||
| fetch-depth: 1 | ||
| fetch-depth: 0 |
There was a problem hiding this comment.
Why
fetch-depth: 0instead of the default1?
fetch-depth: 1 (the checkout action's default) does a shallow clone — only the latest commit, no history, no tags. fetch-depth: 0 fetches the entire git history including all branches and tags.
This is required here because the changesets/action step (changeset version + changeset publish) depends on:
- Git tags — Changesets uses tags to determine which version to publish and to create GitHub releases. A shallow clone doesn't fetch them.
- Full commit history — When generating the release PR, Changesets inspects commits since the last release to build changelog entries and determine which packages changed.
With the default fetch-depth: 1, you'd hit errors like "could not find tag" and end up with empty/incomplete changelogs.
e8de275 to
1873514
Compare
| git push && git push --tags | ||
| ``` | ||
| 8. Create and merge the PR | ||
| 9. Deploy via [Shipit](https://shipit.shopify.io/shopify/buy-button-js/production) |
There was a problem hiding this comment.
General Q - Do we want these here? Are they better as an internal doc?
There was a problem hiding this comment.
Yeah I debated this, and I think this section might be worth having in an internal doc/incident playbook instead. This info was already present before in DEPLOYING.md - I just moved it to CONTRIBUTING.md for this PR. In general though I think it doesn't hurt to have info like this co-located with the repo as if ownership changes, it's easy for playbooks to become out of date or have the information be hard to find. But I could go either way on this one!
| name: Production release to npm | ||
| runs-on: ubuntu-latest | ||
| if: github.event.pull_request.merged == true && !contains(github.event.pull_request.title, '[ROLLBACK]') && !contains(github.event.pull_request.title, '[DOCS]') | ||
| if: github.repository_owner == 'Shopify' |
There was a problem hiding this comment.
I don't think I've seen this one before. Is this to ensure that someone who forked the repo isn't able to push to npm or is it something else? I figured this wouldn't be possible anyways because you need GH secrets to be able to push.
There was a problem hiding this comment.
Yeah to my knowledge you're right and forks wouldn't be able to push to npm anyway because of the lack of secrets. But apparently with this check (and it's also present in Hydrogen for example) it just makes this CI job sort of early return/stop cleanly in case it's running on a fork, rather than having this job fail later on. So not necessary but just cleaner
Replace the direct-publish npm release workflow with the two-mode changesets/action pattern: pending changesets create a release PR titled "[ci] release"; merging it triggers npm publish. Why: the previous workflow published to npm immediately on PR merge. This made it impossible to batch multiple changes from separate PRs in a single npm release, and also meant that authors who didn't realize that PR merge = release could accidentally publish to npm a change that isn't ready for release. The release PR pattern creates an intermediate PR showing exactly what will be published before it goes out.
1873514 to
94d6858
Compare
2 participants
Part of https://github.com/Shopify/developer-tools-team/issues/1195
Summary
DEPLOYING.md(info is now in CONTRIBUTING.md instead))CLAUDE.mdandAGENTS.mdas symlinks toCONTRIBUTING.mdso that we have a single source of truth for all of this information and agents automatically "see" itnpm-release.ymlfor the changesets release PR pattern: pending changesets create a[ci] releasePR; merging that PR triggers npm publishWhy
The previous workflow published to npm immediately on PR merge. This made it extremely un-ergonomic to batch multiple merchant-facing changes in a single release, and required workarounds (like adding
[DOCS]to the PR title) to avoid releasing a new Buy Button JS version when there were zero code changes. The release PR pattern (used by Hydrogen and many Shopify repos) creates an intermediate PR showing exactly what will be published and is the more modern, preferred way of managing releases.External prerequisite
SHOPIFY_GH_ACCESS_TOKENhas been provisioned via github-actions-access-provider#2613