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=, =theme=, 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** What a built-in theme looks like
46
47The names — =plain=, =blog=, =wiki=, =docs= — and the fact that the chosen one is written
48to =theme.css= are stable. Its CSS is not: a theme is a starting point that improves
49between releases, and a site that cannot afford that should copy the stylesheet it likes
50into its own assets and stop naming a theme.
51
52** The Rust API
53
54The crate is on crates.io so the binary can be installed with =cargo install=. The library
55exists to serve the binary, and its types move as the tool does.
56
57* The compiler floor
58
59The MSRV is *1.88*, checked in CI on every change rather than assumed — which is how it
60came to be 1.88 rather than the 1.82 orgo's own code needs. The floor is set by
61dependencies, and a dependency raising its own is invisible until someone on an older
62compiler tries to build.
63
64Raising it is a minor version, never a patch.
65
66* Upgrading
67
68#+BEGIN_SRC sh
69cargo install orgo          # or download a release binary
70orgo build content -o _site --no-cache --strict
71#+END_SRC
72
73=--no-cache= makes the first build after an upgrade a full one, so you are comparing the
74new version's output to the old version's output rather than to a cache written by a
75mixture of both. =--strict= turns a link that stopped resolving into a failure.
76
77If you keep your built site in version control, the diff after that command *is* the
78upgrade report, and the most useful review a generator can give you.