mergePreview()
Preview from code what the merge of the pull request of the CI job releases, and know whether its release would fail.
Signature
ts
function mergePreview(options?: MergePreviewOptions): Promise<ReleaseReport>Options: MergePreviewOptions, the options of the release job that change the release (type, preid, tag, publish, configName, groups...), the outputs of the preview (comment, check), commitlint: true to lint the commits, and changelog: true for the changelog entries of the release.
Behavior
- Computes the release of the merge as
release()will run it on the target branch, and writes nothing: no version, changelog, commit, tag, push, publish nor hook. See Merge Preview. - In the pipeline of a pull request, comments it (unless
comment: false) and, withcheck: true('auto': on GitHub only), sets the commit statusrelizy/merge-preview: off by default. Without comment nor check, the preview is only computed: nothing is posted (outside a pull request pipeline, nothing is posted either). The report is still written asrelease.reportsays: in GitHub Actions, the outputs and the summary of the job (release.report.github: falseturns them off). - Resolves the
ReleaseReportof the preview:released: false,dryRun: true,statusreleasedwhen the merge releases a package,nothingotherwise, the versions and tags by version group (release), andmergePreview:pullRequest, the number of the pull request (kept for the reports of relizy 2), andpullRequestDetails, the pull request itself:provider,kind,number(the same),title,targetBranch,merged. None outside a pull request pipelinebranch, the squash mode (squash),packages(each released package: versions, reason, commits, from the pull request or not),squashPackageswhen a squash merge would release other versionsproblems,commitlint(the commits failing the commitlint of the project: warnings, they never reject;mergetells whether the merge keeps each of them:kept,squashwith a squash merge only,droppedby the squash merge),warnings,publish(enabled,distTag),changelogs(withchangelog: true),posted(comment,status), and themarkdownof the comment
- Its steps are the
merge-previewstep of the progress events (onProgress): onestep:start/step:donepair per part of the preview (the merge, the release, the checks, the comment, the commit status). - Rejects with a
MergePreviewErrorwhen the release of the merge would fail (a version or a tag already taken, a squash commit that is not a Conventional Commit, an error of the config): its message lists the problems, and itsreportis the report of the preview.
Example
ts
import { mergePreview, MergePreviewError } from 'relizy'
try {
const report = await mergePreview({ tag: 'next', comment: false })
console.log(report.mergePreview?.markdown)
}
catch (error) {
if (error instanceof MergePreviewError) {
console.error(error.message)
}
throw error
}Only computed, for an application showing it:
ts
import { mergePreview, MergePreviewError } from 'relizy'
const report = await mergePreview({ comment: false, check: false, changelog: true })
.catch((error: unknown) => {
// The release would fail: the report lists the problems
if (error instanceof MergePreviewError && error.report) {
return error.report
}
throw error
})
for (const pkg of report.mergePreview?.packages ?? []) {
console.log(pkg.name, pkg.oldVersion, '->', pkg.newVersion, pkg.reason)
}