Skip to content

chore: make the release publishable, and the workflow refuse a bad one - #51

Merged
harshuljain13 merged 2 commits into
mainfrom
chore/release-metadata
Oct 5, 2026
Merged

harshuljain13 merged 2 commits into
mainfrom
chore/release-metadata

Conversation

@harshuljain13

Copy link
Copy Markdown
Owner

Everything a package needs before an index sees it, plus three guards the workflow was missing.

Metadata that would have shipped wrong

Was Now
Summary "An open benchmark for LLM admission-control policies" — what the project was two designs ago "Standardized admission control for LLM inference"
License license = { text = "MIT" }, the deprecated form SPDX expression + license-files = ["LICENSE"], so License-Expression and the file both ship and agree by construction
Classifiers none — the PyPI page said nothing about which Pythons work 11, including 3.11–3.13
URLs none — no route from the package page back to the source Homepage / Source / Issues, plus keywords

Workflow guards

The tag must match the version. Without it, tagging v0.1.0 while pyproject says 0.0.1 publishes 0.0.1 under a v0.1.0 tag and nothing notices. The tag is the name the release is remembered by. Verified both ways:

tag v0.0.1   vs pyproject 0.0.1  -> pass
tag v0.1.0   vs pyproject 0.0.1  -> BLOCKED

twine check --strict in the build job. PyPI rejects a malformed long_description outright and its error is far less legible than this one.

skip-existing: true on TestPyPI only. Rehearsing twice at one version is normal, and a hard failure on "file already exists" makes the dry run useless. Deliberately not set for PyPI, where re-uploading a version is a mistake worth stopping.

Verified

  • Both artifacts pass twine check --strict
  • admitperf is free on PyPI and TestPyPI (both 404)
  • pypi and testpypi GitHub environments created
  • 179 passed, lint clean

One mistake worth recording

I first put [project.urls] in the middle of the [project] table. A TOML table header ends the current table, so every key after it — authors included — was read as a URL, and the build failed with URL `authors` of field `project.urls` must be a string.

Still needs you

Trusted Publishing, which requires a browser login. Values are in the PR discussion below.

Everything a package needs before an index sees it, plus three guards the
workflow was missing.

Metadata that would have shipped wrong

  Summary said "An open benchmark for LLM admission-control policies". That is
  what the project was before it became a standard for policies, and the summary
  is the first line a visitor to the PyPI page reads.

  `license = { text = "MIT" }` is the deprecated form. Now a SPDX expression with
  `license-files = ["LICENSE"]`, so the metadata carries License-Expression and the
  file itself — the LICENSE in the repo is MIT and the two now agree by
  construction rather than by coincidence.

  No classifiers and no URLs. PyPI renders classifiers as the sidebar facets, so
  without them the page said nothing about which Python versions work; and a
  package page with no route back to the source is a package nobody can evaluate.
  11 classifiers, Homepage/Source/Issues, and keywords.

Workflow guards

  The tag must match the version in pyproject. Without it, tagging v0.1.0 while
  pyproject says 0.0.1 publishes 0.0.1 under a v0.1.0 tag and nothing notices —
  the tag is the name the release is remembered by.

  `twine check --strict` in the build job. PyPI rejects a malformed
  long_description outright and its error is far less legible than this one.

  `skip-existing: true` on TestPyPI only. Rehearsing twice at one version is
  normal and a hard failure on "file already exists" makes the dry run useless.
  Deliberately NOT set for PyPI, where re-uploading a version is a mistake worth
  stopping.

A TOML mistake worth recording: I first put `[project.urls]` in the middle of the
`[project]` table. A table header ends the current table, so every key after it —
`authors` included — was read as a URL, and the build failed with "URL `authors`
of field `project.urls` must be a string".

Both artifacts pass `twine check --strict`. The name is free on PyPI and TestPyPI,
and the `pypi` and `testpypi` GitHub environments now exist.

179 passed, lint clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@harshuljain13

Copy link
Copy Markdown
Owner Author

Trusted Publishing — the one part that needs a browser

Two forms, identical except the host. Both are required, because a tag runs TestPyPI → verify → PyPI and the first hop fails without it.

1. https://pypi.org/manage/account/publishing/

2. https://test.pypi.org/manage/account/publishing/

Under "Add a new pending publisher":

Field Value
PyPI Project Name admitperf
Owner harshuljain13
Repository name AdmitPerf
Workflow name release.yml
Environment name pypi on PyPI · testpypi on TestPyPI

The environment name differs between the two forms — that is deliberate, and it is what stops a TestPyPI run from ever reaching PyPI credentials.

Use pending publisher: the project does not exist on either index yet (both return 404), and a pending publisher is how the first upload creates it. No API token is stored anywhere.

Then

Rehearse first — Actions → Release → Run workflow → target testpypi. That publishes to TestPyPI, installs the package back out of the index rather than from a path, and smoke-tests the contract on it. That round trip is the only thing that catches a missing dependency or a module left out of the package manifest, because the editable install in CI sees the working tree rather than the wheel.

When it is green:

git tag v0.0.1 && git push origin v0.0.1

A tag always does the full TestPyPI → verify → PyPI sequence; a manual run stops after TestPyPI unless it explicitly asks for pypi.

What the verify step actually asserts

Not just that it imports — a package that installs and then cannot make a decision has passed the wrong test:

busy = Wall()({"vllm:kv_cache_usage_perc": 0.95}, request_id="r1")
assert not busy.admitted and busy.status == 503
idle = Wall()({"vllm:kv_cache_usage_perc": 0.10}, request_id="r2")
assert idle.admitted and idle.status == 200
assert KV_PRESSURE.read({}) is None   # absence is never zero

The publisher was registered on PyPI with environment `pypi-admitperf`, so the
workflow has to say that. PyPI checks the environment name in the OIDC claim, and
a mismatch fails at the publish step with a rejected token rather than anything
that names the cause — so this is worth being exact about rather than approximately
right.

  pypi      job -> environment pypi-admitperf
  testpypi  job -> environment testpypi-admitperf

Both now exist on the repository; the unused `pypi` and `testpypi` environments
are removed so there is nothing to pick the wrong one from. The header comment
records both forms, including that the names differ between indexes on purpose —
that difference is what stops a TestPyPI run reaching PyPI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@harshuljain13
harshuljain13 requested a review from Parv17k October 5, 2026 11:47
@harshuljain13 harshuljain13 self-assigned this Oct 5, 2026
@harshuljain13 harshuljain13 added this to the 0.1.0 milestone Oct 5, 2026
@harshuljain13
harshuljain13 merged commit 75afc92 into main Oct 5, 2026
4 checks passed
@harshuljain13
harshuljain13 deleted the chore/release-metadata branch October 5, 2026 11:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant