bug#81627: 30.2; [ELPA] Suggestions from my first ELPA package submission
Lin Jian via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <[email protected]>
| Newsgroups | gmane.emacs.bugs |
|---|---|
| Message-ID | <[email protected]> |
Hi ELPA maintainers, I have a few suggestions or feature/doc requests from my first package submission experience. Hope they can be used to improve others' first package submission. 1. Support comments in .elpaignore. I think I do not need to explain why comments in this files are useful. Other similar files, such as .gitignore, support comments. Currently, by abusing how .elpaignore works, we can already add comments in it, assuming your comments won't match files you want to include in the tarball. What I ask here is to add "official" comment support and document it. 2. Document what should and should not be added to .elpaignore, maybe with reasoning. - Should .dir-locals.el be excluded? - Should license files be excluded? (I have already mentioned it in emacs-devel[1].) - Probably .elpaignore itself should be excluded. Maybe do it in elpa-admin.el so that package authors do not have to do it themselves. - .git and .gitignore are not needed to be added to .elpaignore because tar is given --exclude-vcs. - Probably README.org should be excluded since the tarball already has the rendered/exported README-elpa. 3. Document that README.org is used to export plain-text README-elpa for tarball and HTML for ELPA homepage. Also document relevant export options. Give guidance for how to organize the content of README.org. This helps increase the rendering quality of exported files in `help-mode' and HTML. - README.org should put the title in "#+title:" and use several "*", instead of putting the title in "*" and using several "**". - Authors should not enable email export via "#+email:" and "#+options: email:t". If enabled, the exported README-elpa looks bad because elpa-admin.el disables user export. - Suggest that org-mode supports export-backend-specific contents which can be used to improve files exported by specific backends. 4. Consider moving some doc from README of elpa-admin branch of ELPA git repo to https://elpa.gnu.org/contributing.html. I personally think the emacs-devel email subject format is useful to be moved. [1]: https://lists.gnu.org/archive/html/emacs-devel/2026-08/msg00500.html