|
| 1 | +# Releasing webdriver-manager |
| 2 | + |
| 3 | +This document is the maintainer runbook for publishing `webdriver-manager` releases. |
| 4 | + |
| 5 | +## Release model |
| 6 | + |
| 7 | +- Use `patch` for bugfixes, metadata/docs cleanup, and non-breaking maintenance changes. |
| 8 | +- Use `minor` for new backward-compatible features. |
| 9 | +- Use `major` for breaking changes. |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +- Maintainer access to: |
| 14 | + - repository push/tag permissions; |
| 15 | + - GitHub Releases; |
| 16 | + - PyPI token (`__token__` user) when publishing manually. |
| 17 | +- Local environment: |
| 18 | + - Python 3.12+ is recommended for release tooling; |
| 19 | + - `.venv` with `build`, `twine`, and `bump2version`. |
| 20 | + |
| 21 | +Install tooling: |
| 22 | + |
| 23 | +```bash |
| 24 | +./.venv/bin/pip install -U build twine bump2version |
| 25 | +``` |
| 26 | + |
| 27 | +## Version sources |
| 28 | + |
| 29 | +Release version must stay aligned in: |
| 30 | + |
| 31 | +- `pyproject.toml` (`[project].version`); |
| 32 | +- `webdriver_manager/__init__.py` (`__version__`); |
| 33 | +- `setup.cfg` (`[bumpversion].current_version`). |
| 34 | + |
| 35 | +`setup.py` is a compatibility shim. Packaging metadata is sourced from `pyproject.toml`. |
| 36 | + |
| 37 | +## Standard release flow (preferred) |
| 38 | + |
| 39 | +1. Ensure branch is up to date and tests are green. |
| 40 | +2. Update `CHANGELOG.md` for the target version. |
| 41 | +3. Bump version: |
| 42 | + |
| 43 | +```bash |
| 44 | +./.venv/bin/bump2version patch |
| 45 | +# or: minor / major |
| 46 | +``` |
| 47 | + |
| 48 | +4. Build and validate artifacts: |
| 49 | + |
| 50 | +```bash |
| 51 | +find . -maxdepth 1 -name '*.egg-info' -exec rm -rf {} + |
| 52 | +rm -rf dist build |
| 53 | +./.venv/bin/python -m build |
| 54 | +./.venv/bin/twine check dist/* |
| 55 | +``` |
| 56 | + |
| 57 | +5. Push commit and tag: |
| 58 | + |
| 59 | +```bash |
| 60 | +git push |
| 61 | +git push --tags |
| 62 | +``` |
| 63 | + |
| 64 | +6. Create and publish a GitHub Release for the new tag. |
| 65 | +7. Verify deploy workflow completed successfully: |
| 66 | + - `.github/workflows/deploy.yml` runs on `release.published`; |
| 67 | + - artifacts are uploaded to PyPI. |
| 68 | + |
| 69 | +## Fallback when GitHub Release UI/API is unavailable |
| 70 | + |
| 71 | +Use this only when GitHub release creation is blocked. |
| 72 | + |
| 73 | +1. Run steps 1-5 from the standard flow. |
| 74 | +2. Publish directly to PyPI from local artifacts: |
| 75 | + |
| 76 | +```bash |
| 77 | +./.venv/bin/twine upload dist/* |
| 78 | +``` |
| 79 | + |
| 80 | +3. When GitHub recovers, create the GitHub Release for the same tag and include notes. |
| 81 | + |
| 82 | +Important: |
| 83 | + |
| 84 | +- The deploy workflow may fail later on re-upload because the same version already exists on PyPI. |
| 85 | +- That failure is expected in this fallback path; do not republish with the same version. |
| 86 | + |
| 87 | +## Post-release checks |
| 88 | + |
| 89 | +- PyPI page shows correct: |
| 90 | + - version; |
| 91 | + - summary; |
| 92 | + - `Requires-Python`; |
| 93 | + - supported Python classifiers. |
| 94 | +- README badges resolve to `webdriver-manager` package. |
| 95 | +- Install smoke test: |
| 96 | + |
| 97 | +```bash |
| 98 | +python -m venv /tmp/wdm-smoke |
| 99 | +source /tmp/wdm-smoke/bin/activate |
| 100 | +pip install webdriver-manager==X.Y.Z |
| 101 | +python -c "import webdriver_manager; print(webdriver_manager.__version__)" |
| 102 | +``` |
| 103 | + |
| 104 | +## Notes |
| 105 | + |
| 106 | +- Keep `4.x` maintenance releases small and focused. |
| 107 | +- Do not yank a release unless it is functionally unsafe (install/runtime/security/API breakage). |
0 commit comments