Skip to content

docs: Document CRAFT_NEW_VERSION and CRAFT_OLD_VERSION for pre-release command #719

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BYK merged 2 commits into from
Jan 15, 2026
Merged

docs: Document CRAFT_NEW_VERSION and CRAFT_OLD_VERSION for pre-release command #719

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
82d7585
fix(changelog): Collapse previews by default
BYK Jan 15, 2026
fdd9f6e
docs: Update pre-release command documentation with env variables
BYK Jan 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions .github/workflows/changelog-preview.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ on:
workflow_call:
inputs:
working-directory:
description: "Directory to run Craft in (relative to repo root)"
description: 'Directory to run Craft in (relative to repo root)'
required: false
type: string
default: "."
default: '.'
craft-version:
description: 'Version of Craft to use (tag or "latest")'
required: false
Expand Down Expand Up @@ -67,9 +67,9 @@ jobs:
shell: bash
run: |
set -euo pipefail

CRAFT_VERSION="${{ inputs.craft-version || 'latest' }}"

if [[ "$CRAFT_VERSION" == "latest" || -z "$CRAFT_VERSION" ]]; then
echo "Downloading latest Craft release..."
CRAFT_URL=$(curl -fsSL "https://api.github.com/repos/getsentry/craft/releases/latest" \
Expand All @@ -85,23 +85,23 @@ jobs:
| jq -r '.assets[] | select(.name == "craft") | .browser_download_url')
fi
fi

# Verify we have a valid URL
if [[ -z "$CRAFT_URL" ]]; then
echo "::error::Failed to determine Craft download URL"
exit 1
fi

echo "Installing Craft from: ${CRAFT_URL}"
sudo curl -fsSL -o /usr/local/bin/craft "$CRAFT_URL"
sudo chmod +x /usr/local/bin/craft

# Verify installation
if [[ ! -s /usr/local/bin/craft ]]; then
echo "::error::Downloaded Craft binary is empty or missing"
exit 1
fi

craft --version

- name: Generate Changelog Preview
Expand Down Expand Up @@ -145,7 +145,8 @@ jobs:

${BUMP_BADGE}

## 📋 Changelog Preview
<details>
<summary>📋 Changelog Preview</summary>

This is how your changes will appear in the changelog.
Entries from this PR are highlighted with a left border (blockquote style).
Expand All @@ -156,6 +157,8 @@ jobs:

---

</details>

<sub>🤖 This preview updates automatically when you update the PR.</sub>
CRAFT_CHANGELOG_COMMENT_END

Expand Down
86 changes: 47 additions & 39 deletions docs/src/content/docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,22 +23,28 @@ This command runs on your release branch as part of `craft prepare`. Default: `b
preReleaseCommand: bash scripts/bump-version.sh
```

The command is executed with the following environment variables:

- `CRAFT_OLD_VERSION`: The previous version (or `0.0.0` if no previous version exists)
- `CRAFT_NEW_VERSION`: The new version being released

The script should:
- Accept old and new version as the last two arguments
- Replace version occurrences

- Use these environment variables to perform version replacement
- Not commit changes
- Not change git state

> **Note:** For backward compatibility, the old and new versions are also passed as the last two command-line arguments to the script, but using environment variables is safer and recommended.

Example script:

```bash
#!/bin/bash
set -eux
OLD_VERSION="${1}"
NEW_VERSION="${2}"

# Use CRAFT_NEW_VERSION provided by craft
export npm_config_git_tag_version=false
npm version "${NEW_VERSION}"
npm version "${CRAFT_NEW_VERSION}"
```

