diff --git a/.github/workflows/release-snapshot.yml b/.github/workflows/release-snapshot.yml new file mode 100644 index 0000000000..38c1572a62 --- /dev/null +++ b/.github/workflows/release-snapshot.yml @@ -0,0 +1,55 @@ +name: Release Snapshot + +on: + workflow_dispatch: + inputs: + tag: + description: "Tag used on changeset version and npm package" + required: false + type: string + +jobs: + get-snapshot-tag: + runs-on: ubuntu-latest + permissions: + contents: write + id-token: write + steps: + - name: Split branch name + id: split + env: + BRANCH: ${{ github.ref_name }} + run: echo "fragment=${BRANCH##*snapshot-}" >> $GITHUB_OUTPUT + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Get last author info + id: author + run: | + echo "authorName=$(git log -1 --pretty=format:'%an')" >> $GITHUB_OUTPUT + echo "authorEmail=$(git log -1 --pretty=format:'%ae')" >> $GITHUB_OUTPUT + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 18 + cache: yarn + - name: Install Dependencies + run: yarn install --frozen-lockfile + - name: Create snapshot release and publish to npm + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + SNAPSHOT_TAG: ${{ inputs.tag || steps.split.outputs.fragment }} + USERNAME: ${{ steps.author.outputs.authorName }} + EMAIL: ${{ steps.author.outputs.authorEmail }} + run: | + yarn changeset version --snapshot $SNAPSHOT_TAG && yarn --mode="update-lockfile" + yarn ci + git config --global user.name "$USERNAME" + git config --global user.email "$EMAIL" + git add . + git commit -m "chore: snapshot release $SNAPSHOT_TAG" + npm set //registry.npmjs.org/:_authToken=$NPM_TOKEN + yarn changeset publish --tag $SNAPSHOT_TAG + git push origin HEAD + git push --tags diff --git a/.storybook/guides/releasing.mdx b/.storybook/guides/releasing.mdx index dd557d7b25..a95aec9ea5 100644 --- a/.storybook/guides/releasing.mdx +++ b/.storybook/guides/releasing.mdx @@ -39,3 +39,35 @@ This allows for maintainers and contributors to review the proposed version and ## Prereleases Information about Changesets and prereleases can be found [here](https://github.com/changesets/changesets/blob/main/docs/prereleases.md). + +### Snapshot releases + +Snapshot releases are a way to release changes for testing without updating versions. Information about Changesets and snapshot releases can be found [here](https://github.com/changesets/changesets/blob/main/docs/snapshot-releases.md). + +Spectrum CSS snapshot releases can be published via two different workflows: + +- Preferred: via a GitHub Action, which is invoked by any contributor who has `write` access to the Spectrum CSS GitHub repository. +- Alternate: locally, from a contributor's computer (requires npm authorization and publish privileges). + +#### Snapshot releases via GitHub Actions + +Our recommended workflow for publishing snapshot releases is through our [GitHub Action](https://github.com/adobe/spectrum-css/blob/main/.github/workflows/release-snapshot.yml). Releasing snapshots via this method has several advantages over local publishing and poses less risk for publication failures. +Any contributor with `write` access to the Spectrum CSS repository can publish snapshot releases. + +**Steps for publishing snapshot releases** + +1. First, ensure that the branch from which you want to publish has added a changeset so that you actually have something to release. No changeset = nothing to release. +2. Next, navigate to the "Actions" tab near the top of the GitHub interface, and click-through to see all available workflows for the project. +3. In the "Actions" navigation on the left side of the interface, choose "Release snapshot" from the list of available workflows. +4. In this "Release snapshots" screen, you'll see a list of previous snapshot worklows that have been run. In the upper right part of the screen, you should see a **"Run Workflow"** button. Clicking the button will open a popover. +5. In the popover, choose the branch from which you wish to release the snapshot ("Use workflow from"), and in the text field, type in a meaningful tag name (example: `s2-action-button`), or optionally, leave this field blank and the workflow will attempt to automatically create a tag name based on your branch's name. +6. The workflow should then begin to run, using `changeset version` to version the affected components with the proper snapshot version name and tags (based upon what you specified in the text field). The workflow also automatically publishes to npm with the snapshot version and tags. +7. Once complete, navigate to npm and check that your snapshot has been published. + +**Alternate steps for publishing snapshot releases locally** + +1. First, ensure that the branch from which you want to publish has added a changeset so that you actually have something to release. No changeset = nothing to release. +2. On the command line, be sure that you've checked out that branch and are on it currently. +3. Run `yarn changeset version --snapshot SOME_MEANINGFUL_TAG_NAME_HERE && && yarn --mode="update-lockfile"` to update the affected package versions to 0.0.0-SOME_MEANINGFUL_TAG_NAME_HERE-THE_TIME_YOU_DID_THIS +4. Run `yarn ci` to run a full, cacheless build. +5. Run `yarn changeset publish --tag SOME_MEANINGFUL_TAG_NAME_HERE` to invoke the publish step. This will publish your versioned packages to npm using the `SOME_MEANINGFUL_TAG_NAME_HERE` tag instead of `latest` on npm which is **VERY** important for the npm ecosystem.