Package: emacs;
Reported by: Stefan Kangas <stefankangas <at> gmail.com>
Date: Mon, 10 Mar 2025 19:17:01 UTC
Severity: wishlist
Tags: patch
Done: Philip Kaludercic <philipk <at> posteo.net>
Bug is archived. No further changes may be made.
Message #35 received at 76925 <at> debbugs.gnu.org (full text, mbox):
From: Stefan Kangas <stefankangas <at> gmail.com> To: david <davidimagid <at> gmail.com> Cc: Philip Kaludercic <philipk <at> posteo.net>, 76925 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>, monnier <at> iro.umontreal.ca Subject: Re: bug#76925: [PATCH] admin/notes/elpa: Add note on contributing to external packages Date: Sat, 22 Mar 2025 17:39:44 -0500
david <davidimagid <at> gmail.com> writes:
> Philip Kaludercic <philipk <at> posteo.net> writes:
>>
>> (A general comment on the tone makes this sound more micro-managey than
>> I think is necessary. IMO it is better to have a relaxed atmosphere
>> than having it sound too "corporate" for lack of a better word.)
>
> Updated patch incorporating feedback:
>
> - Adjusted tone to be more collaborative.
Thanks.
> - Clarified GNU ELPA admins' role in upstream stagnation.
What does this mean?
>>From 09842ebfbf8b123351bdec9c05e4aedff7ab640d Mon Sep 17 00:00:00 2001
> From: dimagid <dimagidve <at> gmail.com>
> Date: Mon, 10 Mar 2025 08:39:40 -0400
> Subject: [PATCH Bug#76925] Add note about externally hosted packages to
> admin/notes/elpa
>
> This commit adds a section to admin/notes/elpa documenting best practices
> for maintaining externally hosted GNU ELPA packages. It covers contribution
> guidelines, copyright assignment, and synchronization with elpa.git, while
> emphasizing a collaborative and relaxed approach to package maintenance.
> ---
> admin/notes/elpa | 77 ++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 77 insertions(+)
>
> diff --git a/admin/notes/elpa b/admin/notes/elpa
> index afcda71d1dd..6a5f2a5c360 100644
> --- a/admin/notes/elpa
> +++ b/admin/notes/elpa
> @@ -33,3 +33,80 @@ the package.
>
> It is easy to use the elpa branch to deploy a "local" copy of the
> package archive. For details, see the README file in the elpa branch.
> +
> +* Contributing to externally hosted packages
> +
> +Some GNU ELPA packages are primarily developed in external repositories
> +(e.g., on GitHub, GitLab, or similar platforms). If you maintain such
> +a package, it’s important to help contributors understand the
> +requirements for contributing, especially when it comes to copyright
> +assignment to the Free Software Foundation (FSF). Here’s what you can
> +do:
Please don't use the ’ code point (0x2019 RIGHT SINGLE QUOTATION MARK);
use the ' code point (0x27 APOSTROPHE) instead. This is for
consistency.
BTW, which Emacs mode are you editing this in to automatically insert
0x2019? Here, I usually only get that character in Emacs when I have copied
from other software, such as an LLM, or when I copy from *Help* buffers
or *Messages* (where it's inserted automatically).
> +1. Include clear contribution guidelines in your repository
> + If you include a README or CONTRIBUTING file in your external
> + repository, consider adding the following:
> + - A notice that the package is distributed through GNU ELPA.
> + - A statement that contributors must assign copyright for their
> + contributions to the FSF if the contribution is significant
> + (e.g., more than a few lines of code, following the fifteen-line
> + thumb-rule).
Clarify what is the "fifteen-line thumb-rule" here.
> + - For complete information, see the CONTRIBUTE file in the Emacs
> + repository.
> +
> +2. Handling contributions requiring copyright assignment
> + When a contributor submits a pull request or patch that requires
> + copyright assignment:
> + - Acknowledge the contribution: Thank the contributor and let them
> + know that their contribution will need to go through the FSF’s
> + copyright assignment process before it can be merged.
> + - Explain the process: Provide the contributor with clear
> + instructions on how to complete the copyright assignment process.
> + This typically involves:
> + - Filling out the FSF’s copyright assignment form.
> + - Sending the signed form to the FSF.
> + - Waiting for confirmation from the FSF that the assignment has
> + been processed.
Instead of "typically", say "always".
> + - Point to resources: Direct the contributor to the FSF’s copyright
> + assignment page for more information:
> + https://www.fsf.org/licensing/assigning.html
The bullet point headings "Acknowledge the contribution", "Explain the
process", "Point to resources" can be taken out.
> +3. Consult with GNU ELPA administrators
> + If you’re unsure whether a contribution requires copyright
> + assignment or how to handle a specific case:
> + - Reach out to the GNU ELPA administrators by emailing
> + emacs-devel <at> gnu.org.
> + - Provide details about the contribution (e.g., the size of the
> + patch, the contributor’s contact information, and any relevant
> + context).
Change "contact information" to "email address". We don't need or want
more specific information than that.
> +4. Merging contributions
> + Once the contributor has completed the copyright assignment process
> + and you’ve received confirmation from the FSF:
> + - Merge the contribution into your external repository. Note that
> + repositories under `elpa.git` should not be modified directly by
> + Emacs developers, as their upstreams are not expected to merge
> + changes made there. Instead, contributions should be made to the
> + external repository and then synchronized with `elpa.git`.
Yes.
> + However, if the upstream development appears to have stagnated and
> + the maintainers are unreachable, the GNU ELPA administrators may
> + commit changes directly to `elpa.git` to ensure the package remains
> + functional and up-to-date.
This is not our process in that case. We would reach out to upstream,
look for a new maintainer, etc. IOW, many other steps become relevant
before we take that drastic step.
In particular, we would always set `:url nil` first.
> + - In exceptional cases, minor local changes may be made directly in
> + `elpa.git` (e.g., to adapt the package to the ELPA environment).
> + However, these changes will not be reflected in the upstream
> + repository and should be kept to a minimum.
I wouldn't mention this here. "Be kept to a minimum" is a bit
misleading, since AFAIK this has never happened. If we should say
anything, we should say that.
> + - Make sure to credit the contributor in the commit history.
> + - If applicable, update the AUTHORS or THANKS file in your
> + repository to acknowledge their contribution.
Fair enough, but do we really need to repeat that?
> +5. Maintaining compliance
> + - It’s a good idea to periodically review your repository’s
> + contribution guidelines to keep them up-to-date and aligned with
> + GNU ELPA policies.
What would this look like? I'm not aware that any maintainer is doing
specific review work besides what happens when new contributors show up.
> + - Stay in touch with the GNU ELPA administrators to address any
> + questions or concerns about contributions and copyright assignment.
I'm even less sure what this might concretely look like.
> +By following these steps, you can help ensure that contributions to your
> +externally hosted package are handled in a way that complies with GNU
> +ELPA policies and respects the FSF’s copyright requirements.
I'm not sure what this paragraph specifically adds.
In general, I'm not sure about the intended target audience for this
documentation. The documentation in admin/notes is usually directed at
people maintaining Emacs, while documentation directed at package
maintainers usually go to elpa.git/README (and related files).
Maybe we should keep only the small note that boils down to:
Don't commit changes directly to packages in GNU ELPA without
checking first that they have :url nil.
And related explanations.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.