Skip to content
This repository was archived by the owner on Oct 27, 2026. It is now read-only.

Prepare 5.2.0, the final release - #107

Merged
exhuma merged 9 commits into
masterfrom
chore/final-eol-release
Oct 27, 2026
Merged

exhuma merged 9 commits into
masterfrom
chore/final-eol-release

Conversation

@exhuma

@exhuma exhuma commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Prepares 5.2.0, the final release of config_resolver. It says plainly that the project is unmaintained, shows how to replace it, and warns at runtime. Nothing is tagged or published: that's left for after review (see the end).

What changes

Runtime warning

  • New ConfigResolverDeprecationWarning(DeprecationWarning) in config_resolver/exc.py, exported from the package.
  • get_config() and from_string() emit it on every call with stacklevel=3, so it points at the caller's line. Importing the package does not warn.
  • tests/test_deprecation.py checks both functions, the caller filename and line (a mutation to stacklevel=2 makes those tests fail), the docs URL in the message, the subclass relation, that python -W error -c "import config_resolver" passes, and that the filter shown in the docs silences it.
  • The existing suite filters the warning in pytest.ini; no existing test was edited. The obsolete log_print option (pytest reported it as unknown) is removed.

Documentation

  • README.rst (the PyPI page) and the docs start page, which includes the README, open with a warning admonition: unmaintained, final release, a short reason, and a link to the migration page.
  • New doc/migration.rst ("Alternatives and migration"), first in the toctree:
    • how to silence the warning while migrating
    • containerised services: pydantic-settings (env_prefix, env_nested_delimiter="__", secrets_dir="/run/secrets", SecretStr, exit on ValidationError)
    • existing INI files: ConfigParser().read() over config_resolver's own path list; read() returns the files it loaded (same as meta.loaded_files)
    • CLI tools: platformdirs + tomllib (with a tomli fallback) for the system → user → explicit cascade, including the BIRD_FEEDER_CONFIG env var, returning (config, loaded_files)
    • replacing version: a schema_version: Literal[2] pydantic field, plus a plain check without pydantic
    • replacing secure=True: an os.stat check of owner and mode, with a note that container secret mounts are 0444/0644 and protected by the mount, not the mode
    • other options: dynaconf, environs, python-decouple
  • The snippets are real files under doc/migration/ and are included with literalinclude. tests/test_migration_snippets.py runs them; tests whose library is missing are skipped, so config_resolver gains no dependency.
  • Docs move from Read the Docs to GitHub Pages, set up like x690:
    • new .github/workflows/docs.yml builds with Sphinx on every push to master and deploys with actions/deploy-pages
    • the docs job in the main workflow checks the build (-n -W) on every push and PR
    • the docs toolchain lives in the default dev group, so plain uv sync / uv run sphinx-build works
    • .readthedocs.yaml is gone; README, project.urls, the changelogs and the warning message point to https://exhuma.github.io/config_resolver/
    • conf.py reads the version from config_resolver/version.txt (it was hard-coded to 5.0.0a1)
    • the theme moves from sphinx_rtd_theme to the michel-albert-sphinx design system (v0.4.0)
    • a few docstring markup and cross-reference errors are fixed so the nitpicky build passes

Packaging and release prep

  • version.txt → 5.2.0.
  • Classifiers:
    • Development Status :: 7 - Inactive
    • license LGPLv3 → MIT, matching LICENSE.txt
    • Typing :: Typed (the package ships py.typed)
    • Python 3.6–3.15 (evidence below)
  • The summary says the package is unmaintained. project.urls lists Documentation, Changelog, Issues and Repository.
  • CHANGES and doc/changelog.rst have a 5.2.0 entry: final release, the deprecation warning (including that projects running with -W error now fail on calls), the license fix, and the docs.
  • CI gets one new job, a strict docs build (sphinx-build -n -W).

Verification

Test suite (dev env, Python 3.13)
$ uv run pytest -q
88 passed, 3 skipped

