Subject: Re: bug#76925: [PATCH] admin/notes/elpa: Add note on contributing to external packages

From: david <[email-masked]>
Date: Sat, 22 Mar 2025 21:20:38 -0400

Stefan Kangas <[email-masked]> writes:

> BTW, which Emacs mode are you editing this in to automatically insert
> 0x2019?
>
I manually used the ’ character in the text.

>> +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
>> +     [email-masked].
>> +   - 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).
>
The addition of this section aims to provide guidance for new GNU ELPA
package developers.  It serves as a reminder in admin/notes about the
process for accepting contributions and maintaining packages, ensuring
ongoing compliance with GNU ELPA licensing policies.

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

I've attached the updated patch incorporating your feedback, emphasizing
the need to check `:url nil` before direct commits to GNU ELPA.  I'll
wait for further instructions to proceed.

>From 01506749659fcb4415e5b4ee97619add857a39e2 Mon Sep 17 00:00:00 2001
From: dimagid <[email-masked]>
Date: Mon, 10 Mar 2025 08:39:40 -0400
Subject: [PATCH] Add note about externally hosted packages to admin/notes/elpa

This commit adds a section on handling externally hosted GNU ELPA
packages, covering contribution guidelines, copyright assignment, and
synchronization with elpa.git.

* admin/notes/elpa: Add section on externally hosted packages.
---
 admin/notes/elpa | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/admin/notes/elpa b/admin/notes/elpa
index afcda71d1dd..9425efd31af 100644
--- a/admin/notes/elpa
+++ b/admin/notes/elpa
@@ -33,3 +33,64 @@ 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:
+
+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
+     rule).  The fifteen-line rule is a guideline used by the FSF to
+     determine whether a contribution is significant enough to require
+     copyright assignment.  Contributions exceeding fifteen lines of
+     code always fall under this rule.
+   - 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:
+   - 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.
+   - Provide the contributor with clear instructions on how to complete
+     the copyright assignment process.  This always 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.
+   - Direct the contributor to the FSF's copyright assignment page for
+     more information: https://www.fsf.org/licensing/assigning.html
+
+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
+     [email-masked].
+   - Provide details about the contribution (e.g., the size of the
+     patch, the contributor's email address, and any relevant context).
+
+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.
+   - Credit the contributor in the commit history and, if applicable,
+     in the AUTHORS or THANKS file.
+
+5. Handling stagnant upstream development
+   If upstream development has stagnated and maintainers are
+   unreachable:
+   - The GNU ELPA administrators will first attempt to contact upstream
+     or find a new maintainer.
+   - As a last resort, after setting `:url nil`, changes may be
+     committed directly to `elpa.git` to keep the package functional.
-- 
2.49.0