Move metadata from elfeed-pkg.el to elfeed.pkg

[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.

[skeeto]

It seems I bet on the wrong horse 11 years ago (eb038b0). Unfortunately removing elfeed-pkg.el and elfeed-web-pkg.el isn't so straightforward. This repository has a package building script (make package) that depends on these files. This feature is important to me, and I supply signed package builds in releases. M-x package-install-file can install these without internet access, and I use it for some isolated testing. (I also uploaded these packages to Marmalade for the brief time it existed, though that's no longer relevant.)

This situation is also true for the other two PRs: skeeto/skewer-mode#94, skeeto/elisp-finalize#3. I have a simple solution for the latter.

Possible paths forward, all include adding the metadata to elfeed.el:

• Update the build script to parse out and generate elfeed-pkg.el. This could be done crudely since it only parses Elfeed sources and need not be generally robust.

• Rename to elfeed-pkg.el.in so it's out of the way. Use this new name in the package script. Accept that there will be two sources of truth.

• Leave elfeed-pkg.el as is, knowing that MELPA will soon ignore it (right?). Accept that there will be two sources of truth.

Whatever, the solution, this might be a good moment to retire elfeed-web rather than fix it. It was a failed experiment. I don't use it myself, and have no plans to maintain that subpackage.

[tarsius]

Would it be an option to modify elfeed[-web].el as I have done here but without deleting elfeed[-web]-pkg.el? That would of course mean that going forward you would have to update the information in two places [for each package], and it would still be a good idea to create a new release.

[tarsius]

this might be a good moment to retire elfeed-web

I've removed it from Melpa.