1On version numbers 2^^^^^^^^^^^^^^^^^^ 3 4The two version numbers (C++ and Python) must match when combined (checked when 5you build the PyPI package), and must be a valid `PEP 440 6<https://www.python.org/dev/peps/pep-0440>`_ version when combined. 7 8For example: 9 10.. code-block:: C++ 11 12 #define PYBIND11_VERSION_MAJOR X 13 #define PYBIND11_VERSION_MINOR Y 14 #define PYBIND11_VERSION_PATCH Z.dev1 15 16For beta, ``PYBIND11_VERSION_PATCH`` should be ``Z.b1``. RC's can be ``Z.rc1``. 17Always include the dot (even though PEP 440 allows it to be dropped). For a 18final release, this must be a simple integer. 19 20 21To release a new version of pybind11: 22^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 23 24- Update the version number 25 - Update ``PYBIND11_VERSION_MAJOR`` etc. in 26 ``include/pybind11/detail/common.h``. PATCH should be a simple integer. 27 - Update ``pybind11/_version.py`` (match above) 28 - Ensure that all the information in ``setup.cfg`` is up-to-date, like 29 supported Python versions. 30 - Add release date in ``docs/changelog.rst``. 31 - Check to make sure 32 `needs-changelog <https://github.com/pybind/pybind11/pulls?q=is%3Apr+is%3Aclosed+label%3A%22needs+changelog%22>`_ 33 issues are entered in the changelog (clear the label when done). 34 - ``git add`` and ``git commit``, ``git push``. **Ensure CI passes**. (If it 35 fails due to a known flake issue, either ignore or restart CI.) 36- Add a release branch if this is a new minor version, or update the existing release branch if it is a patch version 37 - New branch: ``git checkout -b vX.Y``, ``git push -u origin vX.Y`` 38 - Update branch: ``git checkout vX.Y``, ``git merge <release branch>``, ``git push`` 39- Update tags (optional; if you skip this, the GitHub release makes a 40 non-annotated tag for you) 41 - ``git tag -a vX.Y.Z -m 'vX.Y.Z release'``. 42 - ``git push --tags``. 43- Update stable 44 - ``git checkout stable`` 45 - ``git merge master`` 46 - ``git push`` 47- Make a GitHub release (this shows up in the UI, sends new release 48 notifications to users watching releases, and also uploads PyPI packages). 49 (Note: if you do not use an existing tag, this creates a new lightweight tag 50 for you, so you could skip the above step). 51 - GUI method: click "Create a new release" on the far right, fill in the tag 52 name (if you didn't tag above, it will be made here), fill in a release 53 name like "Version X.Y.Z", and optionally copy-and-paste the changelog into 54 the description (processed as markdown by Pandoc). Check "pre-release" if 55 this is a beta/RC. You can get partway there with 56 ``cat docs/changelog.rst | pandsoc -f rst -t markdown``. 57 - CLI method: with ``gh`` installed, run ``gh release create vX.Y.Z -t "Version X.Y.Z"`` 58 If this is a pre-release, add ``-p``. 59 60- Get back to work 61 - Make sure you are on master, not somewhere else: ``git checkout master`` 62 - Update version macros in ``include/pybind11/detail/common.h`` (set PATCH to 63 ``0.dev1`` and increment MINOR). 64 - Update ``_version.py`` to match 65 - Add a spot for in-development updates in ``docs/changelog.rst``. 66 - ``git add``, ``git commit``, ``git push`` 67 68If a version branch is updated, remember to set PATCH to ``1.dev1``. 69 70If you'd like to bump homebrew, run: 71 72.. code-block:: 73 74 brew bump-formula-pr --url https://github.com/pybind/pybind11/archive/vX.Y.Z.tar.gz 75 76Conda-forge should automatically make a PR in a few hours, and automatically 77merge it if there are no issues. 78 79 80Manual packaging 81^^^^^^^^^^^^^^^^ 82 83If you need to manually upload releases, you can download the releases from the job artifacts and upload them with twine. You can also make the files locally (not recommended in general, as your local directory is more likely to be "dirty" and SDists love picking up random unrelated/hidden files); this is the procedure: 84 85.. code-block:: bash 86 87 python3 -m pip install build 88 python3 -m build 89 PYBIND11_SDIST_GLOBAL=1 python3 -m build 90 twine upload dist/* 91 92This makes SDists and wheels, and the final line uploads them. 93