diff --git a/.gitignore b/.gitignore index d711f27..da5ea15 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,4 @@ **/*.rs.bk .venv/ *.egg-info/ - -# python build and test artefacts -__pycache__/ -*.py[cod] +/dist diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..47308ea --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,64 @@ +# Changelog + +Notable changes, in the terms [docs/versioning.md](docs/versioning.md) sets out. +**Calendar** entries change what a day reports, whatever the version number +does. + +## 1.0.0 + +First stable release. The public surface is now the one described in +[docs/versioning.md](docs/versioning.md), and breaking it requires a major +version. + +### Calendar + +Everything below changes what a day reports against pre-1.0 versions. + +- A saint of vigil or polyeleos rank now relaxes a weekday of a fast: to wine + and oil inside the Great Fast, as far as fish in the Nativity, Apostles' and + Dormition Fasts. 74 days across 2020 to 2030 had been reported stricter than + any published calendar keeps them, St Nicholas and the Forty Martyrs of + Sebaste among them. +- The Annunciation is tested before Great Friday and Great Saturday. In the + years it falls on either it had been absorbed into them: reported as a total + fast, demoted to a bullet, and its rank overwritten. It now lifts those days + to wine and oil. +- Lazarus Saturday and Palm Sunday belong to the Great Fast season. They had + belonged to none, so rules that key on the season fell through and the + Byzantine Catholic jurisdictions reported no fast at all on Palm Sunday. +- The eves of the Nativity and Theophany relax to wine and oil when they fall + on a Saturday or Sunday. +- Greek usage admits fish on any day of the Nativity Fast but Wednesday and + Friday until 17 December. Slavic usage keeps fish to Saturdays and Sundays. +- The Protection of the Theotokos is a great feast in Slavic usage. +- The Nativity of the Forerunner is ranked a great feast. +- Melkite, Romanian Greek Catholic and Ukrainian Greek Catholic jurisdictions + no longer report any day as binding. They had borrowed Ruthenian particular + law, which is not their law. + +### Added + +- Greek and Slavic usage as an explicit axis, per jurisdiction and overridable + with `--tradition`. +- `--typikon` and `--no-typikon`: show a day at the Typikon's full discipline + while still reporting what a church's own particular law obliges. +- `--format csv` and `--format tsv`, with `--fields` and `--list-fields`. +- `--no-emoji`. +- The rank marks the liturgical books print, as the `sign` field. +- ACROD, the American Carpatho-Russian Orthodox Diocese. +- `--set-default` remembers the tradition and the discipline alongside the + jurisdiction. + +### Changed + +- Rewritten in Rust. It ships as one static binary with the menologion compiled + in, and as an abi3 wheel. The port was verified by running it against the + previous implementation over 199,446 day-records, 26 jurisdictions across 21 + years, requiring every field of every record to match. +- iCalendar folds content lines on octets, which is what RFC 5545 counts. It + had folded on characters, so a line with emoji ran up to 80 octets against a + 75-octet limit. +- The seven-day view elides a long commemoration on a word boundary and takes + its width from the terminal, rather than cutting at 44 characters mid-word. +- A malformed `--date` or an out-of-range `--year` is a usage error, not a + traceback. diff --git a/Cargo.lock b/Cargo.lock index 2049b86..eb32428 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -334,7 +334,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca" [[package]] name = "typikon" -version = "0.2.0" +version = "1.0.0" dependencies = [ "clap", "pyo3", diff --git a/Cargo.toml b/Cargo.toml index d12fa6b..ffa17e9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "typikon" -version = "0.2.0" +version = "1.0.0" edition = "2021" rust-version = "1.74" description = "The Orthodox liturgical day: feasts, seasons and the fast, computed rather than fetched" diff --git a/README.md b/README.md index 3db3c0c..fe9fc84 100644 --- a/README.md +++ b/README.md @@ -425,8 +425,11 @@ It lands in `~/.local/share/typikon/` and is overlaid automatically. ## Further reading -[docs/calendars.md](docs/calendars.md) sets out which churches keep which -reckoning, how the split came about, what is modelled here and what is not. +- [docs/calendars.md](docs/calendars.md) sets out which churches keep which + reckoning, how the split came about, what is modelled here and what is not. +- [docs/versioning.md](docs/versioning.md) says what counts as the public + surface, and how a correction to the calendar itself is announced. +- [CHANGELOG.md](CHANGELOG.md) carries those announcements. ## Accuracy diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 0000000..f87b04a --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,92 @@ +# 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 +``` + +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. + +### 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 exit codes (0 success, 2 usage error), and the +column names `--format csv` accepts. `--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. +- **The `reason` strings.** They explain a decision to a reader; they are not + identifiers. Key on `fast`, `season` and `obligation`. +- **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`. diff --git a/src/day.rs b/src/day.rs index 089265c..cf00d69 100644 --- a/src/day.rs +++ b/src/day.rs @@ -36,7 +36,13 @@ pub struct Day { pub obligation: Option, pub binds: Level, pub pascha: Date, + /// Days from this day to Pascha, **signed**, and to the Pascha of this + /// day's own civil year. Negative after Pascha has passed: 31 December + /// reports about -263, not the couple of hundred days until the next one. pub days_to_pascha: i32, + /// How far the Julian reckoning currently lags the Gregorian one: 13 until + /// 14 March 2100, 14 after it. Reported for every jurisdiction, including + /// the ones that do not use it. pub julian_offset: i32, }