Project history¶
wend's design decisions are recorded in a development journal: dated Markdown files in
docs/journal/ of the
repository. Each entry covers one piece of work and records what was built, the decisions
behind it and what was measured, so that the next change starts from the reasons. The
format is described in
docs/JOURNAL.md.
Claims in an entry carry a label:
- [Fact]: checked against a primary source: the code, a test, an essay or a benchmark;
- [Measured]: a number from a stated measurement;
- [Interpretation]: a reading of the facts;
- [Proposal]: a direction offered for decision;
- [Decision]: what was chosen, and why.
Where to start¶
The trajectory entry tells the story from the Future Paths essays to the rebuilt library, and is written to be read first. Future Paths and wend gives the same mapping, brought up to date.
The rebuild¶
These entries record how the 0.1 release was examined and replaced.
| entry | what it records |
|---|---|
| Retrospective | what 0.1 was, the unsound construction-time rewrites, the loss of t-string formatting, and the performance estimates |
| Rebuild | the segment normal form, matching, discovery, compilation and inference |
| Audit | an adversarial audit of the rebuild against its contract |
| Messy trees | inference and matching on real, irregular trees, and t-string fidelity |
| Trajectory | the whole story so far, and the roadmap it implies |
Features¶
These entries record the features built on the normal form, one entry per piece of work.
| entry | what it records |
|---|---|
| Conditions | pre- and postconditions, steps, and what can be checked when, including what static checking could add |
| Unions | unions, Alt, first and queries |
| Schemas | directory schemas, declared and inferred |
| Construction | making construction and bind faster |
| Shared compilation | what optimisation still buys: compile_many |
| Lineage | lineage before and after a path exists, and content addressing |
| Inference kinds | inferred layouts of files and of directories |
| Bindings | defaults, bindings from objects, counters, anchors and Pydantic |
| Match gaps | the last format-spec differences between render and match |
| Filesystem backends | the filesystem protocol, fsspec and prefix listing |
| Documentation site | how this site is built, checked and published |
The number at the end of each file name is the issue or pull request the entry belongs to.