Distillation

Date: Aug 25, 2026

• 🟡 (10:33) Research finding—src/commands/prepare.ts:1-69 imports filesystem helpers (existsSync, fsPromises), path helpers (join, relative), shell-quote, simple-git types, yargs types, dry-run isolation (createDryRunIsolation, safeFs), configuration/versioning utilities, changelog helpers, git helpers, GitHub Actions output helpers, buildReleaseCommandEnv, tracing, version utilities, automatic target-version bumping (runAutomaticVersionBumps), and publishMainHandler/PublishOptions from ./publish.
• 🟡 (10:33) Research finding—src/commands/prepare.ts:71-79: prepare command is prepare [NEW-VERSION]; aliases are p, prerelease, prepublish, prepare, and release; description is 🚢 Prepare a new release branch. DEFAULT_BUMP_VERSION_PATH is join('scripts', 'bump-version.sh'); AUTO_VERSION_MIN_VERSION is '2.14.0'.
• 🟡 (10:33) Research finding—src/commands/prepare.ts:81-82: AUTO_BUMP_MIN_VERSION is '2.21.0', the minimum Craft version for automatic version bumping from targets.
• 🟡 (10:33) Research finding—src/commands/prepare.ts:84-135: yargs builder defines positional NEW-VERSION as a string: it accepts a semver string such as "1.2.3", bump types "major", "minor", or "patch", "auto" for conventional-commit-based automatic version determination, "calver" for calendar versioning, or omission to use versioning.policy from .craft.yml. Options: --rev/-r string source revision (git SHA or tag); --no-push boolean default false; --no-git-checks boolean default false; --no-changelog boolean default false; --publish boolean default false; --remote string default 'origin'; --config-from string to load .craft.yml from a remote branch rather than the local file; and numeric --calver-offset overriding configured CalVer days-back offset. Builder applies .check(checkVersionOrPart).
• 🟡 (10:33) Research finding—src/commands/prepare.ts:137-157: PrepareOptions defines newVersion?: string, required rev: string, remote: string, noGitChecks: boolean, noChangelog: boolean, noPush: boolean, publish: boolean, optional configFrom?: string, and optional calverOffset?: number.
• 🟡 (10:33) Research finding—src/commands/prepare.ts:159-163: SLEEP_BEFORE_PUBLISH_SECONDS is 30; it controls the delay before publishing when the corresponding flag is specified.
• 🟡 (10:33) Research finding—src/commands/prepare.ts:176-208: checkVersionOrPart(argv, _opt) validates argv.newVersion. Undefined/empty versions are valid because configuration supplies versioning.policy; 'auto', 'calver', and isBumpType(version) values are valid; otherwise isValidVersion(version) must pass. Invalid values throw Error('Invalid version or version part specified: "${version}"'); versions beginning with 'v' append guidance that removing the "v" prefix will likely fix the issue.
• 🟡 (10:33) Research finding—src/commands/prepare.ts:210-220 begins createReleaseBranch(git: SimpleGit, newVersion, releaseBranchPrefix), documented to create a new local release branch and throw if that branch already exists; its release-branch prefix defaults to "release".