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:
37 files changed
+1005
-83
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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>.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user