Publish the package and its documentation, and move to the papers organization

Add the Zensical documentation of the Python package (docs/package, built by the docs
workflow), merge the standard publish workflow with the setuptools-scm tag check, add the
SPDX header rule to ruff, restructure the README, and point every repository and registry
address at the Gitea organization papers.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
This commit is contained in:
alexmandClaude committed 2026-10-19 04:23:49 -04:00
1 parent bdbf03ebee
commit 30d310f64d
37 files changed
+1005 -83

No files matched your search

+8
View File
@@ -0,0 +1,8 @@
# Changelog
The changelog is one file, `CHANGELOG.md` at the root of the repository, so there is a single copy to keep in sync.
It is published with the format documentation at <https://paperspec.scient.ing/CHANGELOG.html>, and the source is at <https://git.scient.ing/papers/paperspec/src/branch/main/CHANGELOG.md>.
Its top-level headings are the versions of the formats, and a release of the Python package that changes only the code is a subsection under the current format version, as `### 0.1.1` sits under `## 0.1.0`.
The package version comes from the git tag; the format version is the one `CHANGELOG.md` and `pixi.toml` state.
When a release is tagged, the publish workflow takes the release notes from the section whose heading contains the version.
+36
View File
@@ -0,0 +1,36 @@
# About
## Status
The formats are at version 0.1.0.
Of the 32 formats, 19 are `candidate` and 13 are `provisional`; `registry/formats.json` in the repository lists each with its media type, schema, status and chapter.
The Python package is at an alpha stage (the `Development Status :: 3 - Alpha` classifier).
Its version comes from git tags, so a tag `v0.1.1` builds as 0.1.1 and later commits as 0.1.2.devN.
## Design commitments
- **The code defines the expected values.**
No expected value in a vector or fixture is typed by hand: the oracle computes it, and `paperspec check` rebuilds everything and compares it byte for byte.
- **Standard library first.**
Every module imports with the standard library alone.
Schema validation and the Ed25519 and HKDF functions import `jsonschema`, `referencing` and `cryptography` on first use, through the package's extras.
- **Clarity over speed.**
The oracle is a slow, plain program.
The verifiable random function (RFC 9381) and ML-DSA-65 (FIPS 204) are written out in Python and checked against those standards' own test vectors.
- **One Python.**
The specification pins the Unicode 16.0 character data that normalization and the character classes come from, so the package refuses to import on a Python with another version.
Python 3.14 is the only one that matches.
## Known limits and unfinished parts
This documentation describes what the code does.
Where an older guide, a doc comment or the `--help` text says something different, the code wins, and this section lists the differences.
- The package is an oracle, not a production reader or writer.
It has not been measured for speed or for large corpora; the formats are built for a team-scale corpus of hundreds of documents.
- Only `validate` and `load` work on an installed package.
`check`, `build`, `stress` and `site` need a checkout of the repository.
- `paperspec validate --correction` reports a proposals file that is not valid JSON with a Python traceback, not a one-line message.
- The Python API has no generated reference yet: [the API page](../reference/api.md) is written by hand from the code's docstrings.
- The package is not on the studio's registry until a version tag is pushed. `[CHECK: no tag exists yet]`
- Thirteen formats are `provisional` and may still change.
+14
View File
@@ -0,0 +1,14 @@
# License
paperspec is not under the studio's usual license.
Because the formats are meant to be implemented by anyone, in any product, without asking, each path of the repository keeps the license that `LICENSE.md` gives it.
| Paths | License | SPDX |
| --- | --- | --- |
| `spec/`, `docs/`, `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md` and the other prose | Creative Commons Attribution 4.0 International | `CC-BY-4.0` |
| `schemas/`, `sql/`, `context/`, `registry/`, `vectors/`, `fixtures/` | Creative Commons Zero 1.0 Universal | `CC0-1.0` |
| `src/` (the `paperspec` package and its commands), `tests/`, `tools/` | Apache License 2.0 | `Apache-2.0` |
Python source files open with an `SPDX-License-Identifier: Apache-2.0` header, which ruff checks.
All text in the fixtures is synthetic, and the keys in `fixtures/keys/` are public test keys that must never sign anything else.
The full text is in `LICENSE.md` at the root of the repository, <https://git.scient.ing/papers/paperspec/src/branch/main/LICENSE.md>.
+14
View File
@@ -0,0 +1,14 @@
# LLM assistance
Large language models (Anthropic's Claude, through Claude Code) write much of this code, its tests and its documentation, and we do not hide it.
The repository is built so that this is safe to rely on.
- **A person reviews every change.** A model proposes a commit; it does not decide one.
- **Checks gate the code.** `pixi run check` runs the formatter, the linter with the full rule set, the type checker, the Markdown lint, the pytest suite and the repository's own checker, `paperspec check`.
CI runs the same, with branch coverage that fails under 90%, and the stress test.
- **The oracle checks itself.** Every expected value in the vectors and fixtures is computed by the code and rebuilt byte for byte, so a change that alters a computed value shows up as a changed file in the diff.
- **Assisted commits are marked.** Each carries a `Co-Authored-By` trailer naming the model, and a `Claude-Session` trailer linking the session.
- **Claude's working material stays out of the repository.** Plans, notes and review reports live in an untracked `work/` folder.
The specification is the authority.
Where a model's code and a chapter disagree, the chapter wins and the code is the bug.