Prepare the 1.0.0 release: README, CHANGELOG, packaging, release workflow#113
Merged
Conversation
roed-math
force-pushed
the
release-1.0
branch
2 times, most recently
from
July 22, 2026 00:20
8225542 to
e5b1d38
Compare
This was referenced Jul 22, 2026
Rewrite README.md as the PyPI landing page: a dict-in/dict-out pitch, a verified quickstart (config.ini + PostgresDatabase(create=True) + create_table + insert_many + search), a feature list covering the 1.0 surface (joins, $col/$size, bulk loading with reload/revert, stats/counts caching, schema management with a versioned metadata format and migrations, staged writes, introspection, notifications, diffing), absolute-URL documentation links, and supported versions (Python >= 3.8, PostgreSQL 13-18, psycopg 3). Drop the "built upon psycopg2" falsehood. Add CHANGELOG.md (Keep-a-Changelog) with a 1.0.0 section: breaking changes each with a migration note, additions, curated fixes, and infrastructure. Bump pyproject to 1.0.0; declare the license as the SPDX expression GPL-2.0-or-later with license-files (setuptools >= 77 rejects a License trove classifier alongside an SPDX expression); add Development Status, audience, Python 3.8-3.13 and topic classifiers; add Homepage/Repository/Changelog URLs. Add .github/workflows/release.yml: a Trusted-Publishing workflow that builds, twine-checks, and uploads to PyPI on a published GitHub release, with the one-time PyPI setup documented inline. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
README quickstart: config.ini is now discovered ($PSYCODICT_CONFIG, then an existing ./config.ini, then ~/.psycodict/config.ini) rather than created in the working directory. CHANGELOG: breaking-changes entry for the readargs flip, the discovery and the log/secrets relocation, plus the postgresql_dbname defaults fix. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Rebased onto main, which absorbed everything this PR used to anticipate; the reconciliation: - Version: 1.0.0 is now set in psycodict.__init__.__version__, the single source of truth roed314#121 established -- pyproject keeps main's dynamic version, SPDX license string and >=3.9 floor, and this PR's classifiers drop the License:: entry (setuptools >= 77 rejects it next to an SPDX string) and the 3.8 entry. - README: the rewrite now carries the Versioning.md pointer (roed314#123) in its Documentation list, which switches to relative links -- on the Sphinx site (roed314#122) those resolve to the copied guide pages, and they still render on GitHub; CHANGELOG and LICENSE stay absolute since neither is on the site. Supported Python is 3.9+; blob/master URLs become blob/main. - CHANGELOG: entries for the late wave -- sum/random honoring saving (roed314#118) and the 3.9 floor (roed314#121) under breaking changes; the docs site (roed314#122), Versioning.md/CONTRIBUTING/SECURITY and __version__ (roed314#121) under added; reload metafile+resort (roed314#114), update_from_file stats publication (roed314#115), copy_dumps delimiter escaping (roed314#116) under fixed; config.ini untracking (roed314#120), this release workflow and CITATION.cff (roed314#124) under infrastructure. - release.yml: the flow notes now say bump __init__.__version__ and merge to main. - Fixes the docs build on main, broken by the roed314#119 x roed314#122 crossing (roed314#119 merged after roed314#122's last CI run): the Configuration docstring's nested defaults list needed blank lines to be valid RST under autodoc, and the README's relative LICENSE link had no target on the site. Suite 857 passed / 36 skipped; ruff clean; sphinx -W clean; python -m build + twine check --strict pass with Version 1.0.0, License-Expression GPL-2.0-or-later, Requires-Python >=3.9 and no License classifier in the wheel metadata. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The uploaded version is whatever __version__ says at the tagged commit -- the tag name controls nothing -- and PyPI never accepts a version twice, so a rehearsal tag against final-version source would have burned 1.0.0 on the rehearsal. The build job now refuses any tag that is not v<__version__>. With that guard in place, ship the first release as a candidate: __version__ starts at 1.0.0rc1, so the v1.0.0rc1 rehearsal exercises the entire trusted-publishing path (including the pending publisher creating the project) on a version pip ignores by default; bumping to 1.0.0 and tagging v1.0.0 is then a one-line follow-up. The release-flow notes describe the sequence. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Four review findings: - The Documentation list's relative guide links render as relative hrefs on PyPI, resolving against pypi.org and 404ing. They now point at the live Read the Docs pages (verified 200), with a pointer to the Markdown originals at the repository root and the generated API reference; the pyproject urls gain a Documentation entry. - The features tour advertised `revert`, which does not exist; the rollback method is `reload_revert`. - The quickstart's example config connected as the postgres superuser with a blank password while the setup section below creates myuser with a password as the owner of mydb; someone following both sections in order would fail to authenticate. The quickstart now uses the setup section's credentials and says so. - The classifiers stopped at Python 3.13 while CI tests through 3.14. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The capstone of the 1.0 wave, rebased onto
mainafter the rest of the wave merged (#114–#124 including the config redesign, the Sphinx site, the 3.9/SPDX packaging modernization and Versioning.md).What's here
$PSYCODICT_CONFIG→./config.ini→~/.psycodict/config.ini), supported versions (Python ≥3.9, PostgreSQL 13–18, psycopg 3), PG15+ schema-privilege note, and a Documentation list carrying all five guides — as relative links, so on the Sphinx site (Add a Sphinx documentation site: MyST guides + autodoc API reference on Read the Docs #122) they resolve to the copied guide pages while still rendering on GitHub (CHANGELOG and LICENSE stay absolute; neither is on the site). Kills the false "Built upon psycopg2" line.## 1.0.0with Breaking/Added/Fixed/Infrastructure sections citing PR numbers, now covering the whole wave through Add CITATION.cff #124: the breaking list runs from the search/extras split (Remove the search/extras table split #59) and psycopg 3 (Port from psycopg2 to psycopg3 #88) through metadata format 1 (Stamp the metadata format version and check it on connect #90/Add partial-index support (metadata format 1) and the metadata-format compatibility protocol #110), the library-appropriateConfiguration(Library-appropriate configuration: no argv parsing, config discovery #119),sum/randomhonoringsaving(Honor the saving flag in sum() and random()'s count side effect #118), and the Python ≥3.9 floor (Require Python 3.9+, SPDX license metadata, psycodict.__version__ #121), each with a one-line migration note.psycodict.__version__ = "1.0.0rc1"in__init__.py, the single source of truth Require Python 3.9+, SPDX license metadata, psycodict.__version__ #121 established (pyproject stays dynamic). Starting at a release candidate lets thev1.0.0rc1rehearsal exercise the whole trusted-publishing path on a version pip ignores by default; bumping to1.0.0afterward is a one-line follow-up. The wheel builds aspsycodict-1.0.0rc1withLicense-Expression: GPL-2.0-or-later,Requires-Python: >=3.9, and no License classifier (setuptools ≥77 rejects the classifier next to an SPDX string);twine check --strictpasses.release.ymlrefuses any release tag that is notv<__version__>: the uploaded version is whatever the source says at the tagged commit, and PyPI never accepts a version twice, so without the guard a rehearsal tag against final-version source would have burned1.0.0..github/workflows/release.yml— trusted-publishing release workflow: publishing a GitHub release builds sdist+wheel, runs the sametwine check --strictgate as CI, and uploads to PyPI via OIDC through apypienvironment — no stored token. The header documents the one-time PyPI pending-publisher setup.main— the Library-appropriate configuration: no argv parsing, config discovery #119 × Add a Sphinx documentation site: MyST guides + autodoc API reference on Read the Docs #122 crossing (Library-appropriate configuration: no argv parsing, config discovery #119 merged after Add a Sphinx documentation site: MyST guides + autodoc API reference on Read the Docs #122's last CI run) leftmain's docs job red: theConfigurationdocstring's nesteddefaultslist needed blank lines to be valid RST under autodoc, and the README's relativeLICENSElink had no on-site target. Both fixed here.Verification
python -m sphinx -W --keep-goingclean, with the rewritten README's five guide links resolving on-site.python -m build+twine check --strict: PASSED for both sdist and wheel; wheel METADATA carries Version 1.0.0 / SPDX license / ≥3.9.~/.psycodict/config.inicreated, table/insert/search as shown, no cwd pollution).After this merges: register the PyPI pending publisher (and optionally pre-create the
pypiGitHub environment to attach protection rules — it is auto-created on first run otherwise), publish a GitHub Release taggedv1.0.0rc1marked as a pre-release, verify the upload, then bump__version__to1.0.0and publishv1.0.0.🤖 Generated with Claude Code