Re: Gitlab Migration

[Jim Porter]

On 8/26/2021 10:59 AM, Lars Ingebrigtsen wrote:
> It seems like it should be easier to just send a patch, but feedback
> we're getting shows that it's not for a number of developers.  Many
> don't use mail at all for development, and all they're used to is the
> GitLab/Hub way of doing it.

I'm pretty new contributing to Emacs, and so I can definitely understand 
the feeling of intimidation about using a mailing list-based workflow 
for contributions. However, once I actually tried it, it turned out to 
be very similar as a contributor (I don't know if I'd want to *maintain* 
a project using a mailing list workflow, but that's not my job, so it's 
not a problem for me).

One issue, however, is that the documentation for sending patches[1], 
while very thorough, doesn't make things easy to understand for someone 
familiar with a pull request workflow. While all the advice in the 
documentation is useful, a lot of it is stuff that anyone who's sent a 
PR before (hopefully) already knows, such as, "Don’t mix together 
changes made for different reasons. Send them individually."

After resolving to read the documentation thoroughly, I realized I only 
really needed a few short bits of advice:

1) The bug tracker is at https://debbugs.gnu.org
2) To submit a patch:
   a) Clone the Emacs git repo
   b) Make a branch and add some commits (as usual for the PR workflow)
   c) Run `git format-patch master`
   d) Compose an email to bug-gnu-emacs@ with the files in (c) attached
3) Commit messages have a special format (but you can just imitate what 
you see in prior commits)

Almost everything else is either common advice for contributing to any 
project, or something maintainers can address after a patch is submitted 
(e.g. copyright assignment). While I don't think the existing 
documentation should be removed, having a "quick-start intro" for people 
already familiar with the PR workflow would probably go a long way 
towards making new contributors feel less intimidated.

If the above sounds reasonable, I can work on a patch to the docs once 
my copyright paperwork is updated (or someone else can update them 
instead; I don't have a preference). It might even be helpful to add a 
"Contributing" section to the main Emacs homepage[2] with a short 
version of what's already in the full documentation.

- Jim

[1] 
https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html
[2] https://www.gnu.org/software/emacs/