Menu
Changelog Practices guidance for Fortress Rollback. Use when Writing CHANGELOG entries, deciding what to document.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Crate Publishing guidance for Fortress Rollback. Use when Publishing to crates.io, version bumps, release checklist.
Design Decision Log Pattern guidance for Fortress Rollback. Use when Architectural decisions, design alternatives, superseding prior choices.
Repository-wide engineering policy and project context for Fortress Rollback. Use when implementing, diagnosing, reviewing, testing, documenting, or releasing changes in this repository.
GitHub Actions Best Practices guidance for Fortress Rollback. Use when Writing GitHub Actions workflows, CI debugging, actionlint, caching.
Workspace Organization guidance for Fortress Rollback. Use when Organizing workspace, splitting crates, module structure decisions.
Adversarial Handoff Workflow guidance for Fortress Rollback. Use when High-risk reviews, post-incident hardening, escalation from code review.
| name | changelog |
| description | Changelog Practices guidance for Fortress Rollback. Use when Writing CHANGELOG entries, deciding what to document. |
| Change Type | Changelog? | Section | Prefix |
|---|---|---|---|
| New public function/type/trait impl | Yes | Added | |
| Changed function signature | Yes | Changed | Breaking: |
| Removed public item | Yes | Removed | Breaking: |
| New enum variant (exhaustive enum) | Yes | Changed | Breaking: |
New enum variant (#[non_exhaustive]) | Yes | Added | |
Changed Display/Debug output | Yes | Changed | Breaking: |
| Bug fix (user-visible) | Yes | Fixed | |
| Default value change | Yes | Changed | |
| Performance improvement (noticeable) | Yes | Changed | |
New trait impl (Display, Hash, etc.) | Yes | Added | |
pub(crate) or private changes | No | -- | -- |
| Test-only changes | No | -- | -- |
| CI/tooling changes | No | -- | -- |
| Internal refactoring | No | -- | -- |
| Doc typo fixes | No | -- | -- |
Golden rule: If a user's code could behave differently or they need to change their code, document it.
| Visibility | User-Facing? | Changelog? |
|---|---|---|
pub | Yes | Yes |
pub(crate) | No | No |
pub(super) | No | No |
| private | No | No |
## [Unreleased]
### Added
- `ProtocolConfig::deterministic(seed)` preset for reproducible sessions
### Changed
- **Breaking:** `SessionBuilder::with_input_delay()` now returns `Result<Self, FortressError>` instead of panicking on invalid values
### Fixed
- **Pre-existing:** Fixed crash when misprediction detected at frame 0
Sections: Added, Changed, Deprecated, Removed, Fixed, Security.
Unreleased-code rule (hook-enforced): while [Unreleased] has an ### Added section, a
### Fixed entry is only allowed when it fixes behavior that already shipped in a released
version, self-declared with the **Pre-existing:** prefix (mirrors **Breaking:**). Fixes to
the unreleased features themselves must be folded into their ### Added entry instead.
## [Unreleased] undated.## [X.Y.Z] - YYYY-MM-DD.Cargo.toml is X.Y.Z, the matching changelog header must be dated.bash scripts/sync-version.sh --checkbash scripts/sync-version.sh --changelog-onlysync-version.sh metadata issues as failures; warnings are
not acceptable for required release metadata.Added, Deprecated, or non-breaking Changed: at least minor.**Breaking:** or Removed: minor before 1.0; major at or after 1.0.Fixed and/or Security: patch is allowed.[Unreleased]: preparation must fail.The release tool enforces this floor. Protocol-version incompatibilities are
always Changed + **Breaking:**; do not bury them in a Fixed entry.
# WRONG: too internal
- Replaced HashMap with BTreeMap in sync_manager.rs
# CORRECT
- Improved iteration order determinism in session state
# WRONG: verbose
- Added a new method called `with_event_queue_size` to the `SessionBuilder` struct...
# CORRECT
- `SessionBuilder::with_event_queue_size()` for configurable event queue capacity
# WRONG: no guidance
- **Breaking:** Changed `with_input_delay()` return type
# CORRECT
- **Breaking:** `SessionBuilder::with_input_delay()` now returns `Result<Self, FortressError>` instead of silently clamping invalid values
#[non_exhaustive])// Adding variants to this is BREAKING
pub enum ConnectionState { Disconnected, Connecting, Connected }
// Adding variants to this is NOT breaking
#[non_exhaustive]
pub enum ConnectionState { Disconnected, Connecting, Connected }
CHANGELOG entry for new variant on exhaustive enum:
### Changed
- **Breaking:** Added `ConnectionState::Syncing` variant. Update exhaustive matches.
Document under Added:
### Added
- `Display` implementation for `Frame` and `PlayerHandle`
- `Hash` implementation for `SessionConfig`
Changing Display/Debug output is Breaking if users might depend on format:
### Changed
- **Breaking:** `PlayerHandle` now displays as `PlayerHandle(N)` instead of `Player N`
# Validate changelog/version synchronization
bash scripts/sync-version.sh --check
# Verify derives exist before claiming them
rg '#\[derive.*Hash' src/lib.rs
# Verify method/type exists
rg 'pub fn method_name|pub struct TypeName' --type rust
# Build docs to catch broken links
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
When documenting API changes, also update examples:
cargo build --examples # Verify examples compile
cargo test --doc # Verify doc examples
rg 'changed_function|ChangedStruct' --type rust --type md # Find stale refs
Locations: examples/*.rs, README.md, docs/user-guide.md, rustdoc # Examples.
If a release has no user-facing changes, add a single summary line:
- Internal: Improved test coverage and code organization