chore: migrate to pyproject.toml and add PEP 751 lockfile

docs/contributing.rst

@@ -27,6 +27,28 @@ Clone you github fork repo locally and install errbot in development mode from t
 From there, anytime you execute `errbot` it will run from the checked out version of Errbot with all your local
 changes taken into account.
 
+Updating the dependency lockfile
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Errbot ships a pinned dependency lockfile (``pylock.toml``) in `PEP 751`_ format,
+generated by uv_ from the top-level dependencies declared in ``pyproject.toml``.
+The lockfile is the source of truth for reproducible installs in CI and for
+downstream consumers that want exact versions.
+
+Regenerate the lockfile any time you change a dependency in ``pyproject.toml`` (or
+to refresh the pinned versions). From the root of the repository::
+
+    # Install uv if you don't have it (https://docs.astral.sh/uv/)
+    pip install uv
+
+    # Recompile the lockfile from pyproject.toml, pinned to the project's
+    # minimum supported Python version so the resolution covers 3.9+.
+    uv pip compile pyproject.toml -o pylock.toml \
+        --format pylock.toml --python-version 3.9
+
+Commit the resulting ``pylock.toml`` alongside your ``pyproject.toml`` change in
+the same pull request so the two stay in sync.
+
 Preparing your pull request
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -42,6 +64,56 @@ these guidelines as you open a pull request.
 * If you can, please add tests for your code. We know large parts of our codebase
   are missing tests, so we won't reject your code if it lacks tests, though.
 
+Releasing Errbot
+----------------
+
+This section is for maintainers cutting a release. The flow assumes a CHANGES.rst
+maintained by hand under a ``v9.9.9 (unreleased)`` heading on master.
+
+Cutting a release
+~~~~~~~~~~~~~~~~~
+
+1. **Open a release PR** that does two edits:
+
+   - Bump ``errbot/version.py``::
+
+         VERSION = "X.Y.Z"
+
+   - Rename the unreleased heading in ``CHANGES.rst`` from ``v9.9.9 (unreleased)``
+     to ``vX.Y.Z (YYYY-MM-DD)`` and double-check the entries beneath it.
+
+2. **Let CI gate the change.** The test ``tests/release_metadata_test.py`` skips on the
+   ``9.9.9`` sentinel but, once ``version.py`` is bumped, asserts that ``CHANGES.rst``
+   contains a section heading for the new version. A release PR that forgets the heading
+   rename will fail this test before it can merge.
+
+3. **Merge the release PR**, then run the release tooling from a clean checkout::
+
+       ./tools/releases.sh
+
+   The script reruns the same pre-release gate, builds the sdist/wheel with
+   ``python -m build``, and calls ``twine`` to publish to PyPI.
+
+4. **Tag the commit** and push the tag::
+
+       git tag vX.Y.Z
+       git push origin vX.Y.Z
+
+5. **Return master to dev mode** in a follow-up PR:
+
+   - Reset ``errbot/version.py`` to ``VERSION = "9.9.9"``.
+   - Add a fresh ``v9.9.9 (unreleased)`` heading at the top of ``CHANGES.rst``.
+
+After this, the gate test goes back to skipping on master and the next release
+cycle starts.
+
+Refreshing the lockfile for a release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If dependency pins have changed since the previous release, regenerate
+``pylock.toml`` (see `Updating the dependency lockfile`_) and include the result
+in the release PR.
+
 Contributing documentation & making changes to the website
 ----------------------------------------------------------
 
@@ -94,3 +166,5 @@ to ask your question on Stack Overflow, `tagged errbot
 .. _repos.py: https://github.com/errbotio/errbot/blob/master/errbot/repos.py
 .. _`issue tracker`: https://github.com/errbotio/errbot/issues/
 .. _Gitter: https://gitter.im/errbotio/errbot
+.. _uv: https://docs.astral.sh/uv/
+.. _`PEP 751`: https://peps.python.org/pep-0751/