Design format: a change is one new file, never an edit to FORMAT (#1563)

A PR that saves something new adds crates/doc/src/format/pending/<name>.rs (a note, and an upgrade step if older designs must be rewritten). The build writes the next format number while changes are pending and lists them in format_pending; scripts/fold-format-pending.sh fixes them as v<N>/ at release time. Formats 23 and 24 move into v23/ and v24/.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/book/src/guide/files.md

@@ -86,11 +86,12 @@ is available. Missing or incompatible pictures use the usual thumbnail generatio
 The default `cache: false` omits the portable thumbnail too.
 The repository's `docs/design-container.md` describes limits and encoding details.
 
-Current designs use format 24, including the corner relief of an edge flange, the gear, rack and pinion and screw couplings of motion links, design properties, named render setups, opaque PBR looks, thin extrudes, sheet metal perforation fields, associative editable sketch patterns, editable associative offset-distance dimensions, the style of sketch text (bold, italic, alignment, spacing and the curve it follows), face anchors on a piece of a face by its own name, sheet metal rims and bend ends, bend edges for Convert to Sheet Metal, the tear corner relief of sheet metal rules, the names of projected edges, physical materials defined in the design, the font of sketch text, the expressions behind a sketch text's height, place and angle, sheet metal corner relief shapes, sketch face anchors on cylinder caps, sketch axis
-links, persistent
-names from exact face history, exact planar shell-face anchors, persistent analytic offset boundary roles and
-association profile references, durable sketch face anchors, periodic fit splines and versioned
-revolve conventions. It also retains recorded body transfers, explicit 3D curve coordinate
+Designs are saved in the newest format this version of SolidCraft knows (`"format": "solidcraft/N"`
+in the file). It opens designs of every older format and upgrades them as they open; a design
+from a newer version asks you to update instead of being guessed at. Development (nightly) builds
+save a format number no release reads yet.
+
+Upgrading keeps what a design meant. Designs keep recorded body transfers, explicit 3D curve coordinate
 spaces and certified face bindings, alongside semantic configuration styles, associative
 free-form offsets and cylindrical emboss selections. Older ownership maps, geometry and
 expressions retain their saved meaning. Legacy 3D curves with retained associations receive

docs/design-container.md

@@ -7,7 +7,7 @@ self-contained input/output format. `io::write_design` keeps its JSON contract;
 `io::write_design_container` is the fallible container writer.
 
 Packages have `container.json` with `{"format":"solidcraft-container/1"}` and
-`document.json` with the versioned parametric document (currently `solidcraft/24`).
+`document.json` with the versioned parametric document (`solidcraft/N`, the format in `crates/doc/src/format.rs`).
 The independent versions let document migrations evolve without changing blob encodings.
 Existing serialized document fields are retained automatically, without a second copy
 of the document schema or a deep clone of embedded payloads.

docs/releasing.md

@@ -71,7 +71,12 @@ deployment. The stable Flatpak repository is not automatically updated with nigh
    `Cargo.lock` (it changes only our own crates, never dependency versions, and needs no
    network). Inspect the diff: only `version = ` lines of workspace crates should change.
    SolidCraft does not currently implement `cargo xtask version set`.
-3. Run `cargo xtask ci` and the packaging checks in `.github/workflows/packaging-lint.yml`.
+3. Fix the design format number: run `scripts/fold-format-pending.sh`. It moves the pending
+   format changes (`crates/doc/src/format/pending/*.rs`) into the next `crates/doc/src/format/v<N>/`
+   folder, so the release writes and reads that number for good, and does nothing when nothing
+   is pending. Commit the move with the version files. (CONTRIBUTING.md, "Changing the design
+   file format".)
+4. Run `cargo xtask ci` and the packaging checks in `.github/workflows/packaging-lint.yml`.
    Commit the version files through the normal review flow and land them on `main`.
    Do not use `[skip ci]`. Record the exact commit SHA to release. If it changes, revalidate it.