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.
An adversarial review of the release, and four of its findings were things
PyPI never lets you replace once uploaded.
- rust-version said 1.74. clap has needed 1.85 since 4.6, and cargo
hard-errors rather than warning, so the sdist advertised a floor it could
not build on. docs/releasing.md sends macOS and Windows users to that
sdist.
- The wheel was classified Development Status :: 4 - Beta on a release the
changelog calls stable, with none of the Python version classifiers PyPI
indexes on.
- Six README links were relative. PyPI resolves them against the project
page, so every one 404'd there, as they do on the live 0.2.0 page now.
- in that order packs the wheel into the
sdist. The tarball on disk was 431KB with an x86-64 binary inside it.
Also: twine upload gains --skip-existing, so a retry after a partial upload
finishes rather than dying on a version that cannot be reused; twine check
gains the renderer that makes it parse the description at all, without which
it returns None and reports PASSED; and the README no longer claims a
twenty-year sweep the test did not run, because 366 * 21 / 4 is five years.
The test now runs the twenty-one it was named for.
The crates.io name belongs to an unrelated project, which the README now says
rather than leaving a reader to find out from cargo.
Three Eastern Catholic jurisdictions borrowed the Ruthenian ruleset, so a
Melkite, a Romanian Greek Catholic and a Ukrainian Greek Catholic were each
told that fourteen days a year bound them under the particular law of the
Metropolia of Pittsburgh. That is the exact error the level/obligation split
exists to prevent, committed by the library itself.
Every Eastern Catholic church legislates its own fasting discipline. Those
three are now shown at the Typikon with nothing reported as binding, which is
the honest position: the calendar is known, the law is not. Their entries say
so and a test holds it, asserting both that no jurisdiction but ruthenian
carries that ruleset and that the three claim no binding days.
The README gains a section on these churches, since supporting them was never
meant to be something a reader had to infer from the jurisdiction list.
The config file held one key while the program grew three axes, so
--set-default recorded the jurisdiction and silently dropped the discipline
and the usage. On this machine that produced exactly the failure it sounds
like: a terminal reckoning by ROCOR beside a desktop widget reckoning by the
Ruthenian calendar, both correct, neither agreeing.
--set-default now writes whatever was given alongside it, and an ordinary run
reads all three back with flags still winning over the file.
For an Eastern Catholic church these are sharply different questions and the
library was collapsing them. Ruthenian particular law binds on four kinds of
day in the year; the tradition those parishes actually keep is the Byzantine
fast entire. Reporting only the law made a week of the Great Fast read as
'no meat, fish, eggs or dairy' seven times over, which is the legal floor and
not the fast.
--typikon shows the day at the Typikon's discipline while the obligation
still comes from the jurisdiction's own law, because that is the part only it
can say. The Ruthenian rule now answers 'what binds here' separately from
'how is this day kept', which is what makes the two composable at all.
Three tests hold the seam: exactly the same days bind whichever discipline is
displayed, the binding minimum is never stricter than the level shown, and
the flag is a no-op for a jurisdiction already on the Typikon.
Both keep the same Typikon and read it a little differently, and until now
this library silently picked one reading and called it the Typikon. Two
differences are modelled, each one visible in the output and named in the
day's reason:
- The Protection of the Theotokos is a great feast in Slavic usage. Greek
practice ranks it lower, and the Church of Greece keeps it on 28 October
besides. This has teeth: rank is what lifts a Wednesday or Friday fast.
- Greek practice admits fish on any day of the Nativity Fast but Wednesday
and Friday until 17 December; Slavic practice keeps fish to Saturdays and
Sundays throughout.
Every jurisdiction carries the usage its books follow, and --tradition
overrides it for a parish that does not match its jurisdiction's default. The
difference in the calendar lives in a data overlay compiled in beside the
common menologion, which is where a local church's own commemorations would
go; the difference in the fast lives in the rule, because that is where it is.
Each rank also now carries the mark the books print beside it, circled cross,
cross and Jerusalem cross for great, vigil and polyeleos. Unicode has no glyph
for the polyeleos sign, a cross over a half-circle, so the Jerusalem cross
stands in as digital calendars generally settle on.
--format takes text, json, csv, tsv or ics. --json and --ics stay as
shorthand, because the widgets already call them.
csv and tsv are RFC 4180 quoted, one header row, one row per day, with
commemorations joined by a semicolon: a cell that is itself a table is worse
than a cell you have to split. --list-fields prints the twenty columns,
--fields picks a subset in the order you name them, and a column that does
not exist is caught before anything is printed rather than silently emitting
an empty cell.
--no-emoji drops the glyphs from every format, including the emoji field in
the JSON, and collapses the column in the text output rather than leaving a
hole where a glyph used to be.
Python was never the house language here: the mw-* desktop surface it came
from is 39 bash scripts and was exactly one Python script, the one this was
extracted from. What it cost was distribution, a widget dependency that
needed pipx and a Python floor, and 24ms of interpreter startup before a line
of the program ran.
The port is verified rather than asserted. Both implementations were run over
199,446 day-records, 26 jurisdictions across 21 years, with every field of
every record required to match; the JSON, the iCalendar and 480 renderings of
the text output are identical too. examples/dump.rs is the harness.
What the type system actually buys, which is less than the usual claim and
more than nothing:
- Level is an ordered enum, strictest first, so reads as 'a is
stricter' and relaxed_to() is the one place a feast can lift a fast. No
rule can get the direction backwards.
- Date is a newtype over the Julian Day Number and JulianDate is a separate
type, so a civil date and an ecclesiastical one cannot be mixed up. That
confusion is the single most common way calendar code goes wrong.
- Octets is a newtype in the iCalendar folder, because the bug it replaced
counted characters against a limit RFC 5545 states in octets.
- Movables is a struct, not a map, so a mistyped key is a compile error
rather than a None at the far end of the program.
Of the six defects an adversarial review found in the Python, exactly one had
a shape a type system would have caught. The rest were logic, and the tests
came with them.
The menologion is compiled in with include_str!, so the binary answers on its
own: 930KB, no runtime, 1.2ms to start against Python's 36ms.
funkpower