Add command to check for vX.Y.Z tag vs pybind11/_version.py consistency.

[rwgk]

Description

Slightly expand instructions based on lesson just learned (see #4756).

Piggy-backing hints for converting changelog to release message.

Suggested changelog entry:

[rwgk]

Hi @henryiii did you get a chance to look at this tiny update?

I just double-checked the git diff command, with a fresh eye, practicing a mock release. It does work as intended:

• If the branch tag corresponding to what's in pybind11/_version.py does not exist:

$ git diff "$(grep ^__version__ pybind11/_version.py | cut -d'"' -f2 | sed 's/^/v/')"
fatal: ambiguous argument 'v2.11.9': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

• if the branch tag exists but the tagged commit is not identical to the currently checked-out git working copy it shows the diff.

I think that's exactly what we need as a last line of defense, right before the git push --tags in the instructions.

[henryiii]

Where is the current tag number shown? __version__ and pybind11/_version.py are already forced to be in sync by nox -s tests_packaging above, if that's all this is doing.

[rwgk]

The nox command only ensures that common.h and pybind11/_version.py are fully self-consistent.

Which is something I take for granted.

The git-diff-grep command would have shown a diff because it would have pulled v2.11.0 from pybind11/_version.py, but at that step in the instructions my working copy had the v2.11.1 changes, just not the version number update.

[henryiii]

I'm failing to understand why this would catch anything that git status or a plain git diff would not show (or, in my terminal, the current git condition is shown as a colored bar). It's not using or comparing the tag itself at all.

Could it be replaced with "make sure all changes are committed"?

[rwgk]

I simply forgot to update the version number, and everybody else overlooked it, too.

git status would not have shown anything.

git diff also would not have shown anything.

git diff v2.11.0 would have shown that the code I had was not what was tagged as v2.11.0.

[henryiii]

Oooh, oooookay. That seems like an interesting way to so it. Can't you just print out the current version and make sure it's the same as the tag? grep ^__version__ pybind11/_version.py | cut -d'"' -f2 | sed 's/^/v/'" should show the current tag.

[henryiii]

And grep ^__version__ pybind11/_version.py would be enough for a human user to verify the code states the version they just tagged.

[henryiii]

Suggested change

	- ``git diff "$(grep ^__version__ pybind11/_version.py | cut -d'"' -f2 | sed 's/^/v/')"``
	- There should be no diff.
	- ``grep ^__version__ pybind11/_version.py``
	- This should print the version you just tagged.

[rwgk]

I pushed a slightly different wording before seeing this comment.
Give me a moment to try again.
Simpler is better I agree.

[henryiii]

Plus it's not great for the "working" path to produce no feedback that it worked. Your wording is fine.

[rwgk]

@henryiii I removed a few line breaks to make it look better in the web view.

https://github.com/pybind/pybind11/blob/2b54c6539951cbd819b00b2140182bcf9a100ed7/docs/release.rst

Do you know if we can have the line breaks in the .rst file without making it look weird in the web view?

It's still not perfect, but good enough?

[rwgk]

It's still not perfect, but good enough?

With a lot of trial and error I finally figured out then main problem:

This is NOT GOOD:

- Bullet nesting level 1.
    - Bullet nesting level 2.

This is BETTER:

- Bullet nesting level 1.
  - Bullet nesting level 2.

With that and some minor miscellaneous polishing the rendered page on the web looks nice now. I'll go ahead and merge.