fix(changelog): Warn when custom release.yml lacks semver fields

When a custom .github/release.yml is used without semver fields on categories,
PRs appear in the changelog but don't contribute to version bump detection.
This causes the changelog preview to show "None" for semver impact.

Changes:
- Add warning when normalizing custom configs with missing semver fields
- Update docs to clarify semver field requirement for version detection
- Add tests for the warning behavior

Fixes getsentry/sentry-wizard#1191 investigation

Author: BYK

docs/src/content/docs/configuration.md

@@ -31,6 +31,7 @@ The command is executed with the following environment variables:
 The script should:
 
 - Use these environment variables to perform version replacement
+- Replace version occurrences
 - Not commit changes
 - Not change git state
 
@@ -105,6 +106,13 @@ Craft extends GitHub's format with two additional fields:
 | `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`       |
 
+:::caution[Required for Version Detection]
+The `semver` field is required for Craft's automatic version detection to work.
+If you define a custom `.github/release.yml` without `semver` fields, PRs will
+still appear in the changelog but won't contribute to suggested version bumps.
+The [changelog preview](/github-actions/#changelog-preview) will show "None" for semver impact.
+:::
+
 #### Default Configuration
 
 If `.github/release.yml` doesn't exist, Craft uses these defaults based on [Conventional Commits](https://www.conventionalcommits.org/):

docs/src/content/docs/github-actions.md

@@ -11,10 +11,10 @@ For a real-world example of using Craft's GitHub Actions, see the [getsentry/pub
 
 Craft offers two ways to automate releases in GitHub Actions:
 
-| Option | Best For | Flexibility |
-|--------|----------|-------------|
-| **Reusable Workflow** | Quick setup, standard release flow | Low - runs as a complete job |
-| **Composite Action** | Custom workflows, pre/post steps | High - composable with other steps |
+| Option                | Best For                           | Flexibility                        |
+| --------------------- | ---------------------------------- | ---------------------------------- |
+| **Reusable Workflow** | Quick setup, standard release flow | Low - runs as a complete job       |
+| **Composite Action**  | Custom workflows, pre/post steps   | High - composable with other steps |
 
 ### Option 1: Reusable Workflow (Recommended)
 
@@ -39,27 +39,27 @@ jobs:
 
 #### Workflow Inputs
 
-| Input | Description | Default |
-|-------|-------------|---------|
-| `version` | Version to release. Can be a semver string (e.g., "1.2.3"), a bump type ("major", "minor", "patch"), or "auto" for automatic detection. | Uses `versioning.policy` from config |
-| `merge_target` | Target branch to merge into. | Default branch |
-| `force` | Force a release even when there are release-blockers. | `false` |
-| `blocker_label` | Label that blocks releases. | `release-blocker` |
-| `publish_repo` | Repository for publish issues (owner/repo format). | `{owner}/publish` |
-| `git_user_name` | Git committer name. | GitHub actor |
-| `git_user_email` | Git committer email. | Actor's noreply email |
-| `path` | The path that Craft will run inside. | `.` |
-| `craft_config_from_merge_target` | Use the craft config from the merge target branch. | `false` |
+| Input                            | Description                                                                                                                             | Default                              |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `version`                        | Version to release. Can be a semver string (e.g., "1.2.3"), a bump type ("major", "minor", "patch"), or "auto" for automatic detection. | Uses `versioning.policy` from config |
+| `merge_target`                   | Target branch to merge into.                                                                                                            | Default branch                       |
+| `force`                          | Force a release even when there are release-blockers.                                                                                   | `false`                              |
+| `blocker_label`                  | Label that blocks releases.                                                                                                             | `release-blocker`                    |
+| `publish_repo`                   | Repository for publish issues (owner/repo format).                                                                                      | `{owner}/publish`                    |
+| `git_user_name`                  | Git committer name.                                                                                                                     | GitHub actor                         |
+| `git_user_email`                 | Git committer email.                                                                                                                    | Actor's noreply email                |
+| `path`                           | The path that Craft will run inside.                                                                                                    | `.`                                  |
+| `craft_config_from_merge_target` | Use the craft config from the merge target branch.                                                                                      | `false`                              |
 
 #### Workflow Outputs
 
-| Output | Description |
-|--------|-------------|
-| `version` | The resolved version being released |
-| `branch` | The release branch name |
-| `sha` | The commit SHA on the release branch |
+| Output         | Description                                  |
+| -------------- | -------------------------------------------- |
+| `version`      | The resolved version being released          |
+| `branch`       | The release branch name                      |
+| `sha`          | The commit SHA on the release branch         |
 | `previous_tag` | The tag before this release (for diff links) |
-| `changelog` | The changelog for this release |
+| `changelog`    | The changelog for this release               |
 
 ### Option 2: Composite Action
 
@@ -106,7 +106,7 @@ When using auto-versioning, Craft analyzes conventional commits to determine the
 name: Auto Release
 on:
   schedule:
-    - cron: '0 10 * * 1'  # Every Monday at 10 AM
+    - cron: '0 10 * * 1' # Every Monday at 10 AM
 
 jobs:
   release:
@@ -142,8 +142,8 @@ jobs:
 
 ### Inputs
 
-| Input | Description | Default |
-|-------|-------------|---------|
+| Input           | Description                               | Default  |
+| --------------- | ----------------------------------------- | -------- |
 | `craft-version` | Version of Craft to use (tag or "latest") | `latest` |
 
 ### Pinning a Specific Version
@@ -157,7 +157,7 @@ jobs:
   changelog-preview:
     uses: getsentry/craft/.github/workflows/changelog-preview.yml@v2
     with:
-      craft-version: "2.15.0"
+      craft-version: '2.15.0'
     secrets: inherit
 ```
 
@@ -171,6 +171,12 @@ jobs:
 6. **Posts a comment** - Creates or updates a comment on the PR with the changelog preview
 7. **Auto-updates** - The comment is automatically updated when you update the PR (push commits, edit title/description, or change labels)
 
+:::note
+The version bump suggestion requires categories in your `.github/release.yml` to have
+`semver` fields defined. Without them, the suggested bump will show as "None".
+See [Auto Mode configuration](/configuration/#auto-mode) for details.
+:::
+
 ### Example Comment
 
 The workflow posts a comment like this:
@@ -205,6 +211,7 @@ Entries from this PR are highlighted with a left border (blockquote style).
 ### PR Trigger Types
 
 The workflow supports these PR event types:
+
 - `opened` - When a PR is created
 - `synchronize` - When new commits are pushed
 - `reopened` - When a closed PR is reopened
@@ -216,13 +223,16 @@ The workflow supports these PR event types:
 The workflow requires specific permissions and secrets to function correctly:
 
 **Permissions** (required):
+
 - `contents: read` - Allows the workflow to checkout your repository and read git history for changelog generation
 - `pull-requests: write` - Allows the workflow to post and update comments on pull requests
 
 **Secrets**:
+
 - `secrets: inherit` - Passes your repository's `GITHUB_TOKEN` to the workflow, ensuring it has access to your repository (especially important for private repositories)
 
 **Repository Setup**:
+
 - The repository should have a git history with tags for the changelog to be meaningful
 
 :::note[Why are these permissions needed?]
@@ -248,13 +258,13 @@ You can configure labels to exclude PRs from the changelog. In your `.craft.yml`
 ```yaml
 changelog:
   categories:
-    - title: "New Features ✨"
-      labels: ["feature", "enhancement"]
-    - title: "Bug Fixes 🐛"
-      labels: ["bug", "fix"]
+    - title: 'New Features ✨'
+      labels: ['feature', 'enhancement']
+    - title: 'Bug Fixes 🐛'
+      labels: ['bug', 'fix']
   exclude:
-    labels: ["skip-changelog", "dependencies"]
-    authors: ["dependabot[bot]", "renovate[bot]"]
+    labels: ['skip-changelog', 'dependencies']
+    authors: ['dependabot[bot]', 'renovate[bot]']
 ```
 
 PRs with the `skip-changelog` label or from excluded authors will not appear in the changelog.