Skip to content

DOC: Correct the release process guide - #2511

Open
varunj-msft wants to merge 1 commit into
microsoft:mainfrom
varunj-msft:varunj-msft/v1.1.0-Release-Doc-Fixes
Open

DOC: Correct the release process guide#2511
varunj-msft wants to merge 1 commit into
microsoft:mainfrom
varunj-msft:varunj-msft/v1.1.0-Release-Doc-Fixes

Conversation

@varunj-msft

@varunj-msft varunj-msft commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Description

Follow-up to #2510, which should merge first: the step 5 instruction to confirm GitHub Actions checks on the release branch is only true once those triggers are fixed.

The guide told releasers to set the version in pyrit/__init__.py, but that file has held no __version__ literal since the lazy export change; the value now lives in pyrit/_version.py. Following the guide verbatim publishes a wheel whose runtime version still reports the development suffix while the packaging metadata reports the release version. Step 4 now lists every file that carries the version, warns about dependency versions that resemble it, and shows how to confirm no development suffix survives.

The rest of the corrections come from walking the process end to end:

  • The version choice section still described the pre-1.0 scheme. It now states that a release takes the next minor version and that the patch version is reserved for fixes to an existing release.
  • The guide asked for passing integration, end-to-end and partner tests on the version being released without saying how to get them. Those pipelines declare trigger: none and schedule only main, so cutting a release branch produces no run at all, and an absent result reads like a passing one. The validation step now says to queue each one manually against the release branch.
  • The step that verifies the built wheel could not fail. It unset PYTHONPATH but still ran from inside the checkout, and python -c puts the current directory on sys.path, so it imported the working tree and reported the working tree's version rather than the wheel's. It now runs from outside the repository.
  • Internal deployment steps are collected into their own section, which records that a production deployment restarts the application and clears its in-memory state, so onboarded targets are lost, and asks the releaser to settle who queues that deployment rather than assuming it falls to either side.

Smaller fixes: remove stale dist/ artifacts before building, upload to PyPI by explicit filename rather than by wildcard, search for the skipped notebook lists rather than relying on a remembered count, use origin when fetching before a cherry-pick, and stop moving the tag once the version is published.

Tests and Documentation

Documentation only, plus the printed next-step text in build_scripts/prepare_package.py and a comment correction in .github/docs-versions.yml. python -m build_scripts.validate_docs passes and pytest tests/unit/build_scripts/ passes 266 tests.

No notebooks are affected, so JupyText was not run.

The guide told releasers to set the version in `pyrit/__init__.py`, but that
file has held no `__version__` literal since the lazy export change; the
value now lives in `pyrit/_version.py`. Following the guide verbatim
publishes a wheel whose runtime version still reports the development suffix
while the packaging metadata reports the release version. Step 4 now lists
every file that carries the version, warns about dependency versions that
resemble it, and shows how to confirm no development suffix survives.

The version choice section still described the pre-1.0 scheme. It now states
that a release takes the next minor version and that the patch version is
reserved for fixes to an existing release.

The guide asked for passing integration, end-to-end and partner tests on the
version being released without saying how to get them. Those pipelines all
declare `trigger: none` and schedule only `main`, so cutting a release branch
produces no run at all, and an absent result reads like a passing one. The
validation step now says to queue each one manually against the release
branch.

Internal deployment steps are collected into their own section. That section
records that a production deployment restarts the application and clears its
in-memory state, so onboarded targets are lost and an unannounced run can
interrupt work in progress, and asks the releaser to settle who queues the
deployment rather than assuming it falls to either side. It names the pipeline
definition, separates the reason for each precondition, and closes on a
recorded deployed commit, because the image is built from a commit rather
than from the published package and so cannot be checked against the tag.

The step that verifies the built wheel could not fail. It unset `PYTHONPATH`
but was still run from inside the checkout, and `python -c` puts the current
directory on `sys.path`, so it imported the working tree and reported the
working tree's version. It now runs from outside the repository.

Other corrections: remove stale `dist/` artifacts before building, verify the
installed version without the repository shadowing it, upload to PyPI by
filename rather than by wildcard, search for the skipped notebook lists
rather than relying on a filename pattern or a remembered count, use `origin`
when fetching before a cherry-pick, stop moving the tag once the version is
published, and stop suggesting a wildcard upload from the packaging script.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants