Move metadata from purescript-mode-pkg.el to purescript-mode.el

[tarsius]

This pull-request moves metadata about this package from <name>-pkg.el to <name>.el and deletes the now redundant <name>-pkg.el.

The <name>-pkg.el file is not supposed to be tracked in the Git repository. It is supposed to be generated by the package archive (e.g., MELPA) and distributed as part of the <name>-<version>.tar file.

If you are already convinced, you can skip reading most of the rest, but please read the last page.

---

Unfortunately the Multi-file Packages node in the info manual is not explicit about this. So you may have read this:

One of the files in the content directory must be named NAME-pkg.el. It must contain a single Lisp form, consisting of a call to the function define-package,

... and concluded that this means that your Git repository must contain such a <name>-pkg.el file. If so, please carefully read at least the preceding paragraph again (emphasize mine):

Prior to installation, a multi-file package is stored in a package archive as a tar file. The tar file must be named NAME-VERSION.tar, where NAME is the package name and VERSION is the version number. Its contents, once extracted, must all appear in a directory named NAME-VERSION, the “content directory” (see Packaging Basics). [...]

This node talks about how a package archive (such as GNU ELPA or MELPA) should distribute "multi-file" packages as tarballs, and goes into the details of what that tarball must contain. It also mentions how that tarball is unpacked when a user installs the package.

This node does not describe what files must exist in repositories used to develop individual packages. It does not say, that such repositories must contain a <name>-pkg.el file. (But granted, it also does not say, that they must not contain such a file.)

Content directory refers to a directory that was created by unpacking a tarfile. It does not refer to a Git repository.

---

The documentation lacks guidance on whether the repositories, used to maintain individual packages, should, or should not, track <name>-pkg.el. So we have to turn elsewhere to answer that question.

How do, or don't, the tools used to maintain the well known package archives use <name>-pkg.el as a source of information? (They obviously all generate such a file, because that is a requirement, as we have seen above.)

• elpa-admin.el, the tool used to maintain the "official" package archives GNU ELPA and NonGNU ELPA, completely ignore any checked in <name>-pkg.el. It has always done that.

• package-build.el, the tool used to maintain the much older MELPA, gets metadata from <name>.el, but iff some information is missing from that file and <name>-pkg.el exists and contains that piece of information, then that is used.

  Melpa has existed for a long time and when it was young, many conventions had not been established yet, and so package-build.el had to deal with a complex reality of many different, and often conflicting or otherwise problematic practices.

  So the reason that package-build.el falls back to using information from <name>-pkg.el is not that its maintainer (that would be me) thinks that doing so is a good idea, but that it was once necessary and unfortunately still is.

  But now that only 1% of packages use <name>-pkg.el without providing the same information in <name>.el also (or preferable only), I am opening this pull-request, and four dozen like it, so that package-build.el can soon finally stop getting information from that file.

---

So why is it problematic to use <name>-pkg.el in the first place?

When the same information can be specified in <name>.el and <name>-pkg.el, then there are two sources of truth. This is not a problem as long as everybody always makes sure the information is updated in both places. Unfortunately, but not at all surprisingly, that very often is not the case.

Many, if not most, package maintainers who initially put the information in both places, over time forget about one of them and stop updating it. To complicate that further, while most of them seem to stop updating <name>-pkg.el, some instead forget to update <name>.el. For a tool like package-build.el, that makes it impossible to always pick the correct source of truth, as intended by the package maintainer.

I believe the only solution to this problem is to agree on a single source of truth. As a community we have all but done so already. Among the 5837 packages on MELPA, 99% provide the expected information in <name>.el, while only %2 provide it in <name>-pkg.el.

This pull-request, and four dozen others like it, deal with the %1 that only provide this information in <name>-pkg.el. Once these have been merged, MELPA/package-build.el, can start ignoring <name>-pkg.el, just like GNU ELPA and NonGNU ELPA have always done.

Once that has happened, the focus can turn to informing the package maintainers, who provide inconsistent information in the two places, that they are doing so, and might want to remove <name>-pkg.el, to prevent that going forward.

---

Merging this pull-request addresses the problem for "regular" MELPA, the channel that distributes package snapshots.

But doing this alone, does not address the problem for MELPA Stable. In the commit from which the release version is build, <name>-pkg.el still exists and the information is still missing from <name>.el.

So please also create a new release!

If you also tag your releases using Git, then please make sure you bump the version in both places. I.e., bump the Package-Version library header, create a new commit titled something like "Release version N", and do not forget to also tag that exact commit with the matching N or vN git tag.

Thanks for you attention! Jonas

Ps: Please double check this pull-request before merging. As I have mentioned, I am opening four dozen such pull-requests, and it is quite possible that I made a copy-paste error in one or two.

[tarsius]

I recommend you also drop

;; Package-Version: @VERSION@

completely, or hard-code the version. Especially if you drop it completely, then instead use Git tags to tag releases. Melpa understands those.

[tarsius]

🎆 Happy new year and a friendly ping! 😸

[Hi-Angel]

Is @VERSION@ a correct value? When package is installed from Melpa, I see this is set to 20240930.737, which I presume is automatically substituted. The documentation doesn't seem to mention such value.

[Hi-Angel]

I recommend you also drop

;; Package-Version: @VERSION@

Oh, sorry, I missed the comment because I read it before looking at the code and it sounded like it's unrelated to the changes. And by the time I read through everything else I forgot about it 😅

Yeah, I'm not a maintainer (well, not unless @purcell gives me a co-maintaining permissions, because the project seems to be barely maintained), but I'd say "less code is better", so if it's autogenerated or unneeded, let's drop it.

[tarsius]

In the Makefile I can see that the version can be found by looking at Git tags. However, no tags are present in the public repository.

I recommend that you merge this but without adding the Package-Version header, and that you proceed to creating a new release (using a tag). (And then push all tags! 😬)

The Package-Version is required if you want to add the package to [Non]GNU Elpa, but Melpa prefers the Git tag. If you do use both the header and tags, then you must make sure these two sources of versioning truth agree on what commit corresponds to a certain release. I.e., bump the header, create a commit "Release version N", and then tag that very commit with vN or N.

[tarsius]

Thanks, @purcell.

Do you intend to do something about the tags and the invalid Package-Version header?

[Hi-Angel]

I might have to read a bit about this Package-Version, but it sounds like solution is to just remove it.

Making a stable release of purescript-mode I don't think would be useful, given how slow development happens here. I have plans on doing some improvements (mostly on the indentation side which just sucks), but I'd rather write tests to make sure I don't break things than to make a release 😊

[purcell]

What I think is needed here is:

• Change version header to be an actual version, not a @placeholder@. Probably 0.1 is a good default.
• Tag with 0.1
• Remove stuff in Makefile for making a tarball package and substituting the version placehold. It is not, in fact, used for anything at all.

[purcell]

I think it's fine to push a de-facto 0.1 release and then consider tests and improvements for a subsequent release that is a little more considered.

[Hi-Angel]

I might be missing something but such release seem to have no value. It's a completely arbitrary version bump which would be more confusing if anything, because having version implies a project does releases, which this project doesn't. On top of that, that tagged release would likely not be used by anyone at all. The color-identifiers-mode I'm co-maintaining seems to have ×10 times more users than purescript-mode judging by stars, it has lone release long-long ago, and to this day nobody asked for another one. I bet nobody cares.

I'm not opposed to creating a tagged release, but due to me seeing no point I'd prefer to leave this to people more motivated 😊