# release-version-flag Specification
## Purpose
Provide a `--release-version <VERSION>` flag on the grubble CLI that writes an exact version to the package file(s) and optionally generates a CHANGELOG entry, without any file-vs-tag sync or forward-bump logic. This is the publish-side counterpart of the dry-run read side.
## Requirements
### Requirement: --release-version writes the specified version to package files
The CLI SHALL accept a `--release-version <VERSION>` flag that writes the given semver string to the configured package file(s) (e.g., Cargo.toml, package.json) via the applicable Strategy. The version SHALL be written exactly as specified, with no analysis of commits, no file-vs-tag comparison, and no sync logic.
#### Scenario: explicit version is written to Cargo.toml
- **WHEN** grubble runs with `--release-version 5.3.2 --preset rust`
- **THEN** Cargo.toml's `version` field SHALL be updated to `5.3.2`
- **AND** no git commit SHALL be created (no `--changelog` flag)
- **AND** no git tag SHALL be created
### Requirement: --release-version with --changelog generates a CHANGELOG entry
When `--changelog` is combined with `--release-version`, grubble SHALL generate a CHANGELOG entry for the specified version using commits since the last reachable semver tag. The entry SHALL follow the same format as entries generated by the forward-bump flow.
#### Scenario: CHANGELOG entry uses the specified version
- **WHEN** grubble runs with `--release-version 5.4.0 --changelog --preset rust`
- **THEN** the CHANGELOG.md file SHALL contain a new `## [5.4.0] - <date>` entry
- **AND** the entry SHALL include all conventional commits since the last tag
- **AND** a git commit SHALL be created with the Cargo.toml update and CHANGELOG.md update
### Requirement: --release-version with --output json emits the version
When `--output json` is combined with `--release-version`, grubble SHALL emit a JSON object containing the version that was written.
#### Scenario: JSON output contains the written version
- **WHEN** grubble runs with `--release-version 5.4.0 --output json --preset rust`
- **THEN** stdout SHALL contain `{"version": "5.4.0"}`
- **AND** the process SHALL exit with code 0
### Requirement: --release-version errors on invalid semver
If the value passed to `--release-version` is not a valid semver string (`X.Y.Z`), grubble SHALL exit with a non-zero code and an error message.
#### Scenario: invalid version format
- **WHEN** grubble runs with `--release-version 5.4`
- **THEN** grubble SHALL exit with a non-zero code
- **AND** stderr SHALL contain an error message indicating an invalid version
### Requirement: --release-version conflicts with incompatible flags
The `--release-version` flag SHALL be mutually exclusive with `--raw`, `--dry-run`, `--bump-type`, and `--release-from-pr`. Attempting to combine them SHALL result in a CLI parsing error.
#### Scenario: --release-version with --raw
- **WHEN** grubble runs with `--release-version 5.4.0 --raw`
- **THEN** grubble SHALL exit with a non-zero code and display a usage error about conflicting flags
### Requirement: --release-version respects --git-user-name and --git-user-email
When creating a commit (with `--changelog`), the commit SHALL use the configured git user name and email, either from the config file or from CLI flags.
#### Scenario: custom git user in commit
- **WHEN** grubble runs with `--release-version 5.4.0 --changelog --git-user-name "bot" --git-user-email "bot@x.com"`
- **THEN** the created commit SHALL have author `bot <bot@x.com>`