---
name: bootstrap-release
description: Cuts a Bootstrap release from version preparation through npm, GitHub, NuGet, and documentation deployment. Use when a maintainer asks to release, publish, or ship Bootstrap, including prereleases such as v6.0.0-alpha.1.
disable-model-invocation: true
title: bootstrap-release
canonical_url: https://skilld.dev/gh/twbs/bootstrap/bootstrap-release
last_updated: 2026-10-10T08:01:53.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install twbs/bootstrap/bootstrap-release`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/bootstrap-release`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/twbs/bootstrap/bootstrap-release) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/bootstrap-release`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/bootstrap-release --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/bootstrap-release --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Release Bootstrap

Use this workflow for maintainer releases from this repository.
Set the release branch and version once before you start:

```sh
export RELEASE_BRANCH=main
export RELEASE_VERSION=6.0.0-alpha.1
export RELEASE_TAG="v${RELEASE_VERSION}"
```

## Safety rules

- Keep the working tree clean before release work.
- Use `next` for alpha, beta, and release-candidate npm releases.
- Never point npm’s `latest` tag at a prerelease.
- Mark each GitHub prerelease as a prerelease.
- Use a signed git tag.
- Never edit generated SRI hashes.
- Pause before each external write.
- Get explicit approval before you push a tag, publish to npm, publish a GitHub release, or deploy documentation.
- Stop after any failed check.

## Progress

Track these steps:

```text
- [ ] 1. Check release prerequisites
- [ ] 2. Prepare the version
- [ ] 3. Run tests
- [ ] 4. Build release files
- [ ] 5. Commit and merge the release PR
- [ ] 6. Verify and tag the merge commit
- [ ] 7. Publish to npm
- [ ] 8. Publish the GitHub release
- [ ] 9. Deploy documentation
- [ ] 10. Verify the release
```

## 1. Check release prerequisites

1. Confirm the release branch and target version.
2. Confirm all target milestone work is complete.
3. Confirm the working tree is clean.
4. Update the release branch.
5. Use the Node.js version from `.nvmrc`.
6. Install exact dependencies.
7. Confirm npm access.
8. Confirm GitHub access.

```sh
git switch "$RELEASE_BRANCH"
git pull --ff-only origin "$RELEASE_BRANCH"
git status --short
nvm use
npm ci
npm whoami
gh auth status
```

Confirm that the npm account can publish the `bootstrap` package.
Confirm that `.github/workflows/publish-nuget.yml` exists.
Confirm that `.github/workflows/docs-deploy.yml` exists before documentation deployment.

## 2. Prepare the version

Read and save the current version:

```sh
export CURRENT_VERSION=$(node -p "require('./package.json').version")
printf '%s\n' "$CURRENT_VERSION"
```

Skip the version change when it already equals the release version.
Otherwise, preview the version change first:

```sh
npm run release-version -- "$CURRENT_VERSION" "$RELEASE_VERSION" --dry-run --verbose
```

Then apply it:

```sh
npm run release-version -- "$CURRENT_VERSION" "$RELEASE_VERSION" --verbose
```

The script updates:

- `README.md`
- `config.yml`
- `js/src/base-component.ts`
- `package.js`
- `package.json`
- `package-lock.json`
- `scss/_banner.scss`
- `site/data/docs-versions.yml`

It also updates RubyGem version strings from forms such as `6.0.0.alpha.1`.
Review every changed file.
Search for stale version strings outside generated output.

```sh
git grep -Fn "$CURRENT_VERSION" -- \
  . \
  ':!dist' \
  ':!js/dist' \
  ':!_site' \
  ':!package-lock.json'
