Distillation

Date: Aug 25, 2026

• 🔴 (14:53) User directed that CalVer changelog content destined for publish issues replace @-mentions with bold formatting, preventing contributor notifications; committed CHANGELOG.md content must retain original @-mentions.
• 🟡 (14:53) Inspected /home/byk/Code/getsentry/craft-workspace-action-propagation/src/commands/prepare.ts:800-1003.
• 🟡 (14:53) prepareMain loads .craft.yml from argv.remote/argv.configFrom when requested, warns that its preReleaseCommand will execute and the branch must be trusted, runs git.fetch([argv.remote, argv.configFrom]) and git.show([${argv.remote}/${argv.configFrom}:${CONFIG_FILE_NAME}]), and wraps failures as ConfigurationError("Failed to load ${CONFIG_FILE_NAME} from branch \"${argv.configFrom}\": ${error.message}").
• 🟡 (14:53) prepareMain gets config, global GitHub config, default branch, and repository status; resolves rev as argv.rev || repoStatus.current || defaultBranch; skips checkGitStatus(repoStatus, rev) only with argv.noGitChecks.
• 🟡 (14:53) prepareMain resolves newVersion via resolveVersion(git, { versionArg: argv.newVersion, calverOffset: argv.calverOffset }), writes GitHub Actions output version, and requires confirmation when no explicit argv.rev is supplied and rev !== defaultBranch.
• 🟡 (14:53) prepareMain creates dry-run isolation via createDryRunIsolation(git, rev) before release work, replaces git with isolation.git, and always calls await isolation.cleanup() in finally.
• 🟡 (14:53) Release preparation ordering in prepareMain is explicitly significant: createReleaseBranch(git, rev, newVersion, argv.remote, config.releaseBranchPrefix) must run before getLatestTag(git, getGitTagPrefix()), because release may originate from a custom revision and the previous tag must be determined after checkout of the release branch.
• 🟡 (14:53) prepareMain derives changelogPath from either string config.changelog or config.changelog?.filePath; derives changelogPolicy from object config.changelog?.policy when present, otherwise legacy config.changelogPolicy; invokes prepareChangelog() with ChangelogPolicy.None when argv.noChangelog is set.
• 🟡 (14:53) When changelogBody exists, prepareMain stages relative('', changelogPath || DEFAULT_CHANGELOG_PATH) through git.add() before pre-release scripts, ensuring the changelog is committed even if no pre-release command runs; adding an unchanged file is a no-op.
• 🟡 (14:53) prepareMain runs runPreReleaseCommand({ oldVersion, newVersion, preReleaseCommand: config.preReleaseCommand, targets: config.targets, rootDir: getConfigFileDir() || process.cwd() }), then calls commitChanges(git, newVersion, preReleaseCommandRan), isolation.showDiff(), and pushReleaseBranch(git, branchName, argv.remote, !argv.noPush).
• 🟡 (14:53) For a nonempty changelog, CalVer detection is argv.newVersion === 'calver' || getVersioningPolicy() === VersioningPolicy.CalVer; CalVer uses disableChangelogMentions(changelogBody) as issueChangelog, while other versioning policies use the unchanged changelogBody.
• 🟡 (14:53) prepareMain writes full issueChangelog with writeGitHubActionsFile('changelog', issueChangelog) to avoid Linux ARG_MAX/E2BIG from action.yml environment-variable expansion; the comment cites an approximately 2 MB limit and large changelogs such as Sentry monthly releases.
• 🟡 (14:53) prepareMain builds a changelog permalink as https://github.com/${githubConfig.owner}/${githubConfig.repo}/blob/${branchName}/${resolvedChangelogPath}${lineRange}, where lineRange comes from getChangelogLineRange(git, resolvedChangelogPath, newVersion); it sets a compatibility output changelog via truncateForOutput(issueChangelog, changelogFileUrl) so older action.yml versions reading an environment variable avoid E2BIG.
• 🟡 (14:53) With argv.publish, isolated dry-run logs [dry-run] Would run: craft publish ${newVersion} rather than publishing; non-isolated mode logs that release branch was pushed and calls execPublish(argv.remote, newVersion, argv.noGitChecks). Without argv.publish, it logs a reminder to run craft publish ${newVersion}.
• 🟡 (14:53) After successful preparation, prepareMain switches back to defaultBranch using switchToDefaultBranch(git, defaultBranch) only when !argv.rev && !isolation.isIsolated.
• 🟡 (14:53) Exported handler(args) wraps prepareMain in withTracing(..., { name: 'craft.prepare', op: 'craft.prepare' }) and sends thrown errors to handleGlobalError(e).