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
+13
-5
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user