rocketman-code · rocketman-code · Apr 15, 2026 · Apr 14, 2026 · Apr 15, 2026 · Apr 15, 2026
diff --git a/.github/workflows/pr-fragment.yml b/.github/workflows/pr-fragment.yml
@@ -0,0 +1,72 @@
+name: PR Fragment
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened, ready_for_review]
+
+jobs:
+  fragment-required:
+    if: ${{ !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: dorny/paths-filter@v3
+        id: paths
+        with:
+          filters: |
+            user_facing:
+              - 'crates/atomic-rollback/src/**'
+            fragment:
+              - 'crates/changelog-core/src/lib.rs'
+
+      - name: Enforce fragment requirement
+        if: ${{ steps.paths.outputs.user_facing == 'true' && steps.paths.outputs.fragment == 'false' }}
+        run: |
+          cat <<'MSG'
+          ::error::This PR modifies crates/atomic-rollback/src/** but does not modify crates/changelog-core/src/lib.rs. Every change to user-facing source requires a Fragment.
+
+          To fix:
+
+          1. Add a variant to the fragments! macro invocation in crates/changelog-core/src/lib.rs
+          2. Add a match arm in Fragment::status() returning one of:
+
+             - Status::Unreleased { section: ..., text: "..." } for changes that will appear in CHANGELOG.md
+             - Status::InternalOnly { description: "..." } for changes with no user-perceivable effect (pure private refactor, no perf change, no behavior change). Use sparingly and only after checking there is truly no user impact.
+
+          Example (user-facing change):
+
+            fragments! { /* existing variants, */ DescribeYourChangeHere }
+
+            impl Fragment {
+                pub const fn status(self) -> Status {
+                    match self {
+                        /* existing arms, */
+                        Self::DescribeYourChangeHere => Status::Unreleased {
+                            section: Section::Added,
+                            text: "What users experience, in one sentence.",
+                        },
+                    }
+                }
+            }
+
+          Example (internal-only change):
+
+            Self::RenamedPrivateHelperFoo => Status::InternalOnly {
+                description: "Renamed private helper Foo to Bar for consistency.",
+            },
+
+          After editing crates/changelog-core/src/lib.rs, regenerate CHANGELOG.md:
+
+              cargo run -p changelog > CHANGELOG.md
+
+          Then commit both files together. If you do not, build.rs panics on the next cargo build.
+
+          If you are stuck, comment on this PR and a maintainer will add the Fragment for you.
+
+          See docs/standards/changelog-fragments.md for the full contract, including when InternalOnly is appropriate.
+          MSG
+          exit 1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 All notable changes to atomic-rollback are documented here.
 
+## [Unreleased]
+
 ## [0.4.0] - 2026-04-14
 
 ### Added
@@ -74,6 +76,10 @@ All notable changes to atomic-rollback are documented here.
 
 ## [0.3.2] - 2026-04-01
 
+### Changed
+
+- Internal architecture: all external tool output parsed through grammar-derived types at the boundary. Filesystem type comparisons use an enum instead of string matching.
+
 ### Fixed
 
 - Subvolume names with spaces now parse correctly. The btrfs output parser used whitespace splitting which truncated paths containing spaces.
@@ -82,22 +88,18 @@ All notable changes to atomic-rollback are documented here.
 - BLS root= parameter check accepts all kernel device formats (PARTUUID=, PARTLABEL=, /dev/). Previously only root=UUID= and root=/dev/ were accepted.
 - ESP grub.cfg migration renders from the generator template instead of line surgery, eliminating the double-prefix bug class by construction.
 
-### Changed
+## [0.3.1] - 2026-03-31
 
-- Internal architecture: all external tool output parsed through grammar-derived types at the boundary. Filesystem type comparisons use an enum instead of string matching.
+### Changed
 
-## [0.3.1] - 2026-03-31
+- Installation via COPR is the only supported method. The crate was removed from crates.io (binary alone is insufficient without the hook and plugin).
 
 ### Fixed
 
 - Kernel-install hook uses full binary path (/usr/bin/atomic-rollback). The bare command was not in RPM's scriptlet PATH, causing exit 127 on kernel upgrades.
 - RPM spec rewritten for COPR vendored builds. The previous spec used %cargo_build which expects Fedora-packaged crates.
 - COPR Makefile builds from cloned source with correct outdir contract.
 
-### Changed
-
-- Installation via COPR is the only supported method. The crate was removed from crates.io (binary alone is insufficient without the hook and plugin).
-
 ## [0.3.0] - 2026-03-30
 
 ### Added
@@ -141,8 +143,6 @@ All notable changes to atomic-rollback are documented here.
 
 ## [0.1.1] - 2026-03-29
 
-Initial release.
-
 ### Added
 
 - `check`, `migrate`, `rollback`, `snapshot` commands.
@@ -159,3 +159,4 @@ Initial release.
 - All system-specific values (device ref, compression, subvol name) derived from fstab.
 - Bootability predicate derived from the actual Fedora boot chain.
 - RPM spec with kernel-install hook and dnf plugin.
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,65 @@
+# Contributing to atomic-rollback
+
+Thanks for considering a contribution. This guide covers the essentials.
+
+## Prerequisites
+
+- Rust toolchain (`cargo`, `rustc`)
+- Git
+- For VM integration testing: [lima](https://lima-vm.io/) with a Fedora 43 template
+
+## Build
+
+```sh
+cargo build --release
+```
+
+The workspace builds all member crates. The `atomic-rollback` binary lands at `target/release/atomic-rollback`.
+
+## Test
+
+```sh
+cargo test --release
+```
+
+Tests run on Linux and macOS in CI. Production code uses Unix APIs only, so tests are skipped on Windows.
+
+For VM integration testing of `atomic-rollback check` on a real Fedora environment, see `.github/workflows/ci.yml` (x86_64 lima job) for the canonical recipe.
+
+## Commit format
+
+[Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): lowercase imperative description
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `style`, `perf`, `ci`
+
+Examples:
+
+```
+feat(snapshot): auto-named rolling snapshots
+fix(hook): transfer kernel-install hook ownership to migrate
+ci: add cargo test job on ubuntu + macos matrix
+```
+
+## Pull requests
+
+- All changes go through PRs; no exceptions
+- Branch protection requires all CI checks to pass before merge
+- Rebase merge only (linear history)
+
+PR test plans are mandatory. Unchecked task-list items block merge. Complete tests before merging; removing items is not a valid escape.
+
+## CHANGELOG fragments
+
+Every PR that modifies `crates/atomic-rollback/src/**` requires a Fragment in `crates/changelog-core/src/lib.rs`. Structural, not commit-type-based — the gate reads the diff directly so the requirement cannot be bypassed by relabeling commits.
+
+See [docs/standards/changelog-fragments.md](docs/standards/changelog-fragments.md) for the full contract, including when `Status::InternalOnly` is appropriate.
+
+## Project standards
+
+Detailed standards:
+
+- [CHANGELOG fragments](docs/standards/changelog-fragments.md) — how to add fragments, when they're required, when InternalOnly is appropriate, how releases consume them
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,19 +1,7 @@
-[package]
-name = "atomic-rollback"
-version = "0.4.0"
-edition = "2024"
-description = "Atomic system rollback for Fedora via Btrfs RENAME_EXCHANGE subvolume swap"
-license = "GPL-3.0-only"
-repository = "https://github.com/rocketman-code/atomic-rollback"
-keywords = ["btrfs", "rollback", "fedora", "snapshot", "atomic"]
-categories = ["command-line-utilities", "filesystem"]
-
-[lints.rust]
-unexpected_cfgs = { level = "warn", check-cfg = ['cfg(kani)', 'cfg(verus_only)', 'cfg(verus_keep_ghost)'] }
-
-[dependencies]
-libc = "0.2"
-vstd = "=0.0.0-2026-03-29-0113"
-
-[package.metadata.verus]
-verify = true
+[workspace]
+resolver = "3"
+members = [
+    "crates/atomic-rollback",
+    "crates/changelog-core",
+    "crates/changelog",
+]
diff --git a/crates/atomic-rollback/Cargo.toml b/crates/atomic-rollback/Cargo.toml
@@ -0,0 +1,19 @@
+[package]
+name = "atomic-rollback"
+version = "0.4.0"
+edition = "2024"
+description = "Atomic system rollback for Fedora via Btrfs RENAME_EXCHANGE subvolume swap"
+license = "GPL-3.0-only"
+repository = "https://github.com/rocketman-code/atomic-rollback"
+keywords = ["btrfs", "rollback", "fedora", "snapshot", "atomic"]
+categories = ["command-line-utilities", "filesystem"]
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(kani)', 'cfg(verus_only)', 'cfg(verus_keep_ghost)'] }
+
+[dependencies]
+libc = "0.2"
+vstd = "=0.0.0-2026-03-29-0113"
+
+[package.metadata.verus]
+verify = true
diff --git a/src/check.rs → crates/atomic-rollback/src/check.rs b/src/check.rs → crates/atomic-rollback/src/check.rs
diff --git a/src/consts.rs → crates/atomic-rollback/src/consts.rs b/src/consts.rs → crates/atomic-rollback/src/consts.rs
diff --git a/src/grub.rs → crates/atomic-rollback/src/grub.rs b/src/grub.rs → crates/atomic-rollback/src/grub.rs
diff --git a/src/kernel_hook.rs → crates/atomic-rollback/src/kernel_hook.rs b/src/kernel_hook.rs → crates/atomic-rollback/src/kernel_hook.rs
diff --git a/src/main.rs → crates/atomic-rollback/src/main.rs b/src/main.rs → crates/atomic-rollback/src/main.rs
diff --git a/src/migrate.rs → crates/atomic-rollback/src/migrate.rs b/src/migrate.rs → crates/atomic-rollback/src/migrate.rs
diff --git a/src/parse.rs → crates/atomic-rollback/src/parse.rs b/src/parse.rs → crates/atomic-rollback/src/parse.rs
diff --git a/src/platform.rs → crates/atomic-rollback/src/platform.rs b/src/platform.rs → crates/atomic-rollback/src/platform.rs
diff --git a/src/proof.rs → crates/atomic-rollback/src/proof.rs b/src/proof.rs → crates/atomic-rollback/src/proof.rs
diff --git a/src/rollback.rs → crates/atomic-rollback/src/rollback.rs b/src/rollback.rs → crates/atomic-rollback/src/rollback.rs
diff --git a/src/snapshot.rs → crates/atomic-rollback/src/snapshot.rs b/src/snapshot.rs → crates/atomic-rollback/src/snapshot.rs
diff --git a/src/swap.rs → crates/atomic-rollback/src/swap.rs b/src/swap.rs → crates/atomic-rollback/src/swap.rs
diff --git a/src/tools.rs → crates/atomic-rollback/src/tools.rs b/src/tools.rs → crates/atomic-rollback/src/tools.rs
diff --git a/crates/changelog-core/Cargo.toml b/crates/changelog-core/Cargo.toml
@@ -0,0 +1,6 @@
+[package]
+name = "changelog-core"
+version = "0.1.0"
+edition = "2024"
+publish = false
+description = "Source-of-truth and generator for atomic-rollback's CHANGELOG.md"