anglerci - npm
source link: https://www.npmjs.com/package/anglerci
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
AnglerCI
A validation-only approach to releasing projects using NPM and Git.
Requirements
- Git >= v2.19.2
- NodeJS >= v14.17.0
- NPM >= v8.16.0
Getting started
Install as a dev dependency.
npm i -D anglerci
Verify that a changeset is ready for release. Run this in your PR validation pipeline.
npx angler catch
Publish packages for all modified or unpublished workspaces. This will also create an annotated tag for the current commit. Run this in your release pipeline.
npx angler release
NPM workspaces are used if enabled. The project root is also considered to be a "workspace" (the only one if workspaces are disabled). Only workspaces which are non-private will be considered. Yarn and other workspace providers are not supported at this time.
Workspaces with modifications are detected by diffing each workspace directory against a base-ref. The base-ref is read from the --base-ref
CLI option, GITHUB_BASE_REF
environment variable, or the most recent Git annotated-tag. If no base-ref can be determined, then all workspaces are considered modified.
Workspaces which are unpublished are detected by checking whether the current package.json
version exists the configured NPM registry.
How it works
There are two phases:
-
catch
- Verify all changes are committed.
- Verify versions in modified workspaces have increased.
- Verify CHANGELOG.md contains an entry for the release version.
- Verify CHANGELOG.md correctly documents the version increment (major, minor, or patch).
- Verify local dependency versions have been updated.
- Verify local private dependencies are only used as devDependencies.
- Verify incremented workspace versions are unpublished.
-
release
- Verify all changes are committed.
- Tag the commit which is being released.
- Publish packages for all modified or unpublished workspaces.
The npm install
command automatically creates symlinks for local dependencies (dependencies between workspaces in a monorepo), as long as the dependency version range matches the workspace version. Therefore, the catch
command requires that all local dependencies either have the exact matching version, or range where the minimum version is the current local workspace version.
Changelog updates are only enforced for workspaces that contain a CHANGELOG.md
file. If the file exists, it must contain a heading (any level) with the current version number (leading v
is optional). If the major version has increased, there must be a subheading which contains the word breaking
/major
. Conversely, if there is a breaking
/major
subheading, the major version must be increased. The same is true for a features
/enhancements
/minor
subheading and the minor version. If none of those headings are present, then only the patch version can be incremented. All headings are matched partially, case-insensitively, and pluralization is optional. Some recommended heading keywords for patches are: fixes
, build
, chores
, ci
, docs
, styles
, refactors
, perf
, tests
.
The release
command will publish packages for all modified workspaces, as well as any workspaces with versions that are unpublished (even if not modified). Publication is ordered by interdependency, so any local dependency will be published before its dependents.
The release
command also creates a Git annotated-tag (release-<timestamp>
), so that subsequent releases can identify which workspaces have modifications. The tag is created before publishing. If publishing fails due to a transient error, retrying should still publish the tagged modifications (which will now appear to be unmodified), because the versions will still be unpublished.
Why it works this way
Developers are expected to update versions and changelogs as part of their regular commit work. The PR is treated as the moment of truth (instead of each commit). The tool only catches things you might have forgotten. It does not try to do these things for you. At the end of they day, there is no substitute for agreed-upon conventions and peer review to ensure the quality of commit and changelog messaging.
Solutions like conventional commits seem like a good idea, but (IMO) generally don't decrease the amount of work, speed up iteration, reduce mistakes, or improve the quality of commit messages.
Pros:
- No non-user generated code changes in your CI pipeline.
- No extra commits/PRs for updating version numbers.
- No constraints on commit structuring or changelog formatting.
- No workflow learning curve requiring complicated commit fixups.
Cons:
- Simultaneous PRs may result in version "collisions". When a PR is resolved and merged, the effective "previous" version of all following PRs is updated. Updates may be required to these remaining PRs to re-increment version numbers. This is a minor task, and merging upstream changes will usually be required in follow-up PRs anyway.
Ignoring Modifications
Changes to CHANGELOG.md
files are always ignored, because they have no effect on the build output, and it's useful to be able to update them without causing a new release.
Additional files can be ignored when detecting workspace modifications by adding globs to the config.anglerci.ignore
array in package.json
files. Matching is done with the picomatch package, and works similarly to .gitignore
rules.
{
"config": {
"anglerci": {
"ignore": ["*.md"]
}
}
}
Prerelease
To create a prerelease, include a prerelease part in a package.json
version (eg. 1.0.0-prerelease.0
). When a workspace has a prerelease version, the following things happen:
- No
CHANGELOG.md
section is required for the prerelease version. - A NPM non-latest publish tag (
--tag=prerelease
) is set if thepublishConfig.tag
option in thepackage.json
file is empty.
Use the --prerelease
option to enforce prerelease versions (eg. from unprotected branches).
Git Pre-Push Hook
The catch
command can also be used as a Git pre-push
hook. This is not a replacement for a PR pipeline check, but it can help to call out potential problems earlier.
The recommended approach is to use Husky, so that hooks are installed automatically whenever a developer runs the npm install
command.
- Install Husky.
npm i -D husky
npm pkg set scripts.prepare="husky install"
npm run prepare
- Add the pre-push hook.
npx husky add .husky/pre-push "angler catch"
git add .husky/pre-push
Now the catch
command will run whenever you use the Git push
command.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK