Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

"Alfred M. Szmidt" <ams@gnu.org> writes:

>    So, yes, contributing to Emacs is hard.
>
> You might not _prefer_ the way it is done, but it is not hard as you
> purport it to be.  The chapter "Sending patches" is eight relativley
> simple bullets, the CONTRIBUTING is also not a very hard document to
> follow.

I think here’s a misconception about writing: 8 bullet points is not
simple. 4 bullet points are simple and can be grasped by humans
directly. Anything more becomes complex.



But let’s not discuss without the context at hand:

- Sending Patches: 
https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html
- CONTRIBUTE: https://www.gnu.org/software/emacs/CONTRIBUTE

The starting point to contribute is usually the website: 

    https://www.gnu.org/software/emacs

You can find Sending Patches if you click on Documentation & Support,
then go into the manual and search for sending patches — or check in the
reporting bugs section. That’s at least 3 clicks if you know what you’re
doing. If you don’t — good luck finding it.

The Reporting bugs section in Documentation & Support only links the
CONTRIBUTE file as plain text, even though it’s org-mode, so it could be
linked as html (easier to read in the browser). That’s only two links to
click — again: if you know what you’re doing.

As an aside: IRC is linked in "further information", not in
"documentation and support" — I’m not sure why that page exists, because
all the content seems to belong to Documentation & support. Maybe that
could be replaced by a dedicated "Contributing" page with a shorter
version of sending patches.


To make this constructive: If this is intended to be easy, I’d have
imagined something like this (using Sending Patches as base).

------ ------ ------ ------ ------ ------ 

To contribute patches please make them easy to use for maintainers:

- patch format: Send patches with explanation in a single email as MIME
  attachment or inline. Create your patches with diff -u (with the old
  version as first version) or with ~git format-patch master~ (for
  commited changes) or ~git diff~ (for uncommited changes).

- commit log: Include a commit log entry in the correct style. They are
  described in
  
https://www.gnu.org/software/emacs/manual/html_node/emacs/Format-of-ChangeLog.html
  Look at earlier commits for examples.

- target address: Send unfinished patches for discussion to
  emacs-devel@gnu.org. Send fixes for an existing bug to the
  <number>@debbugs.gnu.org address of the bug. Send new bug-reports with
  fix to bug-gnu-emacs@gnu.org.

- patch content: Please send atomic changes: we’d rather get two emails
  than one that mixes concerns. For new bugs, use ~M-x report-emacs-bug~
  to include the information needed for bug-reports.

For more details, please read at
https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html

------ ------ ------ ------ ------ ------ 

I believe that this includes the essential information from
https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html
so someone following these 4 bullet points will already send patches in
the required format. This should be much easier to parse for
contributors.

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

signature.asc
Description: PGP signature