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

Lin Jian <[email protected]> writes:

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

It is not unimaginable for me that someone just downloads the .el file
from GitHub and places it in their User Lisp directory, but it doesn't
matter for now since we are not fixing permanent decisions here.

>> 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 have never heard that argument, but it is good to know that this is an
advantage ^^

>> 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 :)

Very well, I am not convinced by the argument but that is my opinion and
not a guideline.  The main thing is that the README provides a good
overview for package-describe, which I think it does.

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

(Nice to know)

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

Related to this: Are you aware of the
https://elpa.gnu.org/packages/elpa-packages.eld file, that package-vc
uses?

> 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 :)

There have been no comments, just one thing I forgot to mention: The
current name is rather brief and potentially misleading.  Or at least my
first association with "project-store" isn't Nix' "store" but the
ability to store some data in a project, or something like that.  The
ambiguity is resolved by the one-line summary at the top of the file,
but I just wanted to ask what your opinion would be of renaming the
package to something more specific like "project-nix-store"?