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

+13 -5
View File
@@ -1,7 +1,7 @@
# Contributing
This page is for anyone who wants to fix the specification, change a format or add an example.
Propose a change as a pull request on the repository at <https://git.scient.ing/infra/paperspec>.
Propose a change as a pull request on the repository at <https://git.scient.ing/papers/paperspec>.
## What a change needs
@@ -16,10 +16,18 @@ The schemas, SQL, registries, vectors and fixtures then follow the chapter ([spe
Change the oracle in [src/paperspec/](src/paperspec/) to apply the rule, and add the case that shows it to [src/paperspec/cli/build.py](src/paperspec/cli/build.py): a vector, a fixture or a broken package in `fixtures/invalid/`.
Then run `pixi run build`, which rewrites `fixtures/` and `vectors/`.
4. **Run the checks.**
`pixi run check` must end with `All checks pass.`
Without pixi, install the checkout with `pip install -e ".[tools]"` on Python 3.14, then run `paperspec check`.
`pixi run check` must pass and end with `All checks pass.`
Without pixi, install the checkout with `pip install -e ".[tools]" --group dev` on Python 3.14, then run `paperspec check` and the commands in [How the checks run](#how-the-checks-run).
5. **Record the change** in [CHANGELOG.md](CHANGELOG.md).
## How the checks run
The Python code follows the studio's standard: ruff formats and lints it with `.ruff.toml`, ty checks its types with `ty.toml`, and pytest tests it with `.pytest.ini` and `.coveragerc`.
`pixi run check` runs, in order, `fmt-check` (ruff format), `lint` (ruff check), `typecheck` (ty), `lint-md` (markdownlint), `test` (pytest) and `verify` (`paperspec check`, the repository's own checker).
`pixi run fmt` and `pixi run lint-fix` apply the formatter and the safe lint fixes, and `pixi run hooks` installs the git hooks that run the same tools before each commit.
The tests in `tests/` take their data from the vectors and fixtures, so a rule change that a vector or a fixture covers shows up in both the suite and `paperspec check`.
CI runs `fmt-check`, `lint`, `typecheck` and `cov` (the suite with branch coverage, which fails under 90%), then `lint-md`, `verify` and `stress`.
## Versions
A change that makes a valid file invalid, or that changes a computed value, is a breaking change and needs a new major version of the format, with a migration.
@@ -40,7 +48,7 @@ A release that changes only the code takes the next patch version and records it
Pushing the tag publishes the package to the Gitea package registry ([deploy/](deploy/README.md#publish-the-python-package)).
Before tagging:
1. `pixi run check` passes on Linux and macOS, which the workflow in `.gitea/workflows/` runs on every push.
1. `pixi run check` passes, on macOS as well as on Linux, where the workflow `.gitea/workflows/ci.yml` runs the checks on every push to `main` and `dev` and on every pull request.
The check also confirms that every count the prose states (formats, schemas, vectors, broken packages) matches the repository, and that `pixi.toml`, the registries and `src/paperspec/cli/build.py` state the same version.
2. `paperspec stress` passes with its default seed, and with one or two others.
3. The website is published from the release ([deploy/](deploy/README.md)), and the JSON-LD context at `https://paperspec.scient.ing/context/scienting-1.jsonld` and a schema at its `$id` both answer with their media types.
@@ -51,7 +59,7 @@ Before tagging:
## Writing
The checker enforces two rules on every Markdown file: one sentence per line, and US spelling.
`pixi run lint` runs markdownlint with the repository's settings.
`pixi run lint-md` runs markdownlint with the repository's settings.
Define each term where it first appears, because the guides and READMEs are written for newcomers as well as implementers.
All fixture text is synthetic, written for the fixtures.