```

## 3. Run tests

Run the full test suite before the final release build:

```sh
npm test
npm run bundlewatch
```

The browser tests need Chromium.
Install it only when the test output reports that it is missing:

```sh
npx playwright install --with-deps chromium
```

Fix all failures before continuing.

## 4. Build release files

Run the release build:

```sh
npm run release
```

This command performs these tasks:

1. It builds CSS, JavaScript, and TypeScript declarations.
2. It writes SRI hashes to `config.yml`.
3. It builds the documentation site.
4. It creates the distribution ZIP file.
5. It creates the examples ZIP file.

Confirm these files exist:

```text
bootstrap-${RELEASE_VERSION}-dist.zip
bootstrap-${RELEASE_VERSION}-examples.zip
```

Review the complete diff.
Confirm that `config.yml` contains updated `css_hash`, `js_hash`, and `js_bundle_hash` values.
Do not rebuild `dist/` after this check.
If another build changes `dist/`, run `npm run release-sri` again.

## 5. Commit and merge the release PR

Create a release branch from the release branch.
Commit all intended version and generated release changes.

```sh
git switch -c "release-${RELEASE_TAG}"
git add -A
git commit -m "Release ${RELEASE_TAG}"
git push -u origin "release-${RELEASE_TAG}"
gh pr create --base "$RELEASE_BRANCH"
```

Review the staged file list before the commit.
Do not include unrelated changes.
Wait for all required checks.
Merge the PR before tagging.

## 6. Verify and tag the merge commit

Return to the release branch and update it:

```sh
git switch "$RELEASE_BRANCH"
git pull --ff-only origin "$RELEASE_BRANCH"
npm ci
npm run release
git status --short
```

The tracked working tree must stay clean after the repeat build.
The two ZIP files must exist.

After explicit approval, create and push a signed tag:

```sh
git tag -s "$RELEASE_TAG" -m "$RELEASE_TAG"
git push origin "$RELEASE_TAG"
```

Use the version without `v` in package files.
Use the version with `v` for the git tag and GitHub release.

## 7. Publish to npm

Inspect the package contents:

```sh
npm pack --dry-run
```

After explicit approval, publish the prerelease:

```sh
npm publish --tag next
```

Complete npm’s authentication prompt.
Then verify the distribution tags:

```sh
npm dist-tag ls bootstrap
```

`next` must point to `$RELEASE_VERSION`.
`latest` must remain on the newest stable release.

Use the default `latest` tag only for a stable release.

## 8. Publish the GitHub release

Use GitHub’s generated release notes.
Attach both ZIP files.
Mark the release as a prerelease.

After explicit approval, run:

```sh
gh release create "$RELEASE_TAG" \
  --title "$RELEASE_TAG" \
  --generate-notes \
  --prerelease \
  "bootstrap-${RELEASE_VERSION}-dist.zip" \
  "bootstrap-${RELEASE_VERSION}-examples.zip"
```

Publishing the GitHub release starts `.github/workflows/publish-nuget.yml`.
Watch the workflow and confirm that both NuGet packages publish.

## 9. Deploy documentation

The manual documentation workflow builds `_site/`.
It copies the current site over `gh-pages` without deleting older version directories.

After explicit approval, dispatch it from the released branch:

```sh
gh workflow run docs-deploy.yml --ref "$RELEASE_BRANCH"
```

Find and watch the new run:

```sh
gh run list --workflow docs-deploy.yml --limit 1
gh run watch
```

Confirm that the repository Pages source remains the `gh-pages` branch:

```sh
gh api repos/twbs/bootstrap/pages --jq '.build_type, .source'
```

## 10. Verify the release

Verify all release surfaces:

1. Confirm the npm version and distribution tags.
2. Confirm the GitHub release has both ZIP files.
3. Confirm the NuGet workflow passed.
4. Confirm the Bootstrap homepage shows the new version.
5. Confirm the new documentation version loads.
6. Confirm an older documentation version still loads.
7. Confirm the jsDelivr CSS and JavaScript files load.
8. Confirm their SRI hashes match `config.yml`.

jsDelivr can take a few minutes to load a new npm version.

Calculate a published file hash with:

```sh
curl -sL \
  "https://cdn.jsdelivr.net/npm/bootstrap@${RELEASE_VERSION}/dist/css/bootstrap.min.css" \
  | openssl dgst -sha384 -binary \
  | openssl base64 -A
```

Repeat the check for:

- `dist/js/bootstrap.min.js`
- `dist/js/bootstrap.bundle.min.js`

Compare each result with the base64 part of the related `sha384-` value in `config.yml`.

## Recovery

Do not unpublish a bad npm release.
Publish a corrected version.

To move the prerelease distribution tag:

```sh
npm dist-tag add bootstrap@<good-version> next
```

To remove a bad GitHub release and tag:

```sh
gh release delete "$RELEASE_TAG" --cleanup-tag
```

Get explicit approval before either recovery action.
