bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

[-- Attachment #1: Type: text/plain, Size: 436 bytes --]

X-Debbugs-Cc: philipk@posteo.net

 From the discussion in bug#64985, Eli mentioned that .elpaignore wasn't 
documented. (It turns out it's mentioned briefly in the GNU ELPA README, 
but that's the only place I could find.) Here's a small patch to 
document this in the Package section of the Emacs Lisp manual.

This is just a first pass at documenting this feature, so I'm happy to 
add further details if anyone thinks it's warranted.

[-- Attachment #2: 0001-doc-lispref-package.texi-Multi-file-Packages-Documen.patch --]
[-- Type: text/plain, Size: 1062 bytes --]

From a5dc5f63003aea4bda4f382ec46c0556edb14f1a Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Wed, 2 Aug 2023 21:51:18 -0700
Subject: [PATCH] * doc/lispref/package.texi (Multi-file Packages): Document
 ".elpaignore".

---
 doc/lispref/package.texi | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 2952e7dfcfc..ce29b4be72a 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -284,6 +284,13 @@ Multi-file Packages
   (expand-file-name file superfrobnicator-base))
 @end smallexample
 
+  If your project contains files that you don't wish to distribute to
+users (e.g.@: regression tests), you can add them to an
+@file{.elpaignore} file.  In this file, each line lists a file or
+wildcard matching files to ignore when producing your package's tar
+file on ELPA.  (ELPA will pass this file to @command{tar} with the
+@code{-X} option.)
+
 @node Package Archives
 @section Creating and Maintaining Package Archives
 @cindex package archive
-- 
2.25.1

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Eli Zaretskii]

> Cc: philipk@posteo.net
> Date: Wed, 2 Aug 2023 21:56:38 -0700
> From: Jim Porter <jporterbugs@gmail.com>
> 
>  From the discussion in bug#64985, Eli mentioned that .elpaignore wasn't 
> documented. (It turns out it's mentioned briefly in the GNU ELPA README, 
> but that's the only place I could find.) Here's a small patch to 
> document this in the Package section of the Emacs Lisp manual.
> 
> This is just a first pass at documenting this feature, so I'm happy to 
> add further details if anyone thinks it's warranted.

Thanks.  Adding Stefan to the discussion.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>>  From the discussion in bug#64985, Eli mentioned that .elpaignore wasn't 
>> documented. (It turns out it's mentioned briefly in the GNU ELPA README, 
>> but that's the only place I could find.)

That's because it was the only place where `.elpaignore` was used/obeyed
(until the introduction of `package-vc`).


        Stefan

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

On 8/3/2023 6:36 AM, Stefan Monnier via Bug reports for GNU Emacs, the 
Swiss army knife of text editors wrote:
>>>   From the discussion in bug#64985, Eli mentioned that .elpaignore wasn't
>>> documented. (It turns out it's mentioned briefly in the GNU ELPA README,
>>> but that's the only place I could find.)
> 
> That's because it was the only place where `.elpaignore` was used/obeyed
> (until the introduction of `package-vc`).

Yeah, something more general that I've noticed is that as a package 
author, the documentation for how to make a package for GNU ELPA is 
split between the GNU ELPA README and the Emacs Lisp manual. I found 
this a bit confusing when I prepared my first package for submission to 
GNU ELPA, so (for example) I didn't learn about ".elpaignore" until 
after I sent my package submission to emacs-devel.

Maybe it would make sense to put all the documentation in the Emacs Lisp 
manual, and then the GNU ELPA README can be the home for documentation 
about how to work with the GNU ELPA repository specifically (mainly as 
an administrator). What do you think?

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Philip Kaludercic]

Jim Porter <jporterbugs@gmail.com> writes:

> On 8/3/2023 6:36 AM, Stefan Monnier via Bug reports for GNU Emacs, the
> Swiss army knife of text editors wrote:
>>>>   From the discussion in bug#64985, Eli mentioned that .elpaignore wasn't
>>>> documented. (It turns out it's mentioned briefly in the GNU ELPA README,
>>>> but that's the only place I could find.)
>> That's because it was the only place where `.elpaignore` was
>> used/obeyed
>> (until the introduction of `package-vc`).
>
> Yeah, something more general that I've noticed is that as a package
> author, the documentation for how to make a package for GNU ELPA is
> split between the GNU ELPA README and the Emacs Lisp manual. I found
> this a bit confusing when I prepared my first package for submission
> to GNU ELPA, so (for example) I didn't learn about ".elpaignore" until
> after I sent my package submission to emacs-devel.
>
> Maybe it would make sense to put all the documentation in the Emacs
> Lisp manual, and then the GNU ELPA README can be the home for
> documentation about how to work with the GNU ELPA repository
> specifically (mainly as an administrator). What do you think?

When I find some time, I plan to write and add a package to ELPA that
could help automatise some of the necessary steps for contributing to
ELPA (explaining the difference between GNU and NonGNU, signing the CA,
testing for common mistakes, clean byte-compiling, etc.).  It would be
possible to also suggest creating a .elpaignore file as well.  Of
course, this does not mean there shouldn't be any guidelines written
down in the manual.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> Maybe it would make sense to put all the documentation in the Emacs Lisp
> manual, and then the GNU ELPA README can be the home for documentation about
> how to work with the GNU ELPA repository specifically (mainly as an
> administrator).

FWIW, that's how it started.  It's just that some of the conventions
originally used only in (Non)GNU ELPA have now made their way into
`package.el`.

> What do you think?

Any help cleaning this up is welcome.


        Stefan

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

On 8/3/2023 2:21 PM, Stefan Monnier via Bug reports for GNU Emacs, the 
Swiss army knife of text editors wrote:
>> Maybe it would make sense to put all the documentation in the Emacs Lisp
>> manual, and then the GNU ELPA README can be the home for documentation about
>> how to work with the GNU ELPA repository specifically (mainly as an
>> administrator).
> 
> FWIW, that's how it started.  It's just that some of the conventions
> originally used only in (Non)GNU ELPA have now made their way into
> `package.el`.

As a general guideline for documentation, I'm thinking that anything a 
package author puts in their own repository would get documented in the 
Emacs Lisp manual, whereas anything that goes in the (Non)GNU ELPA 
repository (e.g. in the elpa-packages file) goes in the ELPA README. 
That makes intuitive sense to me as a package author at least: then the 
Emacs Lisp manual would have everything I need to *prepare* my package 
for eventual inclusion in ELPA.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>>> Maybe it would make sense to put all the documentation in the Emacs Lisp
>>> manual, and then the GNU ELPA README can be the home for documentation about
>>> how to work with the GNU ELPA repository specifically (mainly as an
>>> administrator).
>> FWIW, that's how it started.  It's just that some of the conventions
>> originally used only in (Non)GNU ELPA have now made their way into
>> `package.el`.
>
> As a general guideline for documentation, I'm thinking that anything
>  a package author puts in their own repository would get documented in the
>  Emacs Lisp manual, whereas anything that goes in the (Non)GNU ELPA
>  repository (e.g. in the elpa-packages file) goes in the ELPA README. That
>  makes intuitive sense to me as a package author at least: then the Emacs
>  Lisp manual would have everything I need to *prepare* my package for
> eventual inclusion in ELPA.

Historically, the difference was between the format of the repository
(which only affected things like Melpa and (Non)GNU ELPA) and the format
of ELPA tarballs (which is what `package.el` dealt with).

`package-vc` makes the repository format relevant to `package.el`.
But there might still be differences between what `package-vc` requires
and what (Non)GNU ELPA requires, beside the data actually maintained in
the (Non)GNU ELPA `elpa-packages`.


        Stefan

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

On 8/3/2023 3:41 PM, Stefan Monnier via Bug reports for GNU Emacs, the 
Swiss army knife of text editors wrote:
> Historically, the difference was between the format of the repository
> (which only affected things like Melpa and (Non)GNU ELPA) and the format
> of ELPA tarballs (which is what `package.el` dealt with).
> 
> `package-vc` makes the repository format relevant to `package.el`.
> But there might still be differences between what `package-vc` requires
> and what (Non)GNU ELPA requires, beside the data actually maintained in
> the (Non)GNU ELPA `elpa-packages`.

Yeah. I do think as a package author who once wasn't sure about exactly 
what I should do to make my Emacs package follow best-practices, the 
first place I'd look is in the Package section of the Emacs Lisp manual 
(regardless of where the implementations for package management live). 
But, like you say, now that 'package-vc' exists, Emacs itself now knows 
(some) about the repo format, too.

In any case, if there are no objections in the next day or two, I'll 
merge my patch, and then look into whether there are any other things 
worth documenting. (For example, I'll try to turn my suggested 
documentation on package naming[1] into a patch.)

[1] https://lists.gnu.org/archive/html/emacs-devel/2023-05/msg00452.html

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Kangas]

Jim Porter <jporterbugs@gmail.com> writes:

> In any case, if there are no objections in the next day or two, I'll merge my
> patch, and then look into whether there are any other things worth
> documenting. (For example, I'll try to turn my suggested documentation on
> package naming[1] into a patch.)
>
> [1] https://lists.gnu.org/archive/html/emacs-devel/2023-05/msg00452.html

Was this installed?  Otherwise, please go ahead.

Your patch LGTM.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

On 9/3/2023 4:18 AM, Stefan Kangas wrote:
> Jim Porter <jporterbugs@gmail.com> writes:
> 
>> In any case, if there are no objections in the next day or two, I'll merge my
>> patch, and then look into whether there are any other things worth
>> documenting. (For example, I'll try to turn my suggested documentation on
>> package naming[1] into a patch.)
>>
>> [1] https://lists.gnu.org/archive/html/emacs-devel/2023-05/msg00452.html
> 
> Was this installed?  Otherwise, please go ahead.
> 
> Your patch LGTM.

In another subthread for this bug, we'd discussed making a *new* manual 
that discusses ELPA and/or creating packages for Emacs in general. If we 
want to create such a manual, I think that's the place my patch should 
go. However, I'm not sure what the status is on that; I have time to 
help out with it, but not enough time to write a whole manual myself.

I CCed some of the people discussing this into this subthread too.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Corwin Brust]

On Tue, Sep 5, 2023 at 8:56 PM Jim Porter <jporterbugs@gmail.com> wrote:
>
> In another subthread for this bug, we'd discussed making a *new* manual
> that discusses ELPA and/or creating packages for Emacs in general. If we
> want to create such a manual, I think that's the place my patch should
> go. However, I'm not sure what the status is on that; I have time to
> help out with it, but not enough time to write a whole manual myself.
>
> I CCed some of the people discussing this into this subthread too.
>

I'm (still) interested in working on this.  I haven't had another
offline discussion on this since I last replied in.

Key points I observed from that thread were (1) preference for
Packaging (not ELPA) as central topic, (2) expectation that we clearly
define rules for where to put things, especially WRT to moving things
already within some existing manual.

My thoughts are in the direction of working on a "mission statement"
and outline, as next steps.  I hope having an outline will help make
it possible to combine efforts from several contributors, there
probably are not many people with time to sit down and write a whole
manual :)

BTW, just in case Someone™ dies have time for this (and would find
this easies to work on if left more greenfield), it won't hurt my
feelings to have a "straw-dog" to discuss from, rather than starting
from an outline and ground-rules, as I'm suggesting/assuming.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Corwin Brust]

On Tue, Sep 5, 2023 at 9:22 PM Corwin Brust <corwin@bru.st> wrote:
>
> I'm (still) interested in working on this.   I haven't had another
> offline discussion on this since I last replied in.
>

Prot and I have resumed the offline discussion we were having.

He is catching up on a backlog of emails; I expect he will join this
conversation on-list by-and-by.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Protesilaos Stavrou]

