Re: [NonGNU ELPA] New package: project-store

Philip Kaludercic <[email protected]> writes:

>> - When users read Commentary in Emacs, they can easily run
>>   `describe-package' to get more documentation, if they are not
>>   satisfied with the brief description at the first line of
>>   project-store.el.
>
> Only if you have installed the package.

Yes, that was the case I intended to describe.

If the package is not installed, which is not common I think, users
should have access to README-elpa from the tarball or README.org from
the source.

> I would still argue that the README and the Commentary have two
> different target audiences: The former is a general introduction to the
> repository and usually contains information about how to contribute,
> what the layout of the project is, how to build it, etc. while the
> Commentary is specifically targeted at the user and reader of the Elisp
> script.  If I do a M-x find-feature to open a file, it is annoying to
> find an indirection.  So for me this wouldn't be a duplication at all,
> but two different expositions.

Besides README, it is common to put development-specific things into
CONTRIBUTING.  Similarly, other things can be moved out of README into
other files like SECURITY.  Those files sometimes are called as
"community health files".

So it is possible to achieve: README = Commentary + a few other things.
In that case, referring to README in Commentary starts to make sense, I
guess.

Actually, one strong reason for me to submit my packages to NonGNU ELPA
instead of other ELPAs not maintained by GNU is that I can use
README.org as the single source of truth for user-oriented doc:

- README.org is rendered/exported into plain text README-elpa in the
  tarball.  README-elpa is displayed in `help-mode' by
  `describe-package'.
- README.org is rendered/exported into HTML, as part of ELPA homepage.
- README.org is rendered by source code hosting platforms.

Note that `org-mode' supports export-backend-specific content, which can
be used to improve README-elpa and HTML (but can make rendering in
source code hosting platform worse?).

Unfortunately, README.org rendering (similarly for NEWS and info manual)
done by ELPA is not documented.  If documented, I believe it is a big
incentive for package authors to prefer (Non)GNU ELPA over other ELPAs.

> I am not saying you have to, I would just recommend as it is
> conventional and IMO useful to have a standalone commentary for the
> script.

Thanks for the suggestion.

I decide to break conventions when I think it is justified.  Besides
referring to README in Commentary, I also:

- use REUSE to specify license and copyright
- use "invalid" items in "Keywords:", if we treat what
  "(elisp) Library Headers" says as the convention :)

>> When I write this package, I have Nix store in mind.  I do not use Guix.
>> (Also, unlike Nix, I did not find doc about Guix store specification.)
>> So I do not plan to keep this package working with Guix, if Guix store
>> diverges from Nix store in the future.  Note that I also do not object
>> to fixing Guix compatibility.  Patch is welcome.
>>
>> I am careful with the wording about Guix in the documentation and code.
>> My intention is to convey only that currently project-store *happens* to
>> also work with Guix store.  So I will not mention Guix in the type of
>> `project-store-dir'.

Just to be clear, if there are other contributors who want to maintain
Guix compatibility in project-store, we can state that more clear in the
doc and code.

> IIUC this would basically amount to having a list of directories that
> could serve as stores?

Yes.  Probably also need to add more items in the project instance (and
maybe also merge two caches into one).

After adding items, it is worth considering switching the project
instance from the list form (store ROOT) to a `cl-defstruct'.  Do
benchmarks for this change.

> Oh, do Nix/Guix use our tarballs, instead of building directory from
> source?

Last time I checked, Guix did not use ELPA-built tarballs.  In addition,
they did not use metadata (archive-contents file) from ELPAs.  They
fetched source code from upstream repo and they used their own code to
build packages.

I maintain Emacs ecosystem in NixOS.  We do things differently than
Guix.

We use use metadata (archive-contents file) from ELPAs to automatically
generate Emacs lisp packages.  For ELPAs not maintained by GNU, we fetch
source code from upstream repos, use package-build.el to build tarballs
and then use builtin functions to compile.  For (Non)GNU ELPA, we fetch
ELPA-built tarballs.  This difference is due to historical reasons.  I
am working a change for (Non)GNU ELPA packages: fetch source code from
upstream repos and use elpa-admin.el to build tarballs.  Since
elpa-admin.el is used, .elpaignore is also respected.

In case people want to know, fetching upstream source and building
tarballs are better for reproducibility than fetching ELPA-built
tarballs.  Old ELPA-built tarballs can be deleted.  Or their content or
metadata, such as date, can be changed.

> Ah yes, I forgot about that.  In that case I would add a comment to
> avoid confusing future readers.
> ...
> Here again a comment would be useful.

Good idea, added.  I guess this was my last chance to force-push, so I
grabbed it :)

> But that shouldn't stand in the way of adding the package itself to
> NonGNU ELPA.  I'll leave some more time for further comments, but IMO
> everything ought to be fine now :)

Excited to see my first package on NonGNU ELPA :)