previewRelease() and previewChangelog()
Compute what the next release does as data, without writing anything - the versions, the bump type, the commits and the reason of each package, the tags, the steps and the changelog entries.
function previewRelease(options?: PreviewReleaseOptions): Promise<ReleasePreview>
function previewChangelog(options?: PreviewChangelogOptions): Promise<PreviewChangelog[]>They are the implementation of the preview_release and preview_changelog tools of the MCP server, for a program that shows the release before it runs (an app, a dashboard). They write nothing, run no hook, ask nothing, and only use the network when you ask: fetchTags, checks, changelog.contributors. The profile, the config and the overrides apply as in release().
They print nothing: the warnings of the computation are in warnings (with the default level of the logger, or the logLevel of overrides), and the level of the logger is back to the one of before once they end. Several previews can run at the same time (several projects of an application): each one gets its own warnings.
Options
| Option | Description |
|---|---|
cwd | Root of the project, process.cwd() by default |
configName, config | The config to load (a name or a path, see Multiple configs), or a config already resolved |
profile, overrides | A profile, and options applied over the config ({ release: { social: false } }) |
type, preid, suffix, canary | What --minor, --preid, --suffix and --canary do |
from, to, force, groups | The range of the commits, --force, and the version groups to preview |
fetchTags | Run git fetch --tags first, as the release does. Default: false, the local tags are used |
checks | Check what would make the release fail: a version already published, a tag already on the remote. Default: false, it uses the network |
changelog | Add the changelog entries to the preview: true for all of them, { package: 'core', contributors: false } for one (contributors may query the GitHub API) |
ReleasePreview
interface ReleasePreview {
profile?: string // the profile applied
canary: boolean
versionMode: 'unified' | 'selective' | 'independent' | 'standalone' | 'groups'
released: boolean // at least one package is released
sets: PreviewSet[] // the project, or one per version group
tags: string[] // the git tags the release creates
steps: PreviewStep[] // every step of release, in order, with whether it runs
problems: { kind: string, message: string }[] // with `checks`: what would make the release fail
warnings: string[]
changelogs: PreviewChangelog[] // with `changelog`
}
interface PreviewSet {
group?: string
title: string
versionMode: 'unified' | 'selective' | 'independent' | 'standalone'
released: boolean
oldVersion?: string // unified and selective: the root version
newVersion?: string
bump?: PreviewBumpType
tag?: string
fromTag?: string
commits: PreviewCommit[]
packages: PreviewPackage[]
notReleased: string[] // no commit, no bumped dependency
}
interface PreviewPackage {
name: string
path: string // relative to the project
private: boolean
oldVersion: string
newVersion: string
bump: 'major' | 'minor' | 'patch' | 'premajor' | 'preminor' | 'prepatch' | 'prerelease' | 'graduation' | 'canary'
tag?: string
reason: 'commits' | 'dependency' | 'graduation' | 'forced' | 'unified'
commits: PreviewCommit[]
dependency?: { chain: string[], group?: string, outOfRange?: { name: string, field: string, range: string | null, newVersion: string } }
breakingPeerDependency?: string
}
interface PreviewStep {
name: 'bump' | 'changelog' | 'publish' | 'commit-and-tag' | 'push' | 'provider-release' | 'social' | 'pr-comment'
label: string
enabled: boolean
disabledBy?: string // `release.social`, `release.canary`
}
interface PreviewCommit {
hash?: string // the full hash (none for the squash commit simulated by a merge preview)
shortHash: string
type: string // `feat`, `fix`...
scope: string // empty without scope
description: string
breaking: boolean
author?: string
}
interface PreviewChangelog {
label: string
file: string // `packages/core/CHANGELOG.md`
packageName: string
content: string // the markdown added at the top of the file
}reason: 'dependency' comes with dependency: the chain of dependencies leading to the package, the version group releasing the dependency when it is another one, and for a version out of the published range of the package (a peer dependency, a workspace:*...) the range, the field and the new version. breakingPeerDependency names a peer dependency making a breaking change that the published range of the package rejects. The step names are the ones of the hooks and of the progress events.
Examples
import { previewChangelog, previewRelease } from 'relizy'
const preview = await previewRelease({ profile: 'beta', checks: true })
if (!preview.released) {
console.log('Nothing to release')
}
for (const set of preview.sets) {
console.log(set.title, set.oldVersion, '->', set.newVersion)
for (const pkg of set.packages) {
console.log(` ${pkg.name} ${pkg.oldVersion} -> ${pkg.newVersion} (${pkg.bump}, ${pkg.reason}, ${pkg.commits.length} commits)`)
}
}
for (const problem of preview.problems) {
console.error(problem.message)
}
const changelogs = await previewChangelog({ profile: 'beta', package: 'root' })
console.log(changelogs[0]?.content)The same preview as the MCP tools: previewRelease({ changelog: true }) for the versions and the changelogs in one computation. previewChangelog({ package }) throws when the release does not release this package: the message lists the released ones.