> From: Corwin Brust <corwin@bru.st>
> Date: Tue, 19 Sep 2023 08:29:03 -0500
>
> On Tue, Sep 5, 2023 at 9:22 PM Corwin Brust <corwin@bru.st> wrote:
>>
>> I'm (still) interested in working on this.   I haven't had another
>> offline discussion on this since I last replied in.
>
> Prot and I have resumed the offline discussion we were having.
>
> He is catching up on a backlog of emails; I expect he will join this
> conversation on-list by-and-by.

Hello folks!

I did not have electricity at home.  Now I am back.  Still need to read
this thread though.

All the best,
Prot

-- 
Protesilaos Stavrou
https://protesilaos.com

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Protesilaos Stavrou]

> From: Jim Porter <jporterbugs@gmail.com>
> Date: Tue,  5 Sep 2023 18:56:36 -0700
>
> [... 14 lines elided]
>
> In another subthread for this bug, we'd discussed making a *new* manual 
> that discusses ELPA and/or creating packages for Emacs in general. If we 
> want to create such a manual, I think that's the place my patch should 
> go. However, I'm not sure what the status is on that; I have time to 
> help out with it, but not enough time to write a whole manual myself.
>
> I CCed some of the people discussing this into this subthread too.

Sorry for the delay!  I read the entire thread.  I am willing to
contribute towards the creation of a new manual.  As Stefan Monnier
noted earlier,[1] I think it is better to have it be about "Emacs
packages" with relevant subsections for where those are stored and how
they can be installed.

