mirror of
https://git.pumpin.online/funkpower/typikon.git
synced 2026-10-23 03:07:12 +00:00
funkpower
83447db964
Two adversarial reviews of the release. Both said do not ship, and they were right twice over. The seven-day view panicked. elide() cut a title at cut.len() / 2, a byte index into a string it had counted in characters, and every movable feast title carries an em dash: at fourteen terminal widths, 80 among them, it aborted with exit 101 on the README's own headline command. tests/elide.rs now cuts every title the program can print at every width it can be asked to print at. The changelog's first Calendar entry was false. It said a vigil or polyeleos saint reaches fish in the three lesser fasts; the code gives wine and oil to every rank but great, and caps the Dormition Fast at wine and oil whatever the rank. A reader in the Dormition Fast was told this release let a saint bring fish. docs/versioning.md makes that section a contract, so a wrong entry there is worse than a wrong comment. The Python bindings read the config file where the CLI reads the environment first, so TYPIKON_JURISDICTION moved one and not the other and the two answered for different churches on the same machine. CI now asserts they agree, and runs the README example checker, which was standing between the docs and reality with nothing running it. Three changes to the surface, made now because after 1.0.0 they are a major version: binds is null rather than the string none where a church legislates no binding fast at all; iCalendar UIDs carry the tradition and the discipline, which two feeds of the same day were sharing while saying different things; and Date's Julian Day Number is behind an accessor rather than a public field. fastLabel, emoji and reason are documented as presentation. The fields are stable, the wording is not, and freezing three human-facing strings for a major version was not the intent.
107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
# Versioning
|
|
|
|
`typikon` follows semantic versioning from 1.0.0 onward. This page says what
|
|
that covers, because a calendar has a wider public surface than a library
|
|
usually does: four things depend on it, and only one of them is a function
|
|
signature.
|
|
|
|
## What is stable
|
|
|
|
A **major** version is required to change any of these.
|
|
|
|
### The JSON
|
|
|
|
Field names, their types, and whether a field can be null. Front ends are the
|
|
thing most likely to be written by someone else, and a schema that shifts
|
|
underneath them is a bad neighbour. As of 1.0.0:
|
|
|
|
```
|
|
date weekday jurisdiction calendar churchDate season cycle feast rank sign
|
|
tradition title commemorations fast fastLabel emoji reason obligation binds
|
|
pascha daysToPascha julianOffset
|
|
```
|
|
|
|
`fastLabel`, `emoji` and `reason` are **presentation**: the fields are always
|
|
there, and their wording is not stable. Key on `fast`, `season`, `rank`,
|
|
`obligation` and `binds`.
|
|
|
|
Adding a field is a **minor** change, so read the object by key and ignore what
|
|
you do not recognise. `season`, `cycle`, `feast`, `rank`, `sign` and
|
|
`obligation` are null on ordinary days.
|
|
|
|
Two semantics worth stating because the names do not carry them:
|
|
|
|
- **`daysToPascha` is signed**, and counts to the Pascha of that day's own
|
|
civil year. It is negative after Pascha has passed. 31 December reports
|
|
about -263, not the days until the next one.
|
|
- **`julianOffset`** is reported for every jurisdiction, including those that
|
|
do not use the Julian menologion.
|
|
- **`binds` is null unless the day binds.** Most jurisdictions legislate no
|
|
binding fast at all, which is a different fact from a day that happens to
|
|
oblige nothing, and the null says which.
|
|
|
|
### The fasting levels
|
|
|
|
`strict` `xerophagy` `wine_oil` `fish` `dairy` `none`, and their order from
|
|
strictest to laxest. Code that compares them may rely on that order.
|
|
|
|
### The jurisdiction and calendar keys
|
|
|
|
`old` `new` `western`, and every jurisdiction key `typikon --list` prints.
|
|
A key is never renamed or removed in a minor version. New ones are added
|
|
freely.
|
|
|
|
### The command line
|
|
|
|
Flag names and what they do, the column names `--format csv` accepts, and the
|
|
exit codes:
|
|
|
|
| | |
|
|
|---|---|
|
|
| 0 | it answered |
|
|
| 1 | it ran and the result is incomplete, as when a fetched menaion is missing days |
|
|
| 2 | it was asked for something it could not do | `--json` and `--ics` remain as shorthand
|
|
for `--format`.
|
|
|
|
### The Rust and Python APIs
|
|
|
|
Public items in the crate root and the modules `calendars`, `paschalion`,
|
|
`seasons`, `fasting`, `jurisdictions`, `menologion`, `day`, `export`, `config`;
|
|
and in Python, the module's functions and the attributes of `Day`.
|
|
|
|
`Day.to_dict()` in Python carries the same fields as the JSON, in snake_case
|
|
rather than camelCase, which is the one deliberate difference between them.
|
|
|
|
## What is not stable
|
|
|
|
- **The text output.** It is for a person to read, and it changes when a better
|
|
arrangement is found. Parse the JSON, CSV or TSV instead.
|
|
- **`reason`, `fastLabel` and `emoji`.** They explain and present a decision to
|
|
a reader; they are not identifiers. The fields themselves are stable, their
|
|
wording is not.
|
|
- **The menologion.** Commemorations get added, corrected and reworded. See
|
|
below.
|
|
- **Anything not listed above**, including every private item and the layout of
|
|
fetched menaia on disk.
|
|
|
|
## Corrections to the calendar itself
|
|
|
|
This is the category semver does not have a word for, and it is the one that
|
|
matters most here.
|
|
|
|
A correction to a fast rule, a feast rank or a commemoration changes what the
|
|
program tells you about a day. It breaks no interface, so by semver it is a
|
|
patch. But it changes what someone is told to eat, and a user who has noticed a
|
|
disagreement with their parish deserves to know it moved.
|
|
|
|
So: **every change to what a day reports is called out in the changelog under
|
|
"Calendar"**, with the days affected, whatever the version number does. If a
|
|
correction changes a day you care about, the changelog is where it will say so.
|
|
|
|
Adding a jurisdiction, a menaion or a tradition is a minor version. Correcting
|
|
an existing one is a patch, and is announced.
|
|
|
|
## Releasing
|
|
|
|
See [releasing.md](releasing.md). The version lives only in `Cargo.toml`.
|