feat: publish the package from CI, and clean up its references

Publishing
- .gitea/workflows/publish.yml publishes paperspec to the instance's PyPI
  registry (/api/packages/infra/pypi) when a v* tag is pushed: it checks
  the repository, builds the sdist and wheel, refuses to upload unless the
  built version equals the tag, runs twine check --strict, and uploads
  with the secrets PACKAGE_USER and PACKAGE_TOKEN (--skip-existing, so a
  rerun on the same tag is safe). Run by hand, it refuses anything but a
  tag.
- pixi dev environment: twine >= 6.1 (the first that reads Metadata 2.4),
  and `dist` (sdist and wheel) replaces the `wheel` task.
- deploy/README.md: how to set up the secrets, release a version, and
  install from the registry with pixi, uv or pip, tying paperspec to the
  registry where the installer allows it.
- CONTRIBUTING.md "Releasing": a tag versions the package; a format
  change takes the new format version as the top CHANGELOG heading, and a
  code-only release takes the next patch as a subsection, as 0.1.1 does.
- pyproject: fallback_version 0+unknown for source trees without git; the
  license expression is Apache-2.0 AND CC0-1.0, for the code and the data
  the wheel carries.

Cleanup (from an audit of every reference to the package)
- spec/00 lists src/ (the package) and tools/ (how to run it), and no
  longer says the reference implementation is not a library.
- Stale explanations fixed in pixi.toml, .gitignore, the Caddyfile, the
  vectors, context, sql and tools READMEs, docs/examples.md, docs/faq.md,
  spec/01, docs/rationale.md and docs/comparison.md: the commands, what
  they need (the tools extra), the fixture folder hale2026harmonic-damb,
  and three lines that held two sentences.
- tools/README.md counts all six commands, says what needs which extra
  (package.validate and corrections.gate need [schema]), and that the
  vectors ship but the fixtures they name do not.
- The CLI's install and clone hints point at the registry instructions and
  an https clone URL; schema.py raises an ImportError naming
  paperspec[schema], as crypto.py does for [crypto].
- check's Unicode check now guards the package's pinned constant.
- site skips build/, dist/ and *.egg-info.
- CHANGELOG 0.1.1 describes the final state.

pixi run check passes (as `python -m paperspec check`); the rebuild is
byte-identical. pixi.lock needs `pixi lock` for twine before pushing: the
publish workflow installs with --locked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
alexmandClaude committed 2026-10-15 09:41:26 -04:00
1 parent 88379d152c
commit 516148146f
25 files changed
+224 -61

No files matched your search

+7 -4
View File
@@ -28,7 +28,10 @@ Packaging, commands and lazy imports only; the formats stay at 0.1.0, and no com
- The package version comes from git tags through setuptools-scm.
- The base package has no dependencies and requires Python 3.14, the only version with the Unicode 16.0 character data the specification pins, and refuses to import under any other Unicode version; the extras `paperspec[schema]` (`jsonschema`, `referencing`), `paperspec[crypto]` (`cryptography`) and `paperspec[tools]` (both) cover `schema` and the HKDF and Ed25519 functions of `crypto`, which now import their packages on first use.
- `paperspec.resources.path` finds the schemas, SQL and vectors in an installed wheel and in an editable install alike.
- The programs in `tools/` become subcommands of one command, `paperspec`, in `src/paperspec/cli/`: `paperspec validate`, `load`, `check`, `build`, `stress` and `site`, which the pixi tasks and the workflow run, and which `python -m paperspec` also runs.
- `paperspec --help` says which commands work anywhere and which need a checkout, and each command's `--help` gives advice and examples; a misspelled command gets a suggestion.
- `src/` is Apache-2.0, as `tools/` was.
- The pixi workspace installs the package editable, and a `dev` environment builds the wheel with `pixi run -e dev wheel`.
- The programs in `tools/` become subcommands of one command, `paperspec`, in `src/paperspec/cli/`: `paperspec validate`, `load`, `check`, `build`, `stress` and `site`, which the pixi tasks and the workflows run, and which `python -m paperspec` also runs.
The scripts `tools/*.py` are gone, so `python3 tools/check.py` and the like no longer work; `tools/` keeps the page that documents the commands.
- `paperspec --help` says which commands work anywhere and which need a checkout, each command's `--help` gives advice and examples, a misspelled command gets a suggestion, and `paperspec --version` prints the package version and the Unicode version it pins.
- `paperspec load` refuses `--built-from` and `--store` without `--bundle`, where it used to ignore them.
- `src/` is Apache-2.0, as `tools/` was, and the package metadata states `Apache-2.0 AND CC0-1.0` for the code and the data it carries.
- The pixi workspace installs the package editable, and a `dev` environment builds the sdist and the wheel with `pixi run -e dev dist`.
- Pushing a version tag publishes the package to the Gitea package registry through `.gitea/workflows/publish.yml` ([deploy/](deploy/README.md#publish-the-python-package)); a release tag versions the package, and [CONTRIBUTING.md](CONTRIBUTING.md#releasing) says how that relates to the format version.