How do we start?  Perhaps someone can produce a draft to get things
going?  I am happy to volunteer towards that end.

Should this be in .texi or can we do it in .org format?

As always, we communicate with the maintainers before making any
changes.

Anything else we need to consider at this stage?

-- 
Protesilaos Stavrou
https://protesilaos.com

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Kangas]

Protesilaos Stavrou <info@protesilaos.com> writes:

> Sorry for the delay!  I read the entire thread.  I am willing to
> contribute towards the creation of a new manual.  As Stefan Monnier
> noted earlier,[1] I think it is better to have it be about "Emacs
> packages" with relevant subsections for where those are stored and how
> they can be installed.
>
> How do we start?  Perhaps someone can produce a draft to get things
> going?  I am happy to volunteer towards that end.

Sounds like a plan.  Thanks for working on this.

> Should this be in .texi or can we do it in .org format?

We generally prefer .texi, but either way is fine for a first draft.
It's not crucial at this stage, and we can always convert it to another
format later.  The biggest work is in writing it.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Eli Zaretskii]

> Date: Thu, 3 Aug 2023 15:02:12 -0700
> Cc: Eli Zaretskii <eliz@gnu.org>, philipk@posteo.net, 65027@debbugs.gnu.org
> From: Jim Porter <jporterbugs@gmail.com>
> 
> As a general guideline for documentation, I'm thinking that anything a 
> package author puts in their own repository would get documented in the 
> Emacs Lisp manual, whereas anything that goes in the (Non)GNU ELPA 
> repository (e.g. in the elpa-packages file) goes in the ELPA README. 
> That makes intuitive sense to me as a package author at least: then the 
> Emacs Lisp manual would have everything I need to *prepare* my package 
> for eventual inclusion in ELPA.

