title |
---|
Release Lifecycle Hooks |
The following hooks are all called during various release commands (ex: latest
, next
, canary
, shipit
).
These hooks is where the publishing of your package actually happens.
{{TOC}}
Called before auto pr-check
is ran/
Context Object:
pr
- All github information related to the PR
auto.hooks.prCheck.tapPromise("NPM", async ({ pr }) => {
// Do stuff
});
Happens before shipit
is run.
This is a great way to throw an error if a token or key is not present.
Context Object:
releaseType
(latest
|old
|next
|canary
) - The type of releaseshipit
will attempt to make.dryRun
- Whether the run is a dry run
auto.hooks.beforeShipIt.tapPromise("NPM", async (context) => {
if (!process.env.NPM_TOKEN) {
throw new Error("NPM Token is needed for the NPM plugin!");
}
});
Other examples:
- all-contributors - Manage manual contribution additions in PRs
- gh-pages - Publishes your docs to GitHub pages on a
latest
release - npm - Exits early when lerna won't need to make a release
Ran before the changelog
command commits the new release notes to CHANGELOG.md
.
Useful for modifying the changelog as a whole or creating extra changelog
files.
These files can be apart of the commit that updates the changelog.
bump
- the semver bumpcommits
- the commits in the changelogcurrentVersion
- version that was just releasedlastRelease
- the version before the current versionreleaseNotes
- generated release notes for the release
auto.hooks.beforeCommitChangelog.tap(
"MyPlugin",
async ({ currentVersion, commits, releaseNotes, lastRelease }) => {
// do something
}
);
Other examples:
- In Core: Create major version branches when
major
happens - npm - Create sub-package changelogs
Ran after the changelog
command adds the new release notes to CHANGELOG.md
.
Useful for getting extra commits into a release before publishing.
bump
- the semver bumpcommits
- the commits in the changelogcurrentVersion
- version that was just releasedlastRelease
- the version before the current versionreleaseNotes
- generated release notes for the release
auto.hooks.afterChangelog.tap(
"MyPlugin",
async ({ currentVersion, commits, releaseNotes, lastRelease }) => {
// do something
}
);
Other examples:
- all-contributors - Make a commit for new contributions
Ran before the package has been versioned. Useful for iterating through the list of commits that are going to be included in the current release, and applying/overriding the version bump (major/minor/patch) labels applied to the PRs corresponding to those commits.
auto.hooks.beforeVersion.tapPromise(
"NPM",
async ({ dryRun, commits, from }) => {}
);
Increment the version the package.
This is a good opportunity to git tag
the release also.
This hooks is required for plugin that facilitate publishing.
Here npm
does it for us.
auto.hooks.version.tapPromise("NPM", async ({ bump, dryRun, quiet }) => {
if (dryRun) {
const { version } = await loadPackageJson();
console.log(inc(version, bump));
return;
}
await execPromise("npm", [
"version",
bump,
"-m",
"Bump version to: %s [skip ci]",
]);
});
If you're implementing this hook for a publishing plugin you must commit (with
[skip ci]
in the message) and tag the version.
Ran after the package has been versioned.
Examples:
- In Core: Used to exit early is new commits are detected on the remote
- brew - Create a new brew formula once the package a=has been versioned
auto.hooks.afterVersion.tapPromise("NPM", async ({ dryRun }) => {});
Publish the package to some package distributor. You must push the tags to github! This hooks is required for plugin that facilitate publishing.
auto.hooks.publish.tapPromise("NPM", async ({ bump }) => {
await execPromise("npm", [
"version",
bump,
"-m",
"Bump version to: %s [skip ci]",
]);
await execPromise("npm", ["publish"]);
await execPromise("git", [
"push",
"--follow-tags",
"--set-upstream",
auto.remote,
"$branch",
]);
});
Ran after the package has been published.
Used to publish a canary
release.
In this hook you get the semver bump and the unique canary
postfix ID.
You can either return a string value of just the version or an object containing the following which will be rendered within and HTML details element.
newVersion
- The version published in thecanary
release or a header for the details element.details
- The body of the details element
auto.hooks.canary.tapPromise(
this.name,
async ({ bump, canaryIdentifier, dryRun, quiet }) => {
const lastRelease = await auto.git!.getLatestRelease();
const current = await auto.getCurrentVersion(lastRelease);
const nextVersion = inc(current, bump as ReleaseType);
const isScopedPackage = name.match(/@\S+\/\S+/);
const canaryVersion = `${nextVersion}-canary${canaryIdentifier}`;
await execPromise("npm", [
"version",
canaryVersion,
"--no-git-tag-version",
]);
await execPromise("npm", ["publish", "--tag", "canary"]);
auto.logger.verbose.info("Successfully published canary version");
return canaryVersion;
}
);
canary
version should not produce any of the following:
- a new tag
- any commits
- a new release
- any changes to changelogs
It is "test" release and has no impact on any of your real releases.
Used to publish a next
release.
In this hook you get the semver bump and a list of all pre-releases made.
This hook must add the version it published to preReleaseVersions
and return it.
preReleaseVersions
- A list of prerelease version publish during the current runbump
- The version bump to apply
import {
determineNextVersion,
execPromise,
getCurrentBranch,
} from "@auto-it/core";
auto.hooks.next.tapPromise(
this.name,
async (preReleaseVersions, { bump, dryRun }) => {
const branch = getCurrentBranch() || "";
const lastRelease = await auto.git.getLatestRelease();
const current =
(await auto.git.getLastTagNotInBaseBranch(branch)) ||
(await auto.getCurrentVersion(lastRelease));
// Use this helper function to determine the next prerelease version
const prerelease = determineNextVersion(lastRelease, current, bump, "next");
// Make sure to add the version to the list
preReleaseVersions.push(prerelease);
if (dryRun) {
return preReleaseVersions;
}
// Create a new tag for it
await execPromise("git", [
"tag",
prerelease,
"-m",
`"Tag pre-release: ${prerelease}"`,
]);
// Push the tag
await execPromise("git", ["push", auto.remote, "--tags"]);
return preReleaseVersions;
}
);
next
version should not produce any of the following:
- any commits
- any changes to changelogs
Ran when trying to make a release during the release
command has run.
This async hook gets the following arguments:
dryRun
- Whether this is a dry runfrom
- Commit to start calculating the version fromnewVersion
- The version being releasedisPrerelease
- Whether the release being made is a prereleasefullReleaseNotes
- The generated release notes for all of the commitscommits
- The commits included in the release
auto.hooks.makeRelease.tapPromise("MyPlugin", async (options) => {
if (!options.dryRun) {
this.logger.log.info(`Releasing ${options.newVersion} to GitHub.`);
return this.git!.publish(
options.fullReleaseNotes,
options.newVersion,
options.isPrerelease
);
}
});
Other examples:
- npm - Create GitHub releases for sub-packages
Ran after the release
command has run, creating a new release on GitHub.
This async hook gets the following arguments:
lastRelease
- the version that existed prior to the current releasenewVersion
- version that was just releasedcommits
- the commits in the releasereleaseNotes
- generated release notes for the releaseresponse
- the response returned from making the release
auto.hooks.afterRelease.tapPromise(
"MyPlugin",
async ({ lastRelease, newVersion, commits, releaseNotes, response }) => {
// do something
}
);
Other examples:
- release - Post comment on issues and PRs about release version
- s3 - Upload release assets to s3
- slack - Post the release notes to slack
- twitter - Create a tweet about the new release
- upload-assets - Uses hook to upload files to newly created release
Ran after the shipit
command has run.
data
newVersion
- The new version that was releasecommits
- the commits in the releasecontext
- The type of release that was created (latest
,next
,canary
, orold
)dryRun
- Whether the run is a dry run
auto.hooks.afterShipIt.tap("MyPlugin", async ({ context }) => {
// do something
});
Other examples:
- gradle - Uses hook to setup next snapshot version