1.0.0

Nobody depends on this yet, which makes now the moment to commit to a surface
rather than later when someone does.

docs/versioning.md says what that surface is. A calendar has a wider one than
a library usually does: the JSON shape, the fasting level names and their
order, the jurisdiction keys, the command line, and the two language APIs are
all things a caller can reasonably build on, and only one of them is a
function signature. The text output, the reason strings and the menologion's
wording are explicitly not.

It also names the category semver has no word for. A correction to a fast rule
or a feast rank breaks no interface, so it is a patch; but it changes what the
program tells someone to eat. Those are called out in the changelog under
Calendar whatever the version does, and CHANGELOG.md starts by listing every
one of them against pre-1.0 behaviour.

daysToPascha is documented as signed, counting to the Pascha of that day's own
civil year, which it always was and nothing said.

.gitignore

@@ -2,7 +2,4 @@
 **/*.rs.bk
 .venv/
 *.egg-info/
-
-# python build and test artefacts
-__pycache__/
-*.py[cod]
+/dist

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.

Cargo.lock

@@ -334,7 +334,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "typikon"
-version = "0.2.0"
+version = "1.0.0"
 dependencies = [
  "clap",
  "pyo3",

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"

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
 

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`.

src/day.rs

@@ -36,7 +36,13 @@ pub struct Day {
     pub obligation: Option<Obligation>,
     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,
 }