To have the best of both worlds, please have the ELisp manual mention
the ELPA README file, and ELPA README file to mention specific nodes
of the ELisp manual where this stuff is described.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Yeah, something more general that I've noticed is that as a package 
  > author, the documentation for how to make a package for GNU ELPA is 
  > split between the GNU ELPA README and the Emacs Lisp manual.

It could be an improvement to merge all that documentation into one
text and rewrite it for coherence and clarity.

  > Maybe it would make sense to put all the documentation in the Emacs Lisp 
  > manual,

That has a drawback: it would make the Emacs Lisp Reference Manual
substantially bigger.  Copies would be less convenient and more
expensive.

I think there is no need for this material to be in the Emacs Lisp
Reference Manual.  So I suggest making a separate short manual about
adding a package to GNU ELPA.  The Emacs Lisp Reference Manual can
direct people to it.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Corwin Brust]

On Fri, Aug 4, 2023 at 8:58 PM Richard Stallman <rms@gnu.org> wrote:
>
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Yeah, something more general that I've noticed is that as a package
>   > author, the documentation for how to make a package for GNU ELPA is
>   > split between the GNU ELPA README and the Emacs Lisp manual.
>
> It could be an improvement to merge all that documentation into one
> text and rewrite it for coherence and clarity.

I have been discussing a similar ideal with some others off list, of
whom I'm tagging in (potentially sharing blame with ;) only prot.

> That has a drawback: it would make the Emacs Lisp Reference Manual
> substantially bigger.  Copies would be less convenient and more
> expensive.
>
> I think there is no need for this material to be in the Emacs Lisp
> Reference Manual.  So I suggest making a separate short manual about
> adding a package to GNU ELPA.  The Emacs Lisp Reference Manual can
> direct people to it.

My/our suggestion is to create a new manual ("ELPA: the missing
manual") that should be provided with Emacs releases, with the current
version available online via gnu.org.

This new manual can start with some new (and/or moved, consolidated,
expanded, ...) sections aimed at Emacs users wanting a deeper
understanding of Emacs packaging.  Following that, it can include some
specifics ("best practices"?) especially for package authors, with the
remainder being collected manuals for ELPA packages.

A slight twist on this idea could be to frame more generally, for
example "Emacs Features and Packaging" (instead of anything about
ELPA).  This might allow

In any event, if this seems worth discussing further, I think work
could begin with agreeing on the specific (and probably rather narrow)
scope. I think we need, for example, to describe the criteria used to
decide what goes into the proposed addition manual.  We might also
want to create a "rubric" (simple rule, or very simple flow chart)
that helps us understand when a feature's documentation will be in the
Emacs manual, the elisp manual, or this new manual, and so on, until
the task beings to look ominously do-able or all volunteers are scared
off >:)

