The packages in this repository have independent versions and are published manually. There is no publication workflow in GitHub Actions. Changesets is used locally to calculate versions and update changelogs; npm is invoked for one explicit workspace at a time.
Three separate states must agree for every release:
- the version in the package's
package.jsonandCHANGELOG.md; - the version published on npm;
- the package-specific Git tag and GitHub Release.
GitHub does not assign npm versions. The package manifest is the source of the
npm version, npm dist-tags identify the stable version of each package, and
GitHub Releases document the corresponding repository commit.
Package tags use the Changesets monorepo convention:
@gouvfr-lasuite/ui-components@1.1.0
@gouvfr-lasuite/ui-tokens@1.0.1
@gouvfr-lasuite/ui-codemod@1.0.1
Do not run changeset publish, npm publish --workspaces or a recursive
workspace publication command. They can publish more packages than intended.
@gouvfr-lasuite/ui-codemod is published only to distribute its one-off CLI
through npx. It is not an application dependency and exposes no JavaScript
import API. Every codemod release pull request must update the exact version in
the documented npx @gouvfr-lasuite/ui-codemod@<version> commands.
- Node 24 (the version pinned in
.nvmrc) and Yarn 1.22.22 —changesetneeds a Node release that canrequire()an ESM module; - a clean checkout with an up-to-date
origin/main; - an npm account allowed to publish the
@gouvfr-lasuitescope; - npm two-factor authentication in
auth-and-writesmode; - an authenticated GitHub CLI (
gh auth status).
Check npm authentication before preparing a publication:
npm whoamiLocal publications do not generate npm provenance. Provenance will be enabled when publishing moves to a dedicated OIDC-enabled CI workflow.
Every functional pull request that should produce a release must include a changeset:
yarn changesetSelect each affected package, choose patch, minor or major, and write a
consumer-facing summary. A components-only changeset looks like this:
---
"@gouvfr-lasuite/ui-components": minor
---
Add the FilePicker component.Changesets are authored release intent. They do not change package versions or publish anything by themselves.
Create a release branch from the latest remote main branch:
git fetch origin
git switch -c release/ui-components-1.1.0 origin/main
yarn changeset statusVersion only ui-components by ignoring the two other packages:
yarn changeset version \
--ignore @gouvfr-lasuite/ui-tokens \
--ignore @gouvfr-lasuite/ui-codemodReview the diff. The release pull request should contain the selected package version and changelog, consumed changesets, and only the internal dependency updates required by Changesets.
Use the equivalent ignore combinations for the other packages:
# ui-tokens only
yarn changeset version \
--ignore @gouvfr-lasuite/ui-components \
--ignore @gouvfr-lasuite/ui-codemod
# ui-codemod only
yarn changeset version \
--ignore @gouvfr-lasuite/ui-components \
--ignore @gouvfr-lasuite/ui-tokensDo not force a dependent package into --ignore when Changesets requires an
internal dependency range update. For example, ui-components currently
depends on ui-tokens through ^1.0.0: token versions within that range can be
released alone, while a change outside that range may require a components
release as well.
A changeset that mixes ignored and selected packages must be split, or all of its packages must be released together.
To release two related packages, ignore only the package that is not part of the release. For example, for tokens and components:
yarn changeset version --ignore @gouvfr-lasuite/ui-codemodTo release every package described by pending changesets:
yarn version-packagesVersions remain independent. The same release pull request may therefore
contain ui-tokens@1.1.0, ui-components@1.0.1 and ui-codemod@1.1.0.
Merge the release pull request before publishing. Do not create commits between the merged release commit, npm publication and tag creation.
Start from a clean, current main branch:
git switch main
git pull --ff-only
git status --short
npm whoamigit status --short must print nothing. Run the complete release validation:
yarn install --frozen-lockfile
yarn lint
yarn build
yarn test
yarn test:ct
yarn build-storybookThe examples below publish ui-components; replace the workspace and version
for another package.
Confirm that the target version does not already exist:
npm view "@gouvfr-lasuite/ui-components@1.1.0" versionAn npm E404 is expected for a new version. Inspect the exact publication
without modifying the registry:
npm publish \
--dry-run \
--workspace="@gouvfr-lasuite/ui-components" \
--access public \
--tag latestPublish the workspace only after reviewing the dry-run file list:
npm publish \
--workspace="@gouvfr-lasuite/ui-components" \
--access public \
--tag latestnpm prompts for the 2FA code interactively. Do not pass an OTP in the command line or store it in shell history.
Verify the published version and its per-package stable dist-tag:
npm view "@gouvfr-lasuite/ui-components@1.1.0" version
npm view "@gouvfr-lasuite/ui-components" dist-tags --jsonPublish packages sequentially so failures are visible and internal dependencies are available before their consumers. For a release of all three packages:
npm publish \
--workspace="@gouvfr-lasuite/ui-tokens" \
--access public \
--tag latest
npm publish \
--workspace="@gouvfr-lasuite/ui-components" \
--access public \
--tag latest
npm publish \
--workspace="@gouvfr-lasuite/ui-codemod" \
--access public \
--tag latestVerify each package with npm view before continuing to the next package.
Publication is not transactional: if tokens succeeds and components fails,
tokens remains published. Fix and retry only the package that failed. A version
accepted by npm is immutable and must never be overwritten.
Create tags only after npm confirms the corresponding publication. For
ui-components@1.1.0:
PACKAGE="@gouvfr-lasuite/ui-components"
VERSION="1.1.0"
TAG="${PACKAGE}@${VERSION}"
git tag -a "$TAG" -m "$TAG"
git push origin "$TAG"Copy the package's CHANGELOG.md section for this version into a temporary
release-notes file, then create the GitHub Release:
gh release create "$TAG" \
--verify-tag \
--title "$PACKAGE $VERSION" \
--notes-file /tmp/ui-components-1.1.0.md \
--latest=falseDo not use --generate-notes: repository-wide generated notes can contain
changes belonging to other packages. GitHub has only one repository-wide
"Latest" release, so every package release explicitly uses --latest=false.
The npm latest dist-tag remains the stable-version authority for each package.
Several package tags and GitHub Releases may point to the same Git commit. A single-package publication creates only one tag and one GitHub Release.
The three new package manifests already contain version 1.0.0, so the first
publication does not run changeset version. After this pull request is merged,
validate the exact merged commit and publish sequentially:
@gouvfr-lasuite/ui-tokens@1.0.0;@gouvfr-lasuite/ui-components@1.0.0;@gouvfr-lasuite/ui-codemod@1.0.0.
Create three package-specific tags and GitHub Releases on that same commit only after all corresponding npm publications have been verified.
- If a dry-run fails, do not publish; correct the release pull request.
- If npm rejects a package before accepting the version, correct the issue and retry that same version.
- If npm accepted the version, never reuse or overwrite it. Release a patch for any correction.
- If npm publication succeeds but tag or GitHub Release creation fails, keep the npm version and finish the missing Git/GitHub metadata on the same commit.
- Deprecate the former packages and archive Cunningham only after the new packages have been installed and validated in a real consumer.