@ibid/core v0.1.0
Ibid.
Once again, as before, but better.
Tools to automate your releases and changelogs. Ibid is opinionated in its expectations of your repository layout, but flexible in what it allows you to do with it.
Together with npm workspaces, it offers a minimal but sufficient alternative to Lerna.
npm install --save-dev @ibid/core
Usage
Primarily Ibid provides a command-line interface with the following commands:
ibid version
— Update the versions & changelogs of packages according to git history.ibid publish
— Publish packages, fixing dependencies before & after as appropriate.ibid depend
— Update dependency style between packages. Used internally byibid publish
.
Each command requires an explicit list of directories or glob patterns to find the packages on which it'll be working.
If this is not provided on the command line,
the "workspaces"
list of your package.json
is checked,
and for compatibility the "packages"
of lerna.json
(if present).
You may use .
for the current directory:
npx ibid version .
npx ibid publish foo bar
For an up-to-date list of available command-line options, use:
npx ibid --help
npx ibid version --help
npx ibid publish --help
ibid version
This command works with the following assumptions:
- Your project uses git for source code management.
- Your commit messages follow the Conventional Commits specification.
- The
"version"
field of yourpackage.json
is set to the latest published version. For a package's first version, use--init
to include its whole history. - There is a git tag set for the latest version, by default
either
v{version}
if the package is at the root of the repo or{name}@{version}
if it's in a subdirectory.
Besides the command-line options,
additional ibid version
configuration may be included in a config file ibid.config.{js,mjs,cjs}
,
or one specified by the --config
option.
This allows for in-depth customization of the changelog output in particular.
See config.ts for all supported config values.
When run, the command reads through your git log
,
filtering commits for each project according to its latest release and the files touched by each commit.
Merge commits and any others with messages which do not match the Conventional Commits spec are ignored.
From these commits, the appropriate next version and its changelog are calculated.
An interactive prompt will allow for these version updates to be modified;
use --yes
to skip this in automation.
On success, for each updated package
its CHANGELOG.md
is written or updated and
its package.json
as well as any lockfiles are updated.
Git tags are set as required.
ibid version --amend
If all goes well, the output of ibid version
is perfect just as it is.
For the cases when it isn't, there's --amend
.
This is primarily intended for manually fixing the generated changelogs.
After running ibid version
,
if any changes need to be included in the release,
apply those changes and git add
them.
Then run:
npx ibid version --amend
This will amend the preceding commit and force-update its git tags as needed.
Note that the --amend
option must not be used with any other options, including paths.
ibid publish
This command is only really useful if you're working in a monorepo,
with multiple packages included in the same repository.
In such a case, it often makes sense to use "file:../foo"
paths for your package.json
"dependencies"
during development,
as these ensure that internal dependencies work as intended.
For releases from such a repository, the file:
links need to be fixed for publication.
This is what ibid publish
does;
it'll find all the local dependencies among your packages and fix them before running npm publish
,
and then fix them back to local/relative paths afterwards.
ibid depend
Given a set of packages,
ensures that their internal dependencies are all either --local
, --exact
or --latest
.
Useful if e.g. transitioning a monorepo to use relative dependencies, or to support a custom release pipeline.
3 years ago