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

From: david <[email-masked]>
Date: Tue, 11 Mar 2025 17:50:23 -0400

Philip Kaludercic <[email-masked]> writes:

> david <[email-masked]> writes:
>
>> Eli Zaretskii <[email-masked]> writes:
>>
>>>> From: Stefan Kangas <[email-masked]>
>>>> Date: Tue, 11 Mar 2025 08:40:46 -0400
>>>> Cc: [email-masked], [email-masked], [email-masked], 
>>>> 	[email-masked]
>>>> 
>>>> Eli Zaretskii <[email-masked]> writes:
>>>> 
>>>> >> Cc: david <[email-masked]>, Philip Kaludercic <[email-masked]>,
>>>> >>  Stefan Monnier <[email-masked]>
>>>> >> From: Stefan Kangas <[email-masked]>
>>>> >> Date: Mon, 10 Mar 2025 12:15:48 -0700
>>>> >>
>>>> >> I'm forwarding this from emacs-devel so that we don't lose track of it.
>>>> >
>>>> > Is ELPA documentation exempt from our convention to use US English?
>>>> 
>>>> AFAIK, no.
>>>
>>> Then there a few nits to be fixed in that text.  Like two spaces
>>> between sentences.
>>
>> Hi,
>>
>> This patch fixes the issue described in Bug#76925 by clarifying the
>> guidelines for contributing to externally hosted packages in GNU ELPA.  
>> The changes include:
>>
>> 1. Added two spaces after periods for better readability.
>> 2. Clarified the process for making local changes in `elpa.git`.
>>
>> Please review and let me know if any further changes are needed.
>>
>> Thanks,
>> David D.
>>
>> From 4970c30be128f9806edd8d14dff82103edf49264 Mon Sep 17 00:00:00 2001
>> From: dimagid <[email-masked]>
>> Date: Mon, 10 Mar 2025 08:39:40 -0400
>> Subject: [PATCH Bug#76925] Add note about externally hosted packages to
>>  admin/notes/elpa
>>
>> ---
>>  admin/notes/elpa | 71 ++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 71 insertions(+)
>>
>> diff --git a/admin/notes/elpa b/admin/notes/elpa
>> index afcda71d1dd..c6debf4bfce 100644
>> --- a/admin/notes/elpa
>> +++ b/admin/notes/elpa
>> @@ -33,3 +33,74 @@ 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 is important to ensure that contributors understand the
>> +requirements for contributing, especially when it comes to copyright
>> +assignment to the Free Software Foundation (FSF).  Here’s what you need
>> +to do:
>> +
>> +1. Include Clear Contribution Guidelines in Your Repository
>> +   Ensure your external repository's README or CONTRIBUTING file
>
> Why is this partially title-cased?
>
>> +   includes 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).
>> +   - For complete information, see the CONTRIBUTE file in the Emacs
>> +     repository.
>
> Also, this is not a requirement.  There is no need for any README file
> at all, and I don't think we should force people to have them.
>

Ok I can fix that.

>> +
>> +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.
>> +   - Point to Resources: Direct the contributor to the FSF’s copyright
>> +     assignment page for more information:
>> +     https://www.fsf.org/licensing/assigning.html
>
> I would mention the fifteen-line thumb-rule for "significance of a
> contribution" somewhere here.
>

I can also include this.

>> +
>> +3. Consult with GNU ELPA Administrators
>> +   If you are unsure whether a contribution requires copyright
>> +   assignment or how to handle a specific case:
>> +   - Consult with 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).
>> +
>> +4. Merging Contributions
>> +   Once the contributor has completed the copyright assignment process
>> +   and you have 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`.
>
> Should we clarify that the ELPA administrators might commit to the
> repository if the upstream development appears to have stagnated and is
> not reachable?
>

The original PATCH didn't address this. The ELPA README mentions
it briefly, but on emacs-devel, I was advised to include a
reference to it here.

>> +   - 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.
>> +   - Ensure the contributor is properly credited in the commit history.
>> +   - If applicable, update the AUTHORS or THANKS file in your
>> +     repository to acknowledge their contribution.
>> +
>> +5. Maintaining Compliance
>> +   - Periodically review your repository’s contribution guidelines to
>> +     ensure they are up-to-date and align with GNU ELPA policies.
>> +   - Stay in touch with the GNU ELPA administrators to address any
>> +     questions or concerns about contributions and copyright assignment.
>> +
>> +By following these steps, you can 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.
>
> (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.)

Hi Philip,

I proposed this patch after receiving a pull request for my recently
published ELPA package—a minor typo fix. This made me wonder: what if a
significant contribution comes from an unknown developer? I checked the
ELPA README and the document I'm patching but found no explicit
guidance. While I know that ELPA contributors must sign the FSF
copyright assignment for substantial code changes, I believe we should
provide clearer instructions for handling external contributions,
especially for authors and maintainers looking to publish new packages
on GNU ELPA.

However, ELPA code can transition to the core with minimal friction.
This is why I propose clarifying these details in the patch wording,
and why I included this in the Emacs developer notes.