Prot, am I right that you (still, also) have energy for something like
this?  Other thoughts as you consider in the context of this thread?

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

On 8/4/2023 7:36 PM, Corwin Brust wrote:
> On Fri, Aug 4, 2023 at 8:58 PM Richard Stallman <rms@gnu.org> wrote:
>>
>> I think there is no need for this material to be in the Emacs Lisp
>> Reference Manual.  So I suggest making a separate short manual about
>> adding a package to GNU ELPA.  The Emacs Lisp Reference Manual can
>> direct people to it.
> 
> My/our suggestion is to create a new manual ("ELPA: the missing
> manual") that should be provided with Emacs releases, with the current
> version available online via gnu.org.

That makes sense to me. I'd be happy to help contribute to this new 
manual if others have interest in helping to share the load.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Eli Zaretskii]

> From: Corwin Brust <corwin@bru.st>
> Date: Fri, 4 Aug 2023 21:36:45 -0500
> Cc: Jim Porter <jporterbugs@gmail.com>, philipk@posteo.net, eliz@gnu.org, 
> 	monnier@iro.umontreal.ca, 65027@debbugs.gnu.org
> 
> My/our suggestion is to create a new manual ("ELPA: the missing
> manual") that should be provided with Emacs releases, with the current
> version available online via gnu.org.

If this is a replacement for the ELPA README, that'd be fine.  But if
you intend to remove stuff from the ELisp manual into this new manual,
please be sure to coordinate with me first.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> My/our suggestion is to create a new manual ("ELPA: the missing
> manual") that should be provided with Emacs releases, with the current
> version available online via gnu.org.

I tend to agree, and it shouldn't be about "ELPA" but about "Emacs
packages".  It could have a "generic" part and then specific subsections
discussing details of specific cases such as ELPA tarballs, (Non)GNU
ELPA, Melpa, straight, etc...


        Stefan

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: monnier@iro.umontreal.ca, eliz@gnu.org, philipk@posteo.net,
> 	65027@debbugs.gnu.org
> Date: Fri, 04 Aug 2023 21:58:43 -0400
> 
>   > Maybe it would make sense to put all the documentation in the Emacs Lisp 
>   > manual,
> 
> That has a drawback: it would make the Emacs Lisp Reference Manual
> substantially bigger.  Copies would be less convenient and more
> expensive.

I don't think there's a real danger here.  The necessary additions to
what is already in the ELisp manual are small.

The reason the ELisp manual touches on these issues is because it
describes package.el, which is a much more general facility, not
limited to ELPA.  The ELPA-specific stuff should not be described
there, only mentioned with a reference to the ELPA README.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Kangas]

Jim Porter <jporterbugs@gmail.com> writes:

> X-Debbugs-Cc: philipk@posteo.net
>
> From the discussion in bug#64985, Eli mentioned that .elpaignore wasn't
> documented. (It turns out it's mentioned briefly in the GNU ELPA README, but
> that's the only place I could find.) Here's a small patch to document this in
> the Package section of the Emacs Lisp manual.
>
> This is just a first pass at documenting this feature, so I'm happy to add
> further details if anyone thinks it's warranted.

There was talk in this bug report about writing a new "package manual",
and Protesilaos volunteered to write a first draft.

But while we wait for that work to complete, is there any reason not to
install the below patch?  Because we currently don't have any
documentation for .elpaignore, and it's kind of frustrating to have to
tell people that it exists over and over.

Thoughts/objections?  Thanks in advance.

> From a5dc5f63003aea4bda4f382ec46c0556edb14f1a Mon Sep 17 00:00:00 2001
> From: Jim Porter <jporterbugs@gmail.com>
> Date: Wed, 2 Aug 2023 21:51:18 -0700
> Subject: [PATCH] * doc/lispref/package.texi (Multi-file Packages): Document
>  ".elpaignore".
>
> ---
>  doc/lispref/package.texi | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
> index 2952e7dfcfc..ce29b4be72a 100644
> --- a/doc/lispref/package.texi
> +++ b/doc/lispref/package.texi
> @@ -284,6 +284,13 @@ Multi-file Packages
>    (expand-file-name file superfrobnicator-base))
>  @end smallexample
>
> +  If your project contains files that you don't wish to distribute to
> +users (e.g.@: regression tests), you can add them to an
> +@file{.elpaignore} file.  In this file, each line lists a file or
> +wildcard matching files to ignore when producing your package's tar
> +file on ELPA.  (ELPA will pass this file to @command{tar} with the
> +@code{-X} option.)
> +
>  @node Package Archives
>  @section Creating and Maintaining Package Archives
>  @cindex package archive

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

On 1/10/2024 1:49 PM, Stefan Kangas wrote:
> But while we wait for that work to complete, is there any reason not to
> install the below patch?  Because we currently don't have any
> documentation for .elpaignore, and it's kind of frustrating to have to
> tell people that it exists over and over.
> 
> Thoughts/objections?  Thanks in advance.

Makes sense to me. If others agree, I can merge my patch.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Jim Porter]