## Post-release Command
Expand Down Expand Up @@ -94,10 +100,10 @@ Auto mode uses `.github/release.yml` to categorize PRs. This file follows [GitHu

Craft extends GitHub's format with two additional fields:

| Field | Description |
|-------|-------------|
| 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` |
| `semver` | Version bump type for auto-versioning: `major`, `minor`, or `patch` |

#### Default Configuration

Expand All @@ -120,7 +126,7 @@ changelog:
- title: Bug Fixes 🐛
commit_patterns:
- "^(?<type>fix(?:\\((?<scope>[^)]+)\\))?!?:\\s*)"
- "^Revert \""
- '^Revert "'
semver: patch
- title: Documentation 📚
commit_patterns:
Expand Down Expand Up @@ -198,12 +204,13 @@ of the PR title. If no such section is present, the PR title is used as usual.
### Changelog Entry

- Add authentication system
- OAuth2 support
- Two-factor authentication
- Session management
- OAuth2 support
- Two-factor authentication
- Session management
```

This will generate:

```markdown
- Add authentication system by @user in [#123](url)
- OAuth2 support
Expand All @@ -228,7 +235,7 @@ Changes are automatically grouped by scope (e.g., `feat(api):` groups under "Api
```yaml
changelog:
policy: auto
scopeGrouping: true # default
scopeGrouping: true # default
```

Scope headers are only shown for scopes with more than one entry. Entries without
Expand Down Expand Up @@ -262,17 +269,17 @@ This behavior is controlled by named capture groups in `commit_patterns`:
- `(?<type>...)` - The type prefix to strip (includes type, scope, and colon)
- `(?<scope>...)` - Scope to preserve when not under a scope header

| Original Title | Scope Header | Displayed Title |
|----------------|--------------|-----------------|
| `feat(api): add endpoint` | Yes (Api) | `Add endpoint` |
| `feat(api): add endpoint` | No | `(api) Add endpoint` |
| `feat: add endpoint` | N/A | `Add endpoint` |
| Original Title | Scope Header | Displayed Title |
| ------------------------- | ------------ | -------------------- |
| `feat(api): add endpoint` | Yes (Api) | `Add endpoint` |
| `feat(api): add endpoint` | No | `(api) Add endpoint` |
| `feat: add endpoint` | N/A | `Add endpoint` |

To disable stripping, provide custom patterns using non-capturing groups:

```yaml
commit_patterns:
- "^feat(?:\\([^)]+\\))?!?:" # No named groups = no stripping
- "^feat(?:\\([^)]+\\))?!?:" # No named groups = no stripping
```

### Skipping Changelog Entries
Expand Down Expand Up @@ -310,29 +317,29 @@ changelog:

### Configuration Options

| Option | Description |
|--------|-------------|
| `changelog` | Path to changelog file (string) OR configuration object |
| `changelog.filePath` | Path to changelog file. Default: `CHANGELOG.md` |
| `changelog.policy` | Mode: `none`, `simple`, or `auto`. Default: `none` |
| `changelog.scopeGrouping` | Enable scope-based grouping. Default: `true` |
| Option | Description |
| ------------------------- | ------------------------------------------------------- |
| `changelog` | Path to changelog file (string) OR configuration object |
| `changelog.filePath` | Path to changelog file. Default: `CHANGELOG.md` |
| `changelog.policy` | Mode: `none`, `simple`, or `auto`. Default: `none` |
| `changelog.scopeGrouping` | Enable scope-based grouping. Default: `true` |

## Versioning

Configure default versioning behavior:

```yaml
versioning:
policy: auto # auto, manual, or calver
policy: auto # auto, manual, or calver
```

### Versioning Policies

| Policy | Description |
|--------|-------------|
| `auto` | Analyze commits to determine version bump (default when using `craft prepare auto`) |
| `manual` | Require explicit version argument |
| `calver` | Use calendar-based versioning |
| Policy | Description |
| -------- | ----------------------------------------------------------------------------------- |
| `auto` | Analyze commits to determine version bump (default when using `craft prepare auto`) |
| `manual` | Require explicit version argument |
| `calver` | Use calendar-based versioning |

### Calendar Versioning (CalVer)

Expand All @@ -342,11 +349,12 @@ For projects using calendar-based versions:
versioning:
policy: calver
calver:
format: "%y.%-m" # e.g., 24.12 for December 2024
offset: 14 # Days to look back for date calculation
format: '%y.%-m' # e.g., 24.12 for December 2024
offset: 14 # Days to look back for date calculation
```

Format supports:

- `%y` - 2-digit year
- `%m` - Zero-padded month
- `%-m` - Month without padding
Expand Down Expand Up @@ -387,7 +395,7 @@ Configure where to fetch artifacts from:

```yaml
artifactProvider:
name: github # or 'gcs' or 'none'
name: github # or 'gcs' or 'none'
```

## Targets
Expand All @@ -410,11 +418,11 @@ See [Target Configurations](./targets/) for details on each target.

These options apply to all targets:

| Option | Description |
|--------|-------------|
| `includeNames` | Regex: only matched files are processed |
| `excludeNames` | Regex: matched files are skipped |
| `id` | Unique ID for the target (use with `-t target[id]`) |
| Option | Description |
| -------------- | --------------------------------------------------- |
| `includeNames` | Regex: only matched files are processed |
| `excludeNames` | Regex: matched files are skipped |
| `id` | Unique ID for the target (use with `-t target[id]`) |

Example:

Expand Down
Loading