The 3 skips are the pre-existing JSON skip and the two pydantic-settings snippet tests (that library isn't in the dev env).

CI on 643b841: all green
success  Test (Python 3.11)
success  Test (Python 3.12)
success  Test (Python 3.13)
success  Test (Python 3.14)
success  Test (Python 3.15)
success  Test (upcoming Python 3.16, may fail)
success  Build documentation
success  Build and inspect package   (twine check + check-wheel-contents)
Older Pythons, run locally
$ uv run --isolated --no-project --python 3.8  --with pytest --with packaging python -m pytest -o addopts="" -q
83 passed, 8 skipped
$ ... --python 3.9  ...  → 83 passed, 8 skipped
$ ... --python 3.10 ...  → 83 passed, 8 skipped
$ ... --python 3.9 ... python -W error::DeprecationWarning -c "import config_resolver; config_resolver.from_string('')"
3.9.25 raised under -W error: config_resolver is no longer maintained and will receive no further releases. See https://config-resolver.readthedocs.io/ for migration examples.
# (the message now links https://exhuma.github.io/config_resolver/migration.html instead)
$ uvx vermin --eval-annotations -t=3.6- --violations config_resolver
Minimum required versions: 3.6

uv can no longer download 3.6 or 3.7. The 3.6/3.7 classifiers rest on 5.1.0's CI matrix (3.6–3.9) plus vermin showing the new code needs only 3.6. 3.10 left the CI matrix because endoflife.date lists it as EOL.

Migration snippets in throwaway uv environments
$ uv run --isolated --no-project --python 3.13 --with pytest --with packaging \
    --with pydantic-settings --with platformdirs \
    pytest -o addopts="" -q tests/test_migration_snippets.py
12 passed
$ ... --python 3.14 ...                 → 12 passed
$ ... --python 3.10 ... --with tomli    → 12 passed   (exercises the tomli fallback)

Versions resolved: pydantic 2.14.1, pydantic-settings 2.16.1, platformdirs 4.13.6.

Docs and package build
$ uv sync --locked && uv run sphinx-build -n -W --keep-going -b html doc doc/_build/html
build succeeded.
$ grep -rL md-header doc/_build/html/*.html; grep -rL michel-albert.css doc/_build/html/*.html; grep -rl fonts.googleapis.com doc/_build/html
(no output)
$ uv build
Successfully built dist/config_resolver-5.2.0.tar.gz
Successfully built dist/config_resolver-5.2.0-py3-none-any.whl
$ uvx twine check --strict dist/*
Checking dist/config_resolver-5.2.0-py3-none-any.whl: PASSED
Checking dist/config_resolver-5.2.0.tar.gz: PASSED
$ uvx check-wheel-contents dist/*.whl
dist/config_resolver-5.2.0-py3-none-any.whl: OK

I couldn't take screenshots of the rendered pages because no browser was available. I only checked the HTML structure.

Quartermaster kits applied

Resolved via resolve_kits at the start; every kit was served at major version v1:

  • module-python-library: metadata, README, changelog, versioning/deprecation, examples-as-tests, docs build in CI
  • module-docs-sphinx: theme, required extensions, version sourcing, -W, no hard-coded version
  • module-hosting-readthedocs: applied at first, then dropped when the docs moved to GitHub Pages (no Pages kit exists; x690's setup was copied)
  • module-documentation: 80-column RST, semantic line breaks, changelog prose
  • module-changelog: entry wording and size tiers; clproc itself was not adopted (see deviations)
  • module-version-control: atomic 50/72 commits without Conventional Commits type prefixes
  • module-testing-strategy and module-code-style-python: "Ensure …" test docstrings, docstring format, no __future__ import

Deliberate deviations

  • requires-python stays >=3.6 (hard constraint), although the library kit wants every supported version tested in CI. CI's versions job will keep printing its "requires-python is below the oldest supported CPython" warning.
  • The docs toolchain lives in the default dev dependency group, not a docs optional extra. The theme is a git+https URL, and PyPI rejects direct references in published metadata. Keeping it in dev matches x690.
  • No clproc / changelog.in migration. That's tooling for future releases, so I kept the hand-written CHANGES and doc/changelog.rst. The license fix has its own changelog entry, even though the kit keeps packaging metadata out of changelogs: you asked for it, and a project's license is something users care about. Drop it if you disagree.
  • Snippets are pytest-run files, not doctests. They need third-party libraries that config_resolver must not depend on, so the tests skip when those libraries are missing. In regular CI, the pydantic-settings tests therefore skip. The other snippet tests run, because pydantic and platformdirs come in through dev tooling.
  • Not restructured: the start page layout and the autodoc API pages stay as they were, and the publish job still uses the pypi_token secret rather than Trusted Publishing. The kits ask for these, but they're infrastructure for future releases.

Left for you

  1. Before merging: enable GitHub Pages under Settings → Pages → Source: GitHub Actions (as in x690). Pages is currently off for this repo, and docs.yml deploys on the merge push. If you merge first, re-run "Docs" from the Actions tab (workflow_dispatch) once Pages is on.
  2. Review and merge.
  3. Check that https://exhuma.github.io/config_resolver/ and /migration.html are live. The warning message links to the migration page.
  4. Tag the merge commit v5.2.0 and push the tag. The existing publish job uploads to PyPI with the pypi_token secret, or publish by hand if you prefer.
  5. Check that the PyPI page shows the warning and the GitHub Pages links.
  6. Decide what to do with the old Read the Docs project. It stays frozen at 5.0.0a1. Deleting it breaks the docs links in older PyPI releases; keeping it leaves stale docs online.
  7. Optionally set the repository's website field to the Pages URL.
  8. Optionally close the remaining open issues (DB Support #5, Remove non-xdg config locations #11, Modular config parsing. #12, The "secure" flag breaks deployments in OpenShift #52, Allow skipping of configs with mismatching major version #66) as "won't fix", then archive the GitHub repository.

🤖 Generated with Claude Code

exhuma and others added 7 commits October 27, 2026 15:05
config_resolver gets one last release and then no further work. Users
need to hear about it where they will notice, so get_config() and
from_string() now emit ConfigResolverDeprecationWarning, a
DeprecationWarning subclass defined in config_resolver.exc and exported
from the package. Importing the package stays silent.

The warning uses stacklevel=3 so it is attributed to the caller's line,
not to config_resolver; tests pin that down. The existing suite filters
the warning in pytest.ini instead of handling it in each test. The
obsolete log_print option, which pytest reports as unknown, is gone.

Co-Authored-By: Claude <noreply@anthropic.com>
PyPI metadata should tell the truth about the project's state:

- Development Status is now "7 - Inactive"; there will be no further
  work after this release.
- The license classifier said LGPLv3, but LICENSE.txt and the license
  field have been MIT for years. The classifier now says MIT.
- The package ships py.typed, so it gets the "Typing :: Typed"
  classifier.
- The summary states that the project is unmaintained.
- project.urls points to the stable docs, the changelog, the issue
  tracker and the repository.

Co-Authored-By: Claude <noreply@anthropic.com>
Read the Docs "stable" still shows 5.0.0a1: there was no
.readthedocs.yaml, and conf.py hard-coded that version.

- Add .readthedocs.yaml. It installs a new "docs" dependency group with
  uv and fails on warnings.
- Read the version from config_resolver/version.txt, the file
  setuptools already uses.
- Replace sphinx_rtd_theme with the michel-albert-sphinx design system,
  and enable autosectionlabel and sphinx-autodoc-typehints.
- Point intersphinx at current Python docs and at packaging.
- Fix the docstring markup and cross-references the nitpicky build
  reported.
- Build the docs in CI with -n -W.

The docs dependencies are a uv dependency group, not an optional
extra: the theme is a git URL, and PyPI rejects direct references in
published metadata.

Co-Authored-By: Claude <noreply@anthropic.com>
The README (the PyPI page) and the docs start page now open with a
warning: the project is unmaintained, 5.2.0 is the final release, a
short reason, and a link to the new "Alternatives and migration" page,
first in the table of contents.

That page covers each common use case with a short snippet:
pydantic-settings for containerised services, plain ConfigParser for
existing INI files, platformdirs + tomllib for a CLI tool's XDG
cascade, a schema_version field instead of the version option, and an
ownership-and-mode check instead of secure=True. It also shows how to
silence the new warning while migrating.

The snippets live in doc/migration/*.py and are included verbatim.
tests/test_migration_snippets.py runs them. Tests whose third-party
library is missing are skipped, so config_resolver gains no
dependency.

Co-Authored-By: Claude <noreply@anthropic.com>
Bump the version and add the 5.2.0 entry to both changelogs: the
deprecation warning (including the effect on projects that run with
-W error), the corrected license classifier, and the docs changes.

5.2.0 is a minor release: the API is unchanged and the only new
behaviour is a warning.

Co-Authored-By: Claude <noreply@anthropic.com>
The classifiers listed only 3.6. The test suite passes on 3.11-3.15 in
CI and on 3.8-3.10 locally. 5.1.0 was tested on 3.6-3.9, and the new
code uses only 3.6-compatible syntax (checked with vermin), so 3.6 and
3.7 stay listed even though current tooling cannot run them.

Co-Authored-By: Claude <noreply@anthropic.com>
The cross-reference fixed earlier pushed the line past the limit.

Co-Authored-By: Claude <noreply@anthropic.com>
@exhuma exhuma self-assigned this Oct 27, 2026
`uv run sphinx-build` failed because Sphinx and the theme lived in a
separate "docs" dependency group, which uv does not install by default.
Move them into the default dev group, as x690 does, so a plain
`uv sync` / `uv run sphinx-build` works locally, on Read the Docs and
in CI. The docs CI job now mirrors x690's: it syncs with the latest
supported Python, then runs sphinx-build.

Co-Authored-By: Claude <noreply@anthropic.com>
@exhuma

exhuma commented Oct 27, 2026

Copy link
Copy Markdown
Owner Author

Fixed in 2fc2150: uv run sphinx-build failed because Sphinx, the theme and sphinx-autodoc-typehints were in a separate docs dependency group, which uv sync/uv run don't install by default. They're now in the default dev group, as in x690:

  • pyproject.toml: docs group removed, its packages moved to dev (uv.lock regenerated)
  • .readthedocs.yaml: plain uv sync, no groups
  • CI docs job: same shape as x690's (setup-python at the latest supported version, uv sync --locked, uv run sphinx-build -n -W --keep-going)

Checked on a fresh clone with a new venv: uv sync --locked && uv run sphinx-build -n -W --keep-going -b html doc doc/_build/html → build succeeded. CI is green on 2fc2150, including the docs job. I've updated the PR description to match.

Host the docs at https://exhuma.github.io/config_resolver/ instead of
Read the Docs, the same way x690 does: a new docs.yml workflow builds
them with Sphinx on every push to master and deploys them with
actions/deploy-pages. The CI workflow keeps checking the build on
every push and pull request.

- Remove .readthedocs.yaml.
- Point the deprecation warning straight at the migration page on
  GitHub Pages, and update the test that checks the link.
- Update project.urls, the README and both changelogs.

Co-Authored-By: Claude <noreply@anthropic.com>
@exhuma

exhuma commented Oct 27, 2026

Copy link
Copy Markdown
Owner Author

Moved the docs to GitHub Pages in 643b841, set up like x690:

  • new .github/workflows/docs.yml builds with Sphinx on every push to master and deploys with actions/deploy-pages to https://exhuma.github.io/config_resolver/
  • .readthedocs.yaml removed
  • the deprecation warning, README, project.urls and both changelogs now link the Pages site (the warning goes straight to migration.html)

CI is green, including the docs build. The deploy itself only runs on master, so it hasn't run yet.

Pages is currently off for this repo. Before merging, enable it under Settings → Pages → Source: GitHub Actions. Otherwise the first deploy fails, and you'll need to re-run the Docs workflow manually. The PR description's "Left for you" list is updated.

@exhuma
exhuma merged commit 47c4f2c into master Oct 27, 2026
20 checks passed
@exhuma
exhuma deleted the chore/final-eol-release branch October 27, 2026 15:31
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant