From 8d503e30be400ad431d3d140707803e87e75fad7 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Thu, 22 May 2025 01:38:10 -0400 Subject: [PATCH] docs: update contributing/release guide a little (#5681) Signed-off-by: Henry Schreiner --- .github/CONTRIBUTING.md | 15 +++++++++++++-- docs/release.rst | 39 +++++++++++++++------------------------ 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 292433471..8ce286f5c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -117,10 +117,21 @@ build only one of the valid targets (listed below). ```bash cmake --preset venv -DPYBIND11_CREATE_WITH_UV=3.13t cmake --build --preset venv -cmake --build --preset testsvenv -t cpptest +cmake --build --preset venv -t cpptest ``` -The `default` preset will use an existing venv or Python install. +The `default` preset will use an existing venv or Python install. If you'd like +to run pytest yourself, say to easily control the options: + +```bash +cd build +source .venv/bin/activate +cd tests +python -m pytest +``` + +The `.so` file is not installed into the venv, so you need to run from this +directory, the local directory is included with `python -m`. ## Configuration options diff --git a/docs/release.rst b/docs/release.rst index d4f3b2960..0d3777102 100644 --- a/docs/release.rst +++ b/docs/release.rst @@ -1,9 +1,8 @@ On version numbers ^^^^^^^^^^^^^^^^^^ -The two version numbers (C++ and Python) must match when combined (checked when -you build the PyPI package), and must be a valid `PEP 440 -`_ version when combined. +The version number must be a valid `PEP 440 +`_ version number. For example: @@ -11,11 +10,10 @@ For example: #define PYBIND11_VERSION_MAJOR X #define PYBIND11_VERSION_MINOR Y - #define PYBIND11_VERSION_PATCH Z.dev1 + #define PYBIND11_VERSION_PATCH Za0 -For beta, ``PYBIND11_VERSION_PATCH`` should be ``Z.b1``. RC's can be ``Z.rc1``. -Always include the dot (even though PEP 440 allows it to be dropped). For a -final release, this must be a simple integer. There is also +For beta, ``PYBIND11_VERSION_PATCH`` should be ``Zb1``. RC's can be ``Zrc1``. +For a final release, this must be a simple integer. There is also ``PYBIND11_VERSION_HEX`` just below that needs to be updated. @@ -23,7 +21,7 @@ To release a new version of pybind11: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you don't have nox, you should either use ``pipx run nox`` instead, or use -``pipx install nox`` or ``brew install nox`` (Unix). +``uv tool install nox``, ``pipx install nox``, or ``brew install nox`` (Unix). - Update the version number @@ -32,11 +30,9 @@ If you don't have nox, you should either use ``pipx run nox`` instead, or use - Update ``PYBIND11_VERSION_HEX`` just below as well. - - Update ``pybind11/_version.py`` (match above). - - Run ``nox -s tests_packaging`` to ensure this was done correctly. -- Ensure that all the information in ``setup.cfg`` is up-to-date, like +- Ensure that all the information in ``pyproject.toml`` is up-to-date, like supported Python versions. - Add release date in ``docs/changelog.md`` and integrate the output of @@ -63,7 +59,7 @@ If you don't have nox, you should either use ``pipx run nox`` instead, or use - ``git tag -a vX.Y.Z -m 'vX.Y.Z release'`` - - ``grep ^__version__ pybind11/_version.py`` + - ``git grep PYBIND11_VERSION include/pybind11/detail/common.h`` - Last-minute consistency check: same as tag? @@ -90,9 +86,9 @@ If you don't have nox, you should either use ``pipx run nox`` instead, or use click "Draft a new release" on the far right, fill in the tag name (if you didn't tag above, it will be made here), fill in a release name like "Version X.Y.Z", and copy-and-paste the markdown-formatted (!) changelog - into the description. You can remove line breaks and strip links to PRs and - issues, e.g. to a bare ``#1234`` without the hyperlink markup. Check - "pre-release" if this is a beta/RC. + into the description. You can remove line breaks and optionally strip links + to PRs and issues, e.g. to a bare ``#1234`` without the hyperlink markup. + Check "pre-release" if this is an alpha/beta/RC. - CLI method: with ``gh`` installed, run ``gh release create vX.Y.Z -t "Version X.Y.Z"`` If this is a pre-release, add ``-p``. @@ -102,7 +98,7 @@ If you don't have nox, you should either use ``pipx run nox`` instead, or use - Make sure you are on master, not somewhere else: ``git checkout master`` - Update version macros in ``include/pybind11/detail/common.h`` (set PATCH to - ``0.dev1`` and increment MINOR). + ``0a0`` and increment MINOR). - Update ``pybind11/_version.py`` to match. @@ -113,16 +109,10 @@ If you don't have nox, you should either use ``pipx run nox`` instead, or use - ``git add``, ``git commit``, ``git push`` -If a version branch is updated, remember to set PATCH to ``1.dev1``. - -If you'd like to bump homebrew, run: - -.. code-block:: console - - brew bump-formula-pr --url https://github.com/pybind/pybind11/archive/vX.Y.Z.tar.gz +If a version branch is updated, remember to set PATCH to ``1a0``. Conda-forge should automatically make a PR in a few hours, and automatically -merge it if there are no issues. +merge it if there are no issues. Homebrew should be automatic, too. Manual packaging @@ -137,6 +127,7 @@ this is the procedure: .. code-block:: bash nox -s build + nox -s build_global twine upload dist/* This makes SDists and wheels, and the final line uploads them.