getsentry · BYK · Dec 31, 2025 · Dec 31, 2025
diff --git 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 | `^(?<type>\w+(?:\((?<scope>[^)]+)\))?!:\s*)` |
-| New Features | `^(?<type>feat(?:\((?<scope>[^)]+)\))?!?:\s*)` |
-| Bug Fixes | `^(?<type>fix(?:\((?<scope>[^)]+)\))?!?:\s*)` |
-| Documentation | `^(?<type>docs?(?:\((?<scope>[^)]+)\))?!?:\s*)` |
-| Build / dependencies | `^(?<type>(?:build\|refactor\|chore\|ci)(?:\((?<scope>[^)]+)\))?!?:\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:
+        - "^(?<type>\\w+(?:\\((?<scope>[^)]+)\\))?!:\\s*)"
+      semver: major
+    - title: New Features ✨
+      commit_patterns:
+        - "^(?<type>feat(?:\\((?<scope>[^)]+)\\))?!?:\\s*)"
+      semver: minor
+    - title: Bug Fixes 🐛
+      commit_patterns:
+        - "^(?<type>fix(?:\\((?<scope>[^)]+)\\))?!?:\\s*)"
+        - "^Revert \""
+      semver: patch
+    - title: Documentation 📚
+      commit_patterns:
+        - "^(?<type>docs?(?:\\((?<scope>[^)]+)\\))?!?:\\s*)"
+      semver: patch
+    - title: Build / dependencies / internal 🔧
+      commit_patterns:
+        - "^(?<type>(?:build|refactor|meta|chore|ci|ref|perf)(?:\\((?<scope>[^)]+)\\))?!?:\\s*)"
+      semver: patch
+```
+
+#### Example Configuration
 
 ```yaml
 changelog:
@@ -108,11 +142,13 @@ changelog:
         - enhancement
       commit_patterns:
         - "^(?<type>feat(?:\\((?<scope>[^)]+)\\))?!?:\\s*)"
+      semver: minor
     - title: Bug Fixes
       labels:
         - bug
       commit_patterns:
         - "^(?<type>fix(?:\\((?<scope>[^)]+)\\))?!?:\\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
@@ -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
@@ -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
@@ -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;