Skip to content

RELEASES.md

Latest commit

 

History

History
197 lines (133 loc) · 8.76 KB

RELEASES.md

File metadata and controls

197 lines (133 loc) · 8.76 KB

Release process guide

Edits to this file show up on both GitHub and in Storybook.

This guide explains the release process for the UNDRR Mangrove component library.

Overview

Releases use manual versioning with automated npm publishing. You choose the version number, update package.json, tag the release, and CI handles the rest.

Why not automated semantic-release?

We follow Conventional Commits for consistent, readable commit history, but we don't use semantic-release for automated version bumps. As a rapidly evolving component library, strict semver automation would produce excessive major version bumps — individual component breaking changes happen frequently during active development, but don't warrant a major library release when the change is scoped to a single component. Manual versioning gives us control over when to signal a significant release to consumers.

Release steps

1. Prepare the release

# Make sure everything passes
yarn test
yarn lint

Review any components whose markup changed since the last release and update their HTML examples in scripts/ai-manifest/component-data.js. If utility classes were added or removed, update scripts/ai-manifest/css-utilities.js. These curated files feed the AI component manifest and can drift from reality between releases.

You can check for drift by running a full build and then validating the manifest:

yarn build
yarn validate-manifest

The validation checks for stale curated data keys, accessibility anti-patterns in HTML examples, and PropTypes coverage.

2. Update the version

Edit version in package.json to the new version number:

{
  "version": "1.3.0"
}

Version guidance:

  • Patch (1.2.14 → 1.2.15): bug fixes, dependency updates, minor style tweaks
  • Minor (1.2.14 → 1.3.0): new components, new features, non-breaking enhancements
  • Major (1.2.14 → 2.0.0): broad breaking changes across multiple components, API redesigns, major dependency upgrades (e.g., React major version)

3. Update CDN links in documentation

yarn update-cdn-version            # updates docs to reference new version
yarn update-cdn-version --dry-run  # preview changes first

This updates CDN URLs in README.md, MDX docs, and story files from the old version to the new one.

4. Commit, tag, and push

git add .
git commit -m "chore(release): v1.3.0"
git tag v1.3.0
git push origin main --tags

5. Monitor the publish

The tag push triggers the NPM Publish workflow, which automatically:

  • Builds the project
  • Packages distribution files and SCSS sources
  • Publishes to the npm registry

6. Create a GitHub Release

Go to GitHub Releases and create a release from the tag. Include a summary of changes — you can use the "Generate release notes" button for a starting point.

7. Verify

8. Update the Drupal theme (if needed)

If component JS or CSS changed:

yarn build

Copy built JS from dist/components/ to undrr_common/js/mangrove-components/ in the Drupal theme. If CSS changed, manually copy compiled CSS to each child theme's css/mangrove/mangrove.css.

Manual npm publish (fallback)

If automated publishing fails, you can trigger it manually:

  1. Go to Actions → Publish to NPM Registry
  2. Click "Run workflow"
  3. Optionally enter a specific git tag (leave empty for latest)

Component changelogs vs project releases

Mangrove tracks changes at two levels:

  • Component changelogs (in each component's MDX file): Track per-component version history. Update these whenever a PR modifies a component's behavior, API, or appearance. See the component standards for the required format (source: stories/Documentation/ComponentContribution.mdx → "Changelog format").
  • Project releases (GitHub Releases): Track library-wide releases. Created during the release process above.

Component changelogs and project releases serve different audiences — component changelogs help developers working with a specific component, while project releases help consumers of the npm package understand what changed between versions.

Commit message conventions

We use Conventional Commits for readable history and PR title validation, even though version bumps are manual:

Prefix Purpose
feat: New feature or component
fix: Bug fix
docs: Documentation only
chore: Maintenance, dependencies
refactor: Code restructuring
test: Test additions or changes
build: Build system or tooling
ci: CI/CD configuration

PR titles are validated by CI — see .github/workflows/pr-title-check.yml.

Package contents

Published npm packages include:

  • /components/**/* — compiled React components (ES modules)
  • /css/**/* — compiled CSS files
  • /js/**/* — compiled vanilla JavaScript files
  • /scss/**/* — source SCSS files
  • /error-pages/**/* — static error page templates
  • /fonts/**/* — Mangrove icon font

CDN distribution

The project maintains a dist branch for CDN/static hosting via the UNDRR static assets repo. This branch is automatically updated on every push to main (not just releases).

  • Content: compiled assets only (no source, no git history)
  • Use case: static sites with no build process

Example CDN URLs:

# Latest (from dist branch, updated on every push to main)
https://assets.undrr.org/testing/static/mangrove/latest/css/style.css
https://assets.undrr.org/testing/static/mangrove/latest/components/MegaMenu.js

# Versioned (from tagged releases)
https://assets.undrr.org/static/mangrove/1.3.3/css/style.css
https://assets.undrr.org/static/mangrove/1.3.3/components/MegaMenu.js
https://assets.undrr.org/static/mangrove/1.3.3/js/tabs.js

CI/CD configuration

File Purpose
.github/workflows/npm-publish.yml npm publish on tag push (v*)
.github/workflows/dist.yml Update dist branch on main push
.github/workflows/storybook.yml Build and deploy Storybook to GitHub Pages
.github/workflows/chromatic.yml Visual regression testing
.github/workflows/pr-title-check.yml Validate PR titles follow Conventional Commits

npm trusted publishing

npm publishing uses OIDC trusted publishing instead of long-lived access tokens. GitHub Actions authenticates directly with npm using a short-lived OIDC token — no NPM_TOKEN secret is needed.

This is configured in two places:

  • npmjs.com: package settings → Trusted Publisher links the unisdr/undrr-mangrove repo and npm-publish.yml workflow
  • Workflow: id-token: write permission and --provenance flag on npm publish

Published packages include a provenance attestation that cryptographically links the npm package to its source commit and build.

Required GitHub secrets

  • GITHUB_TOKEN — built-in, used by workflows
  • CHROMATIC_PROJECT_TOKEN — for visual regression testing (optional)

No npm token is required — trusted publishing handles authentication via OIDC.

Troubleshooting

Symptom Cause Fix
npm publish fails with 403/404 Trusted publisher not configured or misconfigured Check package settings — repo, workflow filename, and environment must match
npm publish fails with OIDC error Missing id-token: write permission in workflow Ensure the job has permissions: id-token: write
npm publish fails with Corepack error Missing corepack enable step in workflow Check npm-publish.yml has the "Enable Corepack" step
CDN not updated dist.yml workflow failed Check the workflow run; it runs on every push to main
PR title rejected Doesn't follow Conventional Commits format Use feat:, fix:, docs:, chore:, etc. prefix
Chromatic skipped Commit or PR title contains [skip chromatic] Intentional; remove the flag to run visual tests