From eab2be0e6141b76eff2627f05820a2eb5df51533 Mon Sep 17 00:00:00 2001 From: Burak Yigit Kaya Date: Wed, 31 Dec 2025 16:19:42 +0300 Subject: [PATCH] docs: improve documentation and CLI messages for new users - Add craft changelog command documentation to getting-started.md - Add dry-run mode explanation section with blocked vs allowed operations - Document skip-changelog features (#skip-changelog, labels, config) - Add Craft extensions (commit_patterns, semver) to Auto Mode docs - Include link to GitHub's release.yml documentation - Show default conventional commits configuration - Improve GITHUB_TOKEN error message with helpful tip - Update --dry-run help text to be more specific --- docs/src/content/docs/configuration.md | 87 +++++++++++++++++++++--- docs/src/content/docs/getting-started.md | 58 +++++++++++++++- src/index.ts | 2 +- src/utils/githubApi.ts | 3 +- 4 files changed, 136 insertions(+), 14 deletions(-) diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md index 4577a050..ebeeabab 100644 --- a/docs/src/content/docs/configuration.md +++ b/docs/src/content/docs/configuration.md @@ -88,17 +88,51 @@ changelog: policy: auto ``` -Auto mode uses `.github/release.yml` to categorize PRs by labels or commit patterns. If not present, it uses default [Conventional Commits](https://www.conventionalcommits.org/) patterns: +Auto mode uses `.github/release.yml` to categorize PRs. This file follows [GitHub's release.yml format](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuring-automatically-generated-release-notes) with Craft-specific extensions. -| Category | Pattern | -|----------|---------| -| Breaking Changes | `^(?\w+(?:\((?[^)]+)\))?!:\s*)` | -| New Features | `^(?feat(?:\((?[^)]+)\))?!?:\s*)` | -| Bug Fixes | `^(?fix(?:\((?[^)]+)\))?!?:\s*)` | -| Documentation | `^(?docs?(?:\((?[^)]+)\))?!?:\s*)` | -| Build / dependencies | `^(?(?:build\|refactor\|chore\|ci)(?:\((?[^)]+)\))?!?:\s*)` | +#### Craft Extensions to release.yml -Example `.github/release.yml`: +Craft extends GitHub's format with two additional fields: + +| Field | Description | +|-------|-------------| +| `commit_patterns` | Array of regex patterns to match commit/PR titles (in addition to labels) | +| `semver` | Version bump type for auto-versioning: `major`, `minor`, or `patch` | + +#### Default Configuration + +If `.github/release.yml` doesn't exist, Craft uses these defaults based on [Conventional Commits](https://www.conventionalcommits.org/): + +```yaml +changelog: + exclude: + labels: + - skip-changelog + categories: + - title: Breaking Changes 🛠 + commit_patterns: + - "^(?\\w+(?:\\((?[^)]+)\\))?!:\\s*)" + semver: major + - title: New Features ✨ + commit_patterns: + - "^(?feat(?:\\((?[^)]+)\\))?!?:\\s*)" + semver: minor + - title: Bug Fixes 🐛 + commit_patterns: + - "^(?fix(?:\\((?[^)]+)\\))?!?:\\s*)" + - "^Revert \"" + semver: patch + - title: Documentation 📚 + commit_patterns: + - "^(?docs?(?:\\((?[^)]+)\\))?!?:\\s*)" + semver: patch + - title: Build / dependencies / internal 🔧 + commit_patterns: + - "^(?(?:build|refactor|meta|chore|ci|ref|perf)(?:\\((?[^)]+)\\))?!?:\\s*)" + semver: patch +``` + +#### Example Configuration ```yaml changelog: @@ -108,11 +142,13 @@ changelog: - enhancement commit_patterns: - "^(?feat(?:\\((?[^)]+)\\))?!?:\\s*)" + semver: minor - title: Bug Fixes labels: - bug commit_patterns: - "^(?fix(?:\\((?[^)]+)\\))?!?:\\s*)" + semver: patch ``` ### Custom Changelog Entries from PR Descriptions @@ -239,6 +275,39 @@ commit_patterns: - "^feat(?:\\([^)]+\\))?!?:" # No named groups = no stripping ``` +### Skipping Changelog Entries + +You can exclude PRs or commits from the changelog in several ways: + +#### Magic Word + +Add `#skip-changelog` anywhere in your commit message or PR body: + +``` +chore: Update dependencies + +#skip-changelog +``` + +#### Skip Label + +PRs with the `skip-changelog` label are automatically excluded. + +#### Configuration + +Configure exclusions in `.github/release.yml`: + +```yaml +changelog: + exclude: + labels: + - skip-changelog + - dependencies + authors: + - dependabot[bot] + - renovate[bot] +``` + ### Configuration Options | Option | Description | diff --git a/docs/src/content/docs/getting-started.md b/docs/src/content/docs/getting-started.md index bdfb5e17..e3c53340 100644 --- a/docs/src/content/docs/getting-started.md +++ b/docs/src/content/docs/getting-started.md @@ -38,7 +38,7 @@ Commands: Options: --no-input Suppresses all user prompts [default: false] - --dry-run Dry run mode: do not perform any real actions + --dry-run Dry run mode: no file writes, commits, pushes, or API mutations --log-level Logging level [choices: "Fatal", "Error", "Warn", "Log", "Info", "Success", "Debug", "Trace", "Silent", "Verbose"] [default: "Info"] @@ -73,7 +73,7 @@ Positionals: Options: --no-input Suppresses all user prompts [default: false] - --dry-run Dry run mode: do not perform any real actions + --dry-run Dry run mode: no file writes, commits, pushes, or API mutations --rev, -r Source revision (git SHA or tag) to prepare from --no-push Do not push the release branch [boolean] [default: false] --no-git-checks Ignore local git changes and unsynchronized remotes @@ -98,7 +98,7 @@ Positionals: Options: --no-input Suppresses all user prompts [default: false] - --dry-run Dry run mode: do not perform any real actions + --dry-run Dry run mode: no file writes, commits, pushes, or API mutations --target, -t Publish to this target [default: "all"] --rev, -r Source revision (git SHA or tag) to publish --no-merge Do not merge the release branch after publishing @@ -109,6 +109,38 @@ Options: -h, --help Show help [boolean] ``` +### `craft changelog`: Generate Changelog + +Generate a changelog from git history without preparing a release. This is useful for previewing what would be included in a release or for CI integrations. + +```shell +craft changelog + +Generate changelog from git history + +Options: + --since, -s Base revision (tag or SHA) to generate from. Defaults to latest tag. + --pr PR number for the current (unmerged) PR to include with highlighting. + --format, -f Output format: text (default) or json +``` + +Examples: + +```shell +# Generate changelog since last tag +craft changelog + +# Generate changelog since specific commit +craft changelog --since 2b58d3c + +# Get detailed JSON output including bump type and commit stats +craft changelog --format json +``` + +:::note +This command requires `GITHUB_TOKEN` to fetch PR information from GitHub. +::: + ### Example Let's release version `1.2.3`: @@ -173,6 +205,26 @@ CRAFT_DRY_RUN=1 CRAFT_NO_INPUT=0 ``` +### Dry-Run Mode + +The `--dry-run` flag prevents destructive operations while still allowing reads: + +**Blocked:** +- File writes (create, modify, delete) +- Git mutations (commit, push, checkout, merge, tag) +- GitHub API mutations (create release, upload assets) + +**Allowed:** +- Reading files and git history +- Fetching from GitHub API +- Git fetch and status checks + +:::note +Dry-run still requires `GITHUB_TOKEN` for commands that fetch PR information from GitHub. +::: + +### GitHub Token + Since Craft relies heavily on GitHub, set the `GITHUB_TOKEN` environment variable to a [GitHub Personal Access Token](https://github.com/settings/tokens) with `repo` scope. ### Environment Files diff --git a/src/index.ts b/src/index.ts index acb7efe4..5010d252 100644 --- a/src/index.ts +++ b/src/index.ts @@ -35,7 +35,7 @@ const GLOBAL_BOOLEAN_FLAGS = { // TODO(byk): Deprecate this in favor of CRAFT_DRY_RUN default: process.env.DRY_RUN, global: true, - describe: 'Dry run mode: do not perform any real actions', + describe: 'Dry run mode: no file writes, commits, pushes, or API mutations', }, }; diff --git a/src/utils/githubApi.ts b/src/utils/githubApi.ts index 9fec9d29..0f31cfcd 100644 --- a/src/utils/githubApi.ts +++ b/src/utils/githubApi.ts @@ -77,7 +77,8 @@ export function getGitHubApiToken(): string { process.env.GITHUB_TOKEN || process.env.GITHUB_API_TOKEN; if (!githubApiToken) { throw new ConfigurationError( - 'GitHub target: GITHUB_TOKEN not found in the environment' + 'GITHUB_TOKEN not found. This is required to fetch PR information from GitHub.\n' + + 'Tip: Run `gh auth token` if you have GitHub CLI installed.' ); } return githubApiToken;