Release 1.0, clarify SemVer, add use-package example

[tpapp]

Fixes #212. From now on we take semantic versioning seriously.

[tpapp]

@giordano @non-Jedi @FelipeLema @ajhalme please comment and/or review (the PR is trivial, and unless someone vehemently disagrees I would just tag versions and follow SemVer from now on, but since you contribute I would like to hear from you too)

[FelipeLema]

🚀

[suhail-singh]

@tpapp thank you for making the switch to SemVer.

Btw, for your awareness, if you want to do it "right", please don't make a merge
commit when merging this into master. Instead merge it directly on master
and tag the same commit (which is bumping the version in the package header)
with the git tag.

[tpapp]

@suhail-singh: sorry I don't understand. Should I merge master into this branch? Is this process written down somewhere?

What difference does it make? I was under the impression that MELPA scans daily and picks up what we have.

[suhail-singh]

This package IIUC is available both on MELPA (and thus, as well, MELPA Stable)
and NonGNU ELPA. These archives differ in their versioning.

• MELPA follows a "rolling release" model. It generates its own time-based
  versions.
• MELPA Stable uses the git tag via the :version-regexp property of the
  recipe (https://github.com/melpa/melpa?tab=readme-ov-file#recipe-format).
• NonGNU ELPA uses the package header to determine the version. Specifically,
  it focuses on the commits that introduce changes to the package header in the
  elisp files and picks the latest such commit.

If you merge this onto master with a merge commit, HEAD on master would
no longer correspond to the commit that introduced the change in the package
header (the lone commit in this PR). That by itself isn't problematic. However
if you were then to tag HEAD with a git tag of 1.0.0 there will be a
discrepancy in the commits that MELPA Stable uses for the 1.0.0 release vs the
commit that NonGNU ELPA uses for the 1.0.0 release. That's arguably
problematic.

[suhail-singh]

For what it's worth, and in case you find this useful / relevant, below is a
description of the process I follow for a package of mine (I follow SemVer as
well). Doing so maintains two invariants:

• The versions via git tags (i.e., on MELPA Stable) reference the same commits
  as would be referenced via Emacs' ELPA system.
• For those who use a local checkout of the repository, they get versions that
  are consistent (and monotonically non-decreasing) with the versions that are
  released.

This process is essentially what I had proposed in #212. Specifically, taking
the example of ox-tufte (https://github.com/ox-tufte/ox-tufte) you'll
observe that:

• The commit I used to bump the version to 4.2.1 is the same one that I tagged
  as 4.2.1 (and the one I used to make the release on github). Specifically,
  ox-tufte/ox-tufte@03e6c9e.
• Additionally, in the immediately next commit I bumped the version in the
  package header to 4.2.1.50-git
  (ox-tufte/ox-tufte@6dfab50).
  The -git suffix marks it as a pre-release and is what tells ELPA
  (cf. MELPA) that this is a development version. I believe ELPA considers
  other pre-release suffixes as well, but I am not well-versed on all the ones
  it considers. The .50 ensures that this version is treated as being greater
  than 4.2.1. This is because 4.2.1.50-git is treated as being less than
  4.2.1.50 (i.e., (version< "4.2.1.50-git" "4.2.1.50") evaluates to t).
  In the case of ox-tufte, this commit only exists on the dev branch, but
  not on main, but that's orthogonal to what we're discussing. I.e., if
  ox-tufte didn't have a separate dev branch, I would have pushed this
  commit onto main instead.

Recently I started using the sisyphus package to make the process somewhat
less manual. I am sharing below my use-package configuration for sisyphus
in case you find it helpful. Please ignore, if not. However, if you do decide
to use sisyphus, you may need to rename Version: in the package header to
Package-Version: instead. I did so in the commit
ox-tufte/ox-tufte@1f84de4.

(use-package sisyphus :ensure t :pin melpa
  :unless noninteractive
  :after magit :demand t
  :config
  (setq sisyphus-non-release-bump-header t
        sisyphus-non-release-suffix ".50-git"))

With the above, I can use M-x sisyphus-create-release and
M-x sisyphus-bump-post-release as conveniences.

[tpapp]

@suhail-singh: thanks for the information. I understand that technically, any given version would point to different commits, but it would still be the same code, right? So I don't see that as a problem.

Can't speak for the others, but there is a limited amount of crazy I am willing to tolerate to support every repo scheme. We can just have this package removed from MELPA stable if that becomes problematic.

Cf melpa/melpa#6656. @alphapapa, since you kindly commented on #212, I would appreciate your advice here.

[suhail-singh]

I understand that technically, any given version would point to different
commits, but it would still be the same code, right?

If the merge commit is what gets tagged via git tag and its parent is the
commit that changes the version in the package header, then yes the code
corresponding to these two commits would be the same. It is for this reason I
used quotes when saying if you want to do it "right".

Note that once you have different commits, for a user to determine whether or
not they correspond to the same code it requires additional effort. They would
have to fetch those commits locally and verify via git. I.e., things go from
"definitely the same version" to "possibly the same version pending
verification". This may or may not be something you care about.

So I don't see that as a problem.

It is for you to decide if this is worth the attention. However, since the pull
request mentioned your aspiration to take versioning seriously I felt this may
be relevant to mention.

We can just have this package removed from MELPA stable if that becomes
problematic.

I don't understand what that hopes to accomplish. To be clear, it's not
necessary to do the .50-git dance. It's also not necessary to mark only the
commit that updates the package header with the git tag. However, if you are
introducing the version in the package header in commit $foo and tagging
$bar with the same version, do note that NonGNU ELPA will point to $foo and
MELPA Stable will point to $bar. That is all.

I shared the process I follow for informational reasons only. Apologies in case
that wasn't clear. I find that it manages the versioning tradeoff without too
much effort on my part. However, I understand (and it's okay) that you may not
feel the same way.

[alphapapa]

Cf melpa/melpa#6656. @alphapapa, since you kindly commented on #212, I would appreciate your advice here.

Hi Tamas,

I think Suhail is correct: it would seem a bit unusual for the commit with a version tag to not be the same commit in which the version header was set to the same value, but as you said, in this case, and especially for this first 1.0.0 release, it shouldn't make any difference, since the code is the same.

I use a similar scheme for my packages: After releasing a new version, I increment the Y number (as in X.Y.Z), adding a -pre suffix (which is accepted by Emacs's version-number functions) to the header and changelog. Then when I release that version, I remove the suffix and tag that commit with the matching vX.Y.Z tag. Much of this comes down to personal preference.

IME the most important thing to keep in mind is that, while MELPA just builds whatever you push, effectively cloning the repo anew each time it builds a package, GNU ELPA pulls changes from the repo, and it will refuse to build if it pulls non-fast-forward changes (in which case it will send the maintainer an email, and you'll have to do a slightly awkward merge to resolve it).

So if your package is built on GNU ELPA, it's important to never rewrite history on the branch that ELPA builds from. If you make a mistake and realize it after pushing, you should just push a new commit on top that fixes the problem; and if that means incrementing the version number again (e.g. adding a .Z bugfix number), so be it. (Technically you can sometimes get away with it, but it's a gamble that ELPA hasn't pulled the mistaken commit yet.)

Another thing I can recommend is to have ELPA pull from a dedicated branch rather than master, which will allow you to maintain a stable branch with bugfixes, apart from master's being where the next X.Y version is developed (e.g. after releasing a bugfix to the stable branch, that branch can be merged into master). But this is a matter of preference.

I hope this helps. It can be a bit confusing at first, but once you grok the different systems, it's not too bad. :)

[tpapp]

Thanks everyone for the detailed information. I recognize that there is a "right" way of doing things, but I have to explore the tooling about that, so for now I will just merge this commit as is, and we will stick to SemVer. I think it is already an improvement.

[cstjean]

Out of curiosity, what is SemVer for such a package? That the key bindings won't change in a minor version?

[tpapp]

Good question, my intention is mostly to play it by ear and open a discussion if there is any doubt. But generally, bug fixes increment the patch version, features increment the minor version, and if the functions we expose change or are removed, we bump the major version. I would not include keybindings and defaults, maybe we should clarify that.

[suhail-singh]

... if the functions we expose change or are removed, we bump the major
version. I would not include keybindings and defaults, maybe we should clarify
that.

This came as a surprise to me. So if that is indeed the case then I agree that
a clarification would help.

However, please also consider a possibly-less-surprising-to-some approach where
altering or removal of defaults and keybindings are considered breaking
changes and result in major version being bumped. However, addition of new
defaults or keybindings only increment the minor version.

Thank you for maintaining julia-mode, btw.

[meedstrom]

Perhaps EffVer is more intuitive?

@suhail-singh out of curiosity, do you routinely look at Emacs package version strings and change upgrade decisions accordingly, or do you know anyone who does? I'd love to see a YouTube video demonstrating how to do that.

I currently have the impression that, for a packager, tending to the exact semantics is a bit like alphabetizing bookshelves. Basically, just do it if it's fun. Once we have a featureful package manager, with lockfiles, dependency resolution, and ability to downgrade, that situation might change.

[suhail-singh]

@suhail-singh out of curiosity, do you routinely look at Emacs package version
strings and change upgrade decisions accordingly, or do you know anyone who
does?

I do. For instance there's a package that I routinely use and I haven't
upgraded it in a while because the version string signalled to me that it was a
breaking change (which I then later confirmed by looking at the README). I
eventually will, but when I do I'll ensure that I have sufficient time to devote
to the task.

Something similar happened with magit and related packages recently as well. I
updated other packages (that seemed to have only bugfixes), but withheld upgrade
of magit etc.

I also have package-install-upgrade-built-in set to t. As such I never use
package-upgrade-all and in its stead use package-menu-filter-upgradable
(bound to / u) to review list of packages and then upgrade as desired.

[meedstrom]

Thank you for describing your process. It's nice that the version info benefits somebody. Sorry for hijacking the thread.