On 1/11/2024 11:35 AM, Jim Porter wrote:
> On 1/10/2024 1:49 PM, Stefan Kangas wrote:
>> But while we wait for that work to complete, is there any reason not to
>> install the below patch?  Because we currently don't have any
>> documentation for .elpaignore, and it's kind of frustrating to have to
>> tell people that it exists over and over.
>>
>> Thoughts/objections?  Thanks in advance.
> 
> Makes sense to me. If others agree, I can merge my patch.

Since no one has had any further comments in the last couple weeks, I've 
now merged my patch to master as 744a10a4d72. Of course, we can work on 
a more elaborate packaging manual in the future. I'll leave this bug 
open for now to discuss that, but if maintainers prefer, we could always 
close this and open a new bug specifically about the packaging manual 
side of things.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Kangas]

Jim Porter <jporterbugs@gmail.com> writes:

> Since no one has had any further comments in the last couple weeks, I've
> now merged my patch to master as 744a10a4d72. Of course, we can work on
> a more elaborate packaging manual in the future. I'll leave this bug
> open for now to discuss that, but if maintainers prefer, we could always
> close this and open a new bug specifically about the packaging manual
> side of things.

Thanks.

I think a new bug is better, indeed:

It takes significant effort to sift through a bug like this one to
uncover that it's not, in fact, about "[PATCH] Document .elpaignore
behavior in the Emacs Lisp manual", but about some other related yet
distinct change.

It's fine to have one or two such bugs, but we have many hundreds.  This
makes using and maintaining the bug tracker harder than it needs to be.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Eli Zaretskii]

> Cc: philipk@posteo.net, corwin@bru.st, monnier@iro.umontreal.ca,
>  info@protesilaos.com, 65027@debbugs.gnu.org
> Date: Sat, 27 Jan 2024 12:34:17 -0800
> From: Jim Porter <jporterbugs@gmail.com>
> 
> On 1/11/2024 11:35 AM, Jim Porter wrote:
> > On 1/10/2024 1:49 PM, Stefan Kangas wrote:
> >> But while we wait for that work to complete, is there any reason not to
> >> install the below patch?  Because we currently don't have any
> >> documentation for .elpaignore, and it's kind of frustrating to have to
> >> tell people that it exists over and over.
> >>
> >> Thoughts/objections?  Thanks in advance.
> > 
> > Makes sense to me. If others agree, I can merge my patch.
> 
> Since no one has had any further comments in the last couple weeks, I've 
> now merged my patch to master as 744a10a4d72.

Thanks, I fixed it slightly.

Btw, it is a bit strange in my eyes that this chapter talks about
package organization conventions on ELPA without ever mentioning that
those conventions are specific for ELPA, nor even describing what ELPA
is until a later section.  Perhaps the organization of the chapter
should be rethought, given that it no longer describes only
package.el, but also the conventions and requirements for submitting
packages to ELPA.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, I fixed it slightly.

I cherry-picked it to emacs-29, so perhaps the fix should be
cherry-picked there too.  It seemed more natural for a documentation fix
to be on the release branch.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sat, 27 Jan 2024 21:49:23 -0800
> Cc: philipk@posteo.net, corwin@bru.st, monnier@iro.umontreal.ca, 
> 	info@protesilaos.com, 65027@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks, I fixed it slightly.
> 
> I cherry-picked it to emacs-29, so perhaps the fix should be
> cherry-picked there too.  It seemed more natural for a documentation fix
> to be on the release branch.

I wasn't sure the description is valid for Emacs 29.  If it is, then
yes, please cherry-pick the fix as well.

bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Stefan Kangas]

Protesilaos Stavrou <info@protesilaos.com> writes:

> I still want to do it, but there have been two major changes ever
> since:
>
> 1. I have limited electricity, so I do not have as much computer time as
>    I want.
>
> 2. I have been suffering on and off from pain in my arms, which limits
>    how much I type.

Thank you for persevering despite these difficulties.  We are not in any
kind of rush, and your contributions are appreciated.