krz/orgo

 1#+TITLE: Versioning and upgrades
 2#+DESCRIPTION: What a version number promises, what it does not, and how to upgrade safely.
 3#+LEDE: The stable surface is what you build a site against, not what the code happens to do.
 4
 5A generator you point at ten years of writing needs to be boring about compatibility.
 6This page says exactly what is promised.
 7
 8* The stable surface
 9
10Changing any of this incompatibly requires a major version.
11
12| Stable | What that covers |
13|--------+------------------|
14| =orgo.toml= keys | Their names, types and meaning. |
15| Template context | =page=, =site=, =nav=, =root=, =pages=, =group=, =groups=, =paginator=, =stylesheet=, and the =absolute=, =rfc822= and =truncate= filters. |
16| The CLI | Command names, flags and exit codes. |
17| URLs | How a source path becomes an output path, =#+SLUG:= included. |
18
19*URLs are on that list deliberately.* A generator that quietly moves your pages breaks
20every link anyone has ever made to you, and no upgrade note fixes an inbound link.
21
22Adding things — a new config key, a new template variable — is a minor release. Nothing
23you already wrote stops working.
24
25* What is not stable
26
27Three things move freely, so the list above can hold still.
28
29** The incremental cache
30
31=<output>/.orgo-cache.json= is versioned and discards itself on a mismatch. A cache
32format bump means one full rebuild, and nothing else. It is never a correctness
33dependency: a missing, stale or corrupt cache produces exactly the same site, more slowly.
34
35** Rendered HTML details
36
37orgo aims at what Emacs exports from the same file, and closing a gap changes markup.
38That is the product working rather than a regression — but it is called out in the release
39notes every time, because your stylesheet is downstream of it.
40
41The class names the documentation names are the ones to write CSS against:
42=post-list=, =post-list-item=, =figure-number=, =table-number=, =section-number-N=,
43=footnote-ref=, =verbatim=, and the =on=/=off=/=trans= classes on checkbox items.
44
45** The Rust API
46
47The crate is on crates.io so the binary can be installed with =cargo install=. The library
48exists to serve the binary, and its types move as the tool does.
49
50* The compiler floor
51
52The MSRV is *1.88*, checked in CI on every change rather than assumed — which is how it
53came to be 1.88 rather than the 1.82 orgo's own code needs. The floor is set by
54dependencies, and a dependency raising its own is invisible until someone on an older
55compiler tries to build.
56
57Raising it is a minor version, never a patch.
58
59* Upgrading
60
61#+BEGIN_SRC sh
62cargo install orgo          # or download a release binary
63orgo build content -o _site --no-cache --strict
64#+END_SRC
65
66=--no-cache= makes the first build after an upgrade a full one, so you are comparing the
67new version's output to the old version's output rather than to a cache written by a
68mixture of both. =--strict= turns a link that stopped resolving into a failure.
69
70If you keep your built site in version control, the diff after that command *is* the
71upgrade report, and the most useful review a generator can give you.