bug#53221: Keeping Version header and tag in sync

bug#53221: Keeping Version header and tag in sync

[Jonas Bernoulli]

Hello,

I have brought this up elsewhere and Stefan Kangas asked me to repeat it
here so we don't forget about it.

1: https://github.com/magit/orgit/pull/45

[Non]GNU Elpa uses the [Package-]Version header to determine a package's
version, while Melpa Stable uses the latest Git/Hg version tag.  (Let's
not talk about what Melpa "bleeding edge" does.)

It is desirable that these package archives as well as other tools that
use either one of these techniques agree which commit a version string
refers too.

To accomplish this we have to bump the version in both locations at the
same time.  At the exact same time!  One should not bump the Version
header in one commit, add a few more commits, and then tag the latest
commit with the same version as was first used in the library header a
few commits earlier.

We are stuck with two sources for the same information and we should try
hard to keep these two sources in agreement.  This also means that when
we invite new packages into [Non]GNU Elpa and instruct their maintainers
to add the Version header, that we then also make them aware of this
complication.

IMO this is how it should be done given the current schism:

1. Update the `Version` header keyword.
2. Possibly make other release-related changes like updating the
   `NEWS` file or updating the version in manuals and such.
3. Create a commit with a message like "Release version VERSION",
   where VERSION is exactly the same version as used in the header.
4. Tag that commit using the same version as used in the header and
   commit message (optionally prefixed with `v` because that is the
   Git convention).  Ideally the tag is signed and annotated.  If it
   is annotated, then it should use a message like "Release version
   VERSION" or "PACKAGE-NAME VERSION".
5. When pushing the release commit, then don't forget to push the
   release tag as well.

Obviously it would be nice to say the above with less words. ;)

     Jonas