Contributing to Emacs

Contributing to Emacs

[Jacob Criner]

[-- Attachment #1: Type: text/plain, Size: 88 bytes --]

Hello,

I would like to support Emacs by writing documentation. Thank you.

Best, Jacob

[-- Attachment #2: Type: text/html, Size: 175 bytes --]

Re: Contributing to Emacs

[Xue Fuqiao]

On Tue, 19 Mar 2013 22:44:30 -0700
Jacob Criner <jacobcriner@gmail.com> wrote:

> Hello,

Hi,

> I would like to support Emacs by writing documentation.

Thanks!  What are you interested in?  Texinfo files?  Man pages?  Or doc
strings?  (Maybe refcard is also a kind of documentation.)

Some small suggestions:
1. Assign the copyright to the FSF for non-trivial contributions;
2. Use the latest version of Emacs (bzr trunk);
3. Sending the patch(es) to bug-gnu-emacs@gnu.org

See also:
http://www.gnu.org/prep/standards/html_node/Documentation.html#Documentation

-- 
Xue Fuqiao
http://www.gnu.org/software/emacs/

Re: Contributing to Emacs

[Stefan Monnier]

> I would like to support Emacs by writing documentation. Thank you.

Thank you very much.
We'd be very happy to have you help us with Emacs's documentation.
Here are the things we usually need w.r.t our documentation:
- Proof-reading the manuals.  That's also a great way to learn more
  about Emacs (even for "veterans" like myself).
  This is usually done together with reading the NEWS file to make sure
  that the manual has been updated.
- Translating the tutorial in some other language.
- Add documentation about some package/feature that isn't mentioned
  in the manual or doesn't have its own manual yet.
- Compare docstrings with the corresponding description in the manual
  (when applicable).  They usually shouldn't be identical, but they
  should not contradict each other.  Generally the manual gives a bit
  less details but more background/context.
Take your pick,


        Stefan

RE: Contributing to Emacs

[Drew Adams]

> > I would like to support Emacs by writing documentation. Thank you.
> 
> Thank you very much.
> We'd be very happy to have you help us with Emacs's documentation.
> Here are the things we usually need w.r.t our documentation:
> - Proof-reading the manuals.  That's also a great way to learn more
>   about Emacs (even for "veterans" like myself).
>   This is usually done together with reading the NEWS file to 
>   make sure that the manual has been updated.
> - Translating the tutorial in some other language.
> - Add documentation about some package/feature that isn't mentioned
>   in the manual or doesn't have its own manual yet.
> - Compare docstrings with the corresponding description in the manual
>   (when applicable).  They usually shouldn't be identical, but they
>   should not contradict each other.  Generally the manual gives a bit
>   less details but more background/context.
> Take your pick,

Not to mention that there are plenty of outstanding doc bugs.  Readers have
already proof-read the manuals to some extent, and reported specific problems
and suggestions for improvement.

http://debbugs.gnu.org/cgi/pkgreport.cgi?archive=both;include=subject%3Adoc;excl
ude=pending%3Adone;package=emacs

Not every report with Subject matching "doc" is a doc bug report, of course, and
there are reported doc bugs whose Subject does not match "doc".  But it's a
start.

Contributing to Emacs

[João Paulo Labegalini de Carvalho]

[-- Attachment #1: Type: text/plain, Size: 2802 bytes --]

Hi,

I started using Emacs about 2 months ago. Now that I am comfortable with
customizing Emacs, getting help, and Elisp, I would like to contribute to
the project.

 I was looking at the file etc/TODO in the repo, and some items there
caught my attention. For example, under 'Important Features'  I found 'Add
an "indirect goto" byte-code'. Is this still a desired feature or is it not
required due to recent efforts towards native compilation? (In the negative
case, please feel free to suggest another item for me to work on)

If it is still desired I would like to work on it and would appreciate
guidance. After taking a look at lisp/emacs-lisp/bytecomp.el,it seems that
forms such as

 (let ((foo (lambda (x) bar)))
     (dosomething
       (funcall foo toto)
       (blabla (funcall foo titi))))

are compiled by calling byte-compile-let. Before generating the binding for
foo, #'(lambda (x) bar) is compiled by calling
byte-compile-push-binding-init, which in turn compiles the lambda to
bytecode and pushes it to the stack.

So to make it more concrete for my sake, I wrote the following form

(let ((foo (lambda (x) (- x 1))))
  (* (funcall foo 2)
     (- (funcall foo 3) 2)))

and with disassemble inspected the generated bytecode by Emacs 28.1

byte code:
  args: nil
0       constant  <compiled-function>
      args: (x)
    0       varref    x
    1       sub1
    2       return

1       dup
2       varbind   foo
3       constant  2
4       call      1
5       varref    foo
6       constant  3
7       call      1
8       constant  2
9       diff
10      mult
11      unbind    1
12      return

As far as I understood,  the idea of the "indirect goto" here is to
eliminate the calls on lines 4 and 7 and replace them with an indirect
goto. And as per the TODO entry, the return in line 2 of the compiled
lambda would also need to be replaced by a jump back.

So here is where I am a bit lost. Currently, the compiled lambda bytecode
lives in the *constant vector* and a reference(?) to it is pushed into
the *evaluation
stack* in line 0 (constant <compiled-function>). Thus, for the indirect
goto idea to work, the bytecode of the lambda would need to be part of the
bytecode of the let's body**. That way, a computed branch can branch into
the lambdas code and it is possible to branch out of it when returning.

Aside from guidance on implementing this, I would appreciate any pointers
on how to adequately test it.

Regards,
-- 
João Paulo L. de Carvalho
Ph.D Computer Science |  IC-UNICAMP | Campinas , SP - Brazil
Postdoctoral Research Fellow | University of Alberta | Edmonton, AB - Canada
joao.carvalho@ic.unicamp.br
joao.carvalho@ualberta.ca

** Forgive me for the lack/miss use of terminology.

[-- Attachment #2: Type: text/html, Size: 3958 bytes --]

Re: Contributing to Emacs

[Mattias Engdegård]

7 sep. 2022 kl. 22.01 skrev João Paulo Labegalini de Carvalho <jaopaulolc@gmail.com>:

>  I was looking at the file etc/TODO in the repo, and some items there caught my attention. For example, under 'Important Features'  I found 'Add an "indirect goto" byte-code'. Is this still a desired feature

That file is a bit misleading. Adding a byte-code is easy; modifying the compiler is more work, and so is deciding what byte-codes to add and what they should look like.

I'd even go as far as saying that etc/TODO isn't necessarily a catalog of where new contributors should best direct their efforts.

Why don't you think of something that you personally would like Emacs to do that it currently does not, or doesn't do well enough? Or fix something that annoys you daily in your work? Such issues are never in short supply, and your time addressing them would be well-spent.

Re: Contributing to Emacs

[Christopher Dimech]

[-- Attachment #1: Type: text/html, Size: 6347 bytes --]

Re: Contributing to Emacs

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: emacs-devel@gnu.org
> Date: Wed, 7 Sep 2022 23:33:17 +0200
> Sensitivity: Normal
> 
> 1.  Text Scaling
> ****************
>  
> a.  When resizing windows and frames, scale the font size of text accordingly.
> b.  When scaling the font size of text, scale the windows and frames accordingly.
> c.  Scale the font size of text to fit the window or frame size.

These are basically the same feature, and it already exists on the
master branch.

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Thursday, September 08, 2022 at 5:40 PM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: emacs-devel@gnu.org
> > Date: Wed, 7 Sep 2022 23:33:17 +0200
> > Sensitivity: Normal
> >
> > 1.  Text Scaling
> > ****************
> >
> > a.  When resizing windows and frames, scale the font size of text accordingly.
> > b.  When scaling the font size of text, scale the windows and frames accordingly.
> > c.  Scale the font size of text to fit the window or frame size.
>
> These are basically the same feature, and it already exists on the
> master branch.

Will test it and report back.  I knew there were some attempt.  Although
some of the functionality was there, it did not work well in particular
circumstances.

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Thursday, September 08, 2022 at 5:40 PM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: emacs-devel@gnu.org
> > Date: Wed, 7 Sep 2022 23:33:17 +0200
> > Sensitivity: Normal
> >
> > 1.  Text Scaling
> > ****************
> >
> > a.  When resizing windows and frames, scale the font size of text accordingly.
> > b.  When scaling the font size of text, scale the windows and frames accordingly.
> > c.  Scale the font size of text to fit the window or frame size.
>
> These are basically the same feature, and it already exists on the
> master branch.

@Eli, Have read INSTALL file and it should include the ./autogen.sh
tool as step "1b".

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Thursday, September 08, 2022 at 5:40 PM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: emacs-devel@gnu.org
> > Date: Wed, 7 Sep 2022 23:33:17 +0200
> > Sensitivity: Normal
> >
> > 1.  Text Scaling
> > ****************
> >
> > a.  When resizing windows and frames, scale the font size of text accordingly.
> > b.  When scaling the font size of text, scale the windows and frames accordingly.
> > c.  Scale the font size of text to fit the window or frame size.
>
> These are basically the same feature, and it already exists on the
> master branch.

@Eli, a pleasant thing would be to mention the commands for window and frame
related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".

Re: Contributing to Emacs

[Robert Pluim]

>>>>> On Thu, 8 Sep 2022 13:57:10 +0200, Christopher Dimech <dimech@gmx.com> said:

    >> Sent: Thursday, September 08, 2022 at 5:40 PM
    >> From: "Eli Zaretskii" <eliz@gnu.org>
    >> To: "Christopher Dimech" <dimech@gmx.com>
    >> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
    >> Subject: Re: Contributing to Emacs
    >> 
    >> > From: Christopher Dimech <dimech@gmx.com>
    >> > Cc: emacs-devel@gnu.org
    >> > Date: Wed, 7 Sep 2022 23:33:17 +0200
    >> > Sensitivity: Normal
    >> >
    >> > 1.  Text Scaling
    >> > ****************
    >> >
    >> > a.  When resizing windows and frames, scale the font size of text accordingly.
    >> > b.  When scaling the font size of text, scale the windows and frames accordingly.
    >> > c.  Scale the font size of text to fit the window or frame size.
    >> 
    >> These are basically the same feature, and it already exists on the
    >> master branch.

    Christopher> @Eli, Have read INSTALL file and it should include the ./autogen.sh
    Christopher> tool as step "1b".

Only when youʼre building from a git checkout, in which case you
should read INSTALL.REPO, which has that step.

Robert
-- 

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Friday, September 09, 2022 at 12:27 AM
> From: "Robert Pluim" <rpluim@gmail.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Eli Zaretskii" <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> >>>>> On Thu, 8 Sep 2022 13:57:10 +0200, Christopher Dimech <dimech@gmx.com> said:
> 
>     >> Sent: Thursday, September 08, 2022 at 5:40 PM
>     >> From: "Eli Zaretskii" <eliz@gnu.org>
>     >> To: "Christopher Dimech" <dimech@gmx.com>
>     >> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
>     >> Subject: Re: Contributing to Emacs
>     >> 
>     >> > From: Christopher Dimech <dimech@gmx.com>
>     >> > Cc: emacs-devel@gnu.org
>     >> > Date: Wed, 7 Sep 2022 23:33:17 +0200
>     >> > Sensitivity: Normal
>     >> >
>     >> > 1.  Text Scaling
>     >> > ****************
>     >> >
>     >> > a.  When resizing windows and frames, scale the font size of text accordingly.
>     >> > b.  When scaling the font size of text, scale the windows and frames accordingly.
>     >> > c.  Scale the font size of text to fit the window or frame size.
>     >> 
>     >> These are basically the same feature, and it already exists on the
>     >> master branch.
> 
>     Christopher> @Eli, Have read INSTALL file and it should include the ./autogen.sh
>     Christopher> tool as step "1b".
> 
> Only when youʼre building from a git checkout, in which case you
> should read INSTALL.REPO, which has that step.
> 
> Robert
 
@Robert.  I would then suggest to include what INSTALL and INSTALL.REPO
are meant for immediately at the beginning of README.

Re: Contributing to Emacs

[Robert Pluim]

>>>>> On Thu, 8 Sep 2022 15:11:29 +0200, Christopher Dimech <dimech@gmx.com> said:

    >> Only when youʼre building from a git checkout, in which case you
    >> should read INSTALL.REPO, which has that step.
    >> 
    >> Robert
 
    Christopher> @Robert.  I would then suggest to include what INSTALL and INSTALL.REPO
    Christopher> are meant for immediately at the beginning of README.

Line 8 of README:

    The file INSTALL in this directory says how to build and install GNU
    Emacs on various systems, once you have unpacked or checked out the
    entire Emacs file tree.

although perhaps that 'checked out' bit should be removed or refer to
INSTALL.REPO.

Robert
-- 

Re: Contributing to Emacs

[Óscar Fuentes]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Thu, 8 Sep 2022 15:11:29 +0200, Christopher Dimech <dimech@gmx.com> said:
>
>     >> Only when youʼre building from a git checkout, in which case you
>     >> should read INSTALL.REPO, which has that step.
>     >> 
>     >> Robert
>  
>     Christopher> @Robert.  I would then suggest to include what INSTALL and INSTALL.REPO
>     Christopher> are meant for immediately at the beginning of README.
>
> Line 8 of README:
>
>     The file INSTALL in this directory says how to build and install GNU
>     Emacs on various systems, once you have unpacked or checked out the
>     entire Emacs file tree.
>
> although perhaps that 'checked out' bit should be removed or refer to
> INSTALL.REPO.

You are supposed to use the instructions on INSTALL for building an
Emacs checkout too. Among those instructions, at the beginning, it is
said that you must start with the steps written in INSTALL.REPO in case
you are building a checkout.

It looks fine to me.

Re: Contributing to Emacs

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> Date: Thu, 8 Sep 2022 14:12:01 +0200
> 
> @Eli, a pleasant thing would be to mention the commands for window and frame
> related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".

They are mentioned in the doc string of text-scale-adjust, which is
the preferred user interface for this.

Re: Contributing to Emacs

[Robert Pluim]

>>>>> On Thu, 08 Sep 2022 15:38:40 +0200, Óscar Fuentes <ofv@wanadoo.es> said:

    Óscar> Robert Pluim <rpluim@gmail.com> writes:
    >>>>>>> On Thu, 8 Sep 2022 15:11:29 +0200, Christopher Dimech <dimech@gmx.com> said:
    >> 
    >> >> Only when youʼre building from a git checkout, in which case you
    >> >> should read INSTALL.REPO, which has that step.
    >> >> 
    >> >> Robert
    >> 
    Christopher> @Robert.  I would then suggest to include what INSTALL and INSTALL.REPO
    Christopher> are meant for immediately at the beginning of README.
    >> 
    >> Line 8 of README:
    >> 
    >> The file INSTALL in this directory says how to build and install GNU
    >> Emacs on various systems, once you have unpacked or checked out the
    >> entire Emacs file tree.
    >> 
    >> although perhaps that 'checked out' bit should be removed or refer to
    >> INSTALL.REPO.

    Óscar> You are supposed to use the instructions on INSTALL for building an
    Óscar> Emacs checkout too. Among those instructions, at the beginning, it is
    Óscar> said that you must start with the steps written in INSTALL.REPO in case
    Óscar> you are building a checkout.

    Óscar> It looks fine to me.

Itʼs easy to miss the referral to INSTALL.REPO at the start of
INSTALL. Would it do any harm to refer to it from README as well?

Robert
-- 

Re: Contributing to Emacs

[Óscar Fuentes]

Robert Pluim <rpluim@gmail.com> writes:

>     Óscar> You are supposed to use the instructions on INSTALL for building an
>     Óscar> Emacs checkout too. Among those instructions, at the beginning, it is
>     Óscar> said that you must start with the steps written in INSTALL.REPO in case
>     Óscar> you are building a checkout.
>
>     Óscar> It looks fine to me.
>
> Itʼs easy to miss the referral to INSTALL.REPO at the start of
> INSTALL. Would it do any harm to refer to it from README as well?

I don't think that it is easier to miss the INSTALL.REPO mention than
any other part of INSTALL, so mentioning it on README seems like
unnecessarily complicating things, moreover when you are supposed to go
to INSTALL.REPO from INSTALL, not from README.

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Friday, September 09, 2022 at 1:47 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> > Date: Thu, 8 Sep 2022 14:12:01 +0200
> > 
> > @Eli, a pleasant thing would be to mention the commands for window and frame
> > related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".
> 
> They are mentioned in the doc string of text-scale-adjust, which is
> the preferred user interface for this.

What I get is the following.  I do not see any reference for the functionality
that scales text in response to window resizing.

--------

text-scale-adjust is an autoloaded interactive byte-compiled Lisp
function in ‘face-remap.el’.

It is bound to C-x C-0, C-x C-=, C-x C--, C-x C-+.

(text-scale-adjust INC)

Adjust the height of the default face by INC.

INC may be passed as a numeric prefix argument.

The actual adjustment made depends on the final component of the
keybinding used to invoke the command, with all modifiers removed:

   +, =   Increase the height of the default face by one step
   -      Decrease the height of the default face by one step
   0      Reset the height of the default face to the global default

After adjusting, continue to read input events and further adjust
the face height as long as the input event read
(with all modifiers removed) is one of the above characters.

Each step scales the height of the default face by the variable
‘text-scale-mode-step’ (a negative number of steps decreases the
height by the same amount).  As a special case, an argument of 0
will remove any scaling currently active.

This command is a special-purpose wrapper around the
‘text-scale-increase’ command which makes repetition convenient
even when it is bound in a non-top-level keymap.  For binding in
a top-level keymap, ‘text-scale-increase’ or
‘text-scale-decrease’ may be more appropriate.

  Probably introduced at or before Emacs version 28.1.

Re: Contributing to Emacs

[Visuwesh]

[வியாழன் செப்டம்பர் 08, 2022] Christopher Dimech wrote:

>> Sent: Friday, September 09, 2022 at 1:47 AM
>> From: "Eli Zaretskii" <eliz@gnu.org>
>> To: "Christopher Dimech" <dimech@gmx.com>
>> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
>> Subject: Re: Contributing to Emacs
>>
>> > From: Christopher Dimech <dimech@gmx.com>
>> > Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
>> > Date: Thu, 8 Sep 2022 14:12:01 +0200
>> > 
>> > @Eli, a pleasant thing would be to mention the commands for window and frame
>> > related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".
>> 
>> They are mentioned in the doc string of text-scale-adjust, which is
>> the preferred user interface for this.
>
> What I get is the following.  I do not see any reference for the functionality
> that scales text in response to window resizing.

You have an old checkout?  I'm on a pretty recent HEAD and docstring of
text-scale-adjust links to global-text-scale-adjust.

    This command is a special-purpose wrapper around the
    ‘text-scale-increase’ command which makes repetition convenient
    even when it is bound in a non-top-level keymap.  For binding in
    a top-level keymap, ‘text-scale-increase’ or
    ‘text-scale-decrease’ may be more appropriate.

    Most faces are affected by these font size changes, but not faces
    that have an explicit ‘:height’ setting.  The two exceptions to
    this are the ‘default’ and ‘header-line’ faces: they will both be
    scaled even if they have an explicit ‘:height’ setting.

    See also the related command ‘global-text-scale-adjust’.

      Probably introduced at or before Emacs version 28.1.

    [back]	[forward]

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Friday, September 09, 2022 at 2:55 AM
> From: "Visuwesh" <visuweshm@gmail.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Eli Zaretskii" <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> [வியாழன் செப்டம்பர் 08, 2022] Christopher Dimech wrote:
> 
> >> Sent: Friday, September 09, 2022 at 1:47 AM
> >> From: "Eli Zaretskii" <eliz@gnu.org>
> >> To: "Christopher Dimech" <dimech@gmx.com>
> >> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> >> Subject: Re: Contributing to Emacs
> >>
> >> > From: Christopher Dimech <dimech@gmx.com>
> >> > Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> >> > Date: Thu, 8 Sep 2022 14:12:01 +0200
> >> > 
> >> > @Eli, a pleasant thing would be to mention the commands for window and frame
> >> > related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".
> >> 
> >> They are mentioned in the doc string of text-scale-adjust, which is
> >> the preferred user interface for this.
> >
> > What I get is the following.  I do not see any reference for the functionality
> > that scales text in response to window resizing.
> 
> You have an old checkout?  I'm on a pretty recent HEAD and docstring of
> text-scale-adjust links to global-text-scale-adjust.

I get emacs-28.1.91 of 5 weeks ago.
 
>     This command is a special-purpose wrapper around the
>     ‘text-scale-increase’ command which makes repetition convenient
>     even when it is bound in a non-top-level keymap.  For binding in
>     a top-level keymap, ‘text-scale-increase’ or
>     ‘text-scale-decrease’ may be more appropriate.
> 
>     Most faces are affected by these font size changes, but not faces
>     that have an explicit ‘:height’ setting.  The two exceptions to
>     this are the ‘default’ and ‘header-line’ faces: they will both be
>     scaled even if they have an explicit ‘:height’ setting.
> 
>     See also the related command ‘global-text-scale-adjust’.
> 
>       Probably introduced at or before Emacs version 28.1.
> 
>     [back]	[forward]
>

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Friday, September 09, 2022 at 1:25 AM
> From: "Robert Pluim" <rpluim@gmail.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Eli Zaretskii" <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> >>>>> On Thu, 8 Sep 2022 15:11:29 +0200, Christopher Dimech <dimech@gmx.com> said:
> 
>     >> Only when youʼre building from a git checkout, in which case you
>     >> should read INSTALL.REPO, which has that step.
>     >> 
>     >> Robert
>  
>     Christopher> @Robert.  I would then suggest to include what INSTALL and INSTALL.REPO
>     Christopher> are meant for immediately at the beginning of README.
> 
> Line 8 of README:
> 
>     The file INSTALL in this directory says how to build and install GNU
>     Emacs on various systems, once you have unpacked or checked out the
>     entire Emacs file tree.
> 
> although perhaps that 'checked out' bit should be removed or refer to
> INSTALL.REPO.
> 
> Robert

I would remove it as you suggest.

Had thought about having something like this, easy and simple.  

The file INSTALL in this directory says how to build and install GNU
Emacs on various systems, once you have downloaded an Emacs Release
file tree.

The file INSTALL.REPO in this directory says how to build and install GNU
Emacs after downloading the development sources hosted on Savannah.

Re: Contributing to Emacs

[Robert Pluim]

>>>>> On Thu, 8 Sep 2022 17:16:42 +0200, Christopher Dimech <dimech@gmx.com> said:

    >> > What I get is the following.  I do not see any reference for the functionality
    >> > that scales text in response to window resizing.
    >> 
    >> You have an old checkout?  I'm on a pretty recent HEAD and docstring of
    >> text-scale-adjust links to global-text-scale-adjust.

    Christopher> I get emacs-28.1.91 of 5 weeks ago.

Thatʼs the emacs-28 branch. The relevant code and doc changes are on
the master branch.

Robert
-- 

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Friday, September 09, 2022 at 3:24 AM
> From: "Robert Pluim" <rpluim@gmail.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Visuwesh" <visuweshm@gmail.com>, "Eli Zaretskii" <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> >>>>> On Thu, 8 Sep 2022 17:16:42 +0200, Christopher Dimech <dimech@gmx.com> said:
> 
>     >> > What I get is the following.  I do not see any reference for the functionality
>     >> > that scales text in response to window resizing.
>     >> 
>     >> You have an old checkout?  I'm on a pretty recent HEAD and docstring of
>     >> text-scale-adjust links to global-text-scale-adjust.
> 
>     Christopher> I get emacs-28.1.91 of 5 weeks ago.
> 
> Thatʼs the emacs-28 branch. The relevant code and doc changes are on
> the master branch.

Right.  Have seen that tags for the emacs-28 branch.  I wonder if there could be
a tag system as well when checking out the master branch.  It would be quite helpful
and quick to see what one has, especially when having multiple versions locally.

Re: Contributing to Emacs

[Visuwesh]

[வியாழன் செப்டம்பர் 08, 2022] Christopher Dimech wrote:

>> Sent: Friday, September 09, 2022 at 3:24 AM
>> From: "Robert Pluim" <rpluim@gmail.com>
>> To: "Christopher Dimech" <dimech@gmx.com>
>> Cc: "Visuwesh" <visuweshm@gmail.com>, "Eli Zaretskii" <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
>> Subject: Re: Contributing to Emacs
>>
>> >>>>> On Thu, 8 Sep 2022 17:16:42 +0200, Christopher Dimech <dimech@gmx.com> said:
>> 
>>     >> > What I get is the following.  I do not see any reference for the functionality
>>     >> > that scales text in response to window resizing.
>>     >> 
>>     >> You have an old checkout?  I'm on a pretty recent HEAD and docstring of
>>     >> text-scale-adjust links to global-text-scale-adjust.
>> 
>>     Christopher> I get emacs-28.1.91 of 5 weeks ago.
>> 
>> Thatʼs the emacs-28 branch. The relevant code and doc changes are on
>> the master branch.
>
> Right.  Have seen that tags for the emacs-28 branch.  I wonder if there could be
> a tag system as well when checking out the master branch.  It would be quite helpful
> and quick to see what one has, especially when having multiple versions locally.

We already have emacs-repository-version.

Re: Contributing to Emacs

[Robert Pluim]

>>>>> On Thu, 8 Sep 2022 17:34:59 +0200, Christopher Dimech <dimech@gmx.com> said:

    >> Thatʼs the emacs-28 branch. The relevant code and doc changes are on
    >> the master branch.

    Christopher> Right.  Have seen that tags for the emacs-28 branch.  I wonder if there could be
    Christopher> a tag system as well when checking out the master branch.  It would be quite helpful
    Christopher> and quick to see what one has, especially when having multiple versions locally.

What would be the point of tagging master? It never goes through any
kind of formal "it is now stable" process until a release branch is
created. And if you want to see which revision youʼre at, any variant
of

    git log -1

or the builtin `emacs-repository-version' variable will tell you.

Robert
-- 

Re: Contributing to Emacs

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: jaopaulolc@gmail.com, emacs-devel@gnu.org
> Date: Thu, 8 Sep 2022 16:49:57 +0200
> 
> > > @Eli, a pleasant thing would be to mention the commands for window and frame
> > > related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".
> > 
> > They are mentioned in the doc string of text-scale-adjust, which is
> > the preferred user interface for this.
> 
> What I get is the following.  I do not see any reference for the functionality
> that scales text in response to window resizing.

Because you are looking at the doc string in a version of Emacs where
the globalized variant of this command doesn't exist.

Re: Contributing to Emacs

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
> Date: Thu, 8 Sep 2022 17:16:42 +0200
> 
> > >> > @Eli, a pleasant thing would be to mention the commands for window and frame
> > >> > related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".
> > >> 
> > >> They are mentioned in the doc string of text-scale-adjust, which is
> > >> the preferred user interface for this.
> > >
> > > What I get is the following.  I do not see any reference for the functionality
> > > that scales text in response to window resizing.
> > 
> > You have an old checkout?  I'm on a pretty recent HEAD and docstring of
> > text-scale-adjust links to global-text-scale-adjust.
> 
> I get emacs-28.1.91 of 5 weeks ago.

You've lost context: when this started I said the feature exists on
the master branch, i.e. in Emacs 29.  You are using Emacs 28, which is
delivered from the emacs-28 branch.

Re: Contributing to Emacs

[João Paulo Labegalini de Carvalho]

[-- Attachment #1: Type: text/plain, Size: 1764 bytes --]

> That file is a bit misleading. Adding a byte-code is easy; modifying the
> compiler is more work, and so is deciding what byte-codes to add and what
> they should look like.
>
> I'd even go as far as saying that etc/TODO isn't necessarily a catalog of
> where new contributors should best direct their efforts.
>

That was what I suspected. I noticed that some items in the etc/TODO file
seem to have already been (partially) resolved (e.g. Convert modes that use
view-mode to be derived from special-mode instead).

I can see that adding a byte-code is the easy part. Modifying the compiler
is definitely a more challenging part, specially to decide when the new
byte-code should be generated.

Why don't you think of something that you personally would like Emacs to do
> that it currently does not, or doesn't do well enough? Or fix something
> that annoys you daily in your work? Such issues are never in short supply,
> and your time addressing them would be well-spent.
>

That is a very good suggestion. Currently I don't have anything that annoys
me,  the annoyances I had so far were easy to fix with existing features
and were due to my lack of Emacs knowledge.

The reason I turned to the new byte-code item was to exploit it as a way to
learn more about the inner workings of Emacs.  I guess that I did already
learn something with my modest investigation.

I will keep your suggestion in mind, and if I ever find something that
could be improved/done differently I will reach back out.

-- 
João Paulo L. de Carvalho
Ph.D Computer Science |  IC-UNICAMP | Campinas , SP - Brazil
Postdoctoral Research Fellow | University of Alberta | Edmonton, AB - Canada
joao.carvalho@ic.unicamp.br
joao.carvalho@ualberta.ca

[-- Attachment #2: Type: text/html, Size: 2502 bytes --]

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Friday, September 09, 2022 at 4:11 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: visuweshm@gmail.com, jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Cc: Eli Zaretskii <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
> > Date: Thu, 8 Sep 2022 17:16:42 +0200
> >
> > > >> > @Eli, a pleasant thing would be to mention the commands for window and frame
> > > >> > related scaling in the documentation of "text-scale-increase" and "text-scale-decrease".
> > > >>
> > > >> They are mentioned in the doc string of text-scale-adjust, which is
> > > >> the preferred user interface for this.
> > > >
> > > > What I get is the following.  I do not see any reference for the functionality
> > > > that scales text in response to window resizing.
> > >
> > > You have an old checkout?  I'm on a pretty recent HEAD and docstring of
> > > text-scale-adjust links to global-text-scale-adjust.
> >
> > I get emacs-28.1.91 of 5 weeks ago.
>
> You've lost context: when this started I said the feature exists on
> the master branch, i.e. in Emacs 29.  You are using Emacs 28, which is
> delivered from the emacs-28 branch.

Yes, Robert told me, and got the right branch now.

Re: Contributing to Emacs

[Eli Zaretskii]

> From: Mattias Engdegård <mattiase@acm.org>
> Date: Wed, 7 Sep 2022 22:32:40 +0200
> Cc: emacs-devel@gnu.org
> 
> I'd even go as far as saying that etc/TODO isn't necessarily a catalog of where new contributors should best direct their efforts.

It's supposed to be.  If you know of entries that shouldn't be there,
and entries that should but aren't, please tell.  We do want to have
this file as a useful reference of developmental tasks that are of
interest to us.

> Why don't you think of something that you personally would like Emacs to do that it currently does not, or doesn't do well enough? Or fix something that annoys you daily in your work? Such issues are never in short supply, and your time addressing them would be well-spent.

How can new contributors find such issues, when they don't know enough
about Emacs, its deficiencies, its development directions, things that
were tried and failed, etc.?  etc/TODO is supposed to guide them.

Re: Contributing to Emacs

[Christopher Dimech]

> Sent: Friday, September 09, 2022 at 3:39 AM
> From: "Robert Pluim" <rpluim@gmail.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Visuwesh" <visuweshm@gmail.com>, "Eli Zaretskii" <eliz@gnu.org>, jaopaulolc@gmail.com, emacs-devel@gnu.org
> Subject: Re: Contributing to Emacs
>
> >>>>> On Thu, 8 Sep 2022 17:34:59 +0200, Christopher Dimech <dimech@gmx.com> said:
> 
>     >> Thatʼs the emacs-28 branch. The relevant code and doc changes are on
>     >> the master branch.
> 
>     Christopher> Right.  Have seen that tags for the emacs-28 branch.  I wonder if there could be
>     Christopher> a tag system as well when checking out the master branch.  It would be quite helpful
>     Christopher> and quick to see what one has, especially when having multiple versions locally.
> 
> What would be the point of tagging master? It never goes through any
> kind of formal "it is now stable" process until a release branch is
> created. And if you want to see which revision youʼre at, any variant
> of
> 
>     git log -1
> 
> or the builtin `emacs-repository-version' variable will tell you.

It says in the README 

This directory tree holds version 29.0.50 of GNU Emacs,

So everything is fine as it is.

Re: Contributing to Emacs

[Stefan Monnier]

>  I was looking at the file etc/TODO in the repo, and some items there
> caught my attention. For example, under 'Important Features'  I found 'Add
> an "indirect goto" byte-code'. Is this still a desired feature or is it not
> required due to recent efforts towards native compilation? (In the negative
> case, please feel free to suggest another item for me to work on)

I think I was the one to add this point to etc/TODO and AFAIK the need
is pretty much still the same, yes.  Part of the idea is to handle more
efficiently code which uses local lambda expressions (like `cl-flet`).

There's a lot of scope here.  Some steps are easy but won't bring any
(or very little) benefit, which others depend on those first steps and
require much more extensive work.

> If it is still desired I would like to work on it and would appreciate
> guidance. After taking a look at lisp/emacs-lisp/bytecomp.el,it seems that
> forms such as
>
>  (let ((foo (lambda (x) bar)))
>      (dosomething
>        (funcall foo toto)
>        (blabla (funcall foo titi))))
>
> are compiled by calling byte-compile-let. Before generating the binding for
> foo, #'(lambda (x) bar) is compiled by calling
> byte-compile-push-binding-init, which in turn compiles the lambda to
> bytecode and pushes it to the stack.
>
> So to make it more concrete for my sake, I wrote the following form
>
> (let ((foo (lambda (x) (- x 1))))
>   (* (funcall foo 2)
>      (- (funcall foo 3) 2)))

Indeed, I think it might be fairly easy to handle this code more
efficiently.  Things become more ... interesting when we have code like:

    (let* ((count 0)
           (foo (lambda (x) (setq count (1+ count)) (+ x count))))
      (* (funcall foo 2)
         (- (funcall foo 3) 2)))

Where `cconv.el` turns the `count` into a one-element list and
replaces the `setq` with a `setcar`, which wouldn't be needed if we
could directly refer to the `count` var from the inner lambda using
those new byte codes.

Even more interesting would be

    (let* ((count 0)
           (foo (lambda (x) (setq count (1+ count)) (+ x count))))
      (let ((bar (funcall foo 2)))
         (- (funcall foo 3) bar)))

where the relative position of `count` on the stack is different in the
two calls to `foo`.

> and with disassemble inspected the generated bytecode by Emacs 28.1
>
> byte code:
>   args: nil
> 0       constant  <compiled-function>
>       args: (x)
>     0       varref    x
>     1       sub1
>     2       return
>
> 1       dup
> 2       varbind   foo
> 3       constant  2
> 4       call      1
> 5       varref    foo
> 6       constant  3
> 7       call      1
> 8       constant  2
> 9       diff
> 10      mult
> 11      unbind    1
> 12      return
>
> As far as I understood,  the idea of the "indirect goto" here is to
> eliminate the calls on lines 4 and 7 and replace them with an indirect
> goto.

The ones at 4 and 7 can stay as "normal" gotos but they need to pass to
the function an additional argument which is the return address, and
then the inner function would be the one which uses an indirect goto
instead of "return".

> stack* in line 0 (constant <compiled-function>). Thus, for the indirect
> goto idea to work, the bytecode of the lambda would need to be part of the
> bytecode of the let's body**. That way, a computed branch can branch into
> the lambdas code and it is possible to branch out of it when returning.

I guess in theory there could be cases where we could use a computed
goto to jump into a function, but that needs probably too many stars to
be aligned to be worth considering.  The indirect goto is needed for
"return", OTOH.

> Aside from guidance on implementing this, I would appreciate any
> pointers on how to adequately test it.

I don't think there's currently many ways to test bytecode level
operation, other than writing normal ELisp code which we expect will use
those bytecodes and make sure they behave as expected.


        Stefan

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sat, 2023-06-17 at 12:47 -0400, Alfred M. Szmidt wrote:
>    > > Increase of userbase may potentially result in new developers and
>    > > maintainers.
>    > 
>    > Our experience with NS and w32 ports indicates this is a false hope.
> 
>    To be fair, Emacs is notoriously hard to contribute to, so to have
>    new devs/maintainers appear requires substantially larger increase
>    of the userbase compared to an increase needed in other
>    projects. Still worth a try though.
> 
> Notoriously hard?  It is one of the easiest projects, you send a patch, one
> of the amazing people who work on Emacs looks over it, and if you have
> your papers in order, it is commited or commented on.  That is not
> very hard.
> 
> Best is to avoid such crazy overblown generalizations...

I see you have 4 patches to Emacs. If you do not mind, can I ask you: what other projects did you contribute to, to be able to compare the experience?

(I changed the email title as I feel this is kind of offtopic regarding Android)

Re: contributing to Emacs

[Alfred M. Szmidt]

   (I changed the email title as I feel this is kind of offtopic regarding Android)

My "qualifications" are also off-topic for emacs-devel, it is you who
needs to answer what "notoriously hard" means.  Clearly, people do not
find it as hard as you claim to.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sat, 2023-06-17 at 14:36 -0400, Alfred M. Szmidt wrote:
>    (I changed the email title as I feel this is kind of offtopic regarding
> Android)
>
> My "qualifications" are also off-topic for emacs-devel, it is you who
> needs to answer what "notoriously hard" means.  Clearly, people do not
> find it as hard as you claim to.

Okay, well. You see, in 90% of open source projects contributions work like this: you
create a branch, you add commits, you `git push` — and then if your changes weren't
registered yet for review, you'll get a link in your terminal to immediately
send them for review. Otherwise you don't do anything at all, it is already in
review, and simple push makes it available to maintainers to see.

A few projects have special requirements, like "have a Signed-off-by" line. In such
case in a few minutes you'll get an email saying your commits didn't pass CI, so you
look at it, you fix it.

Such simplicity makes contribution a complete no-brainer. I can't count how many
times I was stumbling upon something easily fixable in a project I don't even use,
(in such cases it's mostly docs improvements) and in five minutes I had changes
applied and sent for review.

This "90%" you can count as the chance that if a new developer comes, they would
expect it to be that simple. Which isn't the case for Emacs. If contributing to most
open sources projects only requires finding out their upstream URL, in Emacs case you
also need to go read HUGE "Sending patches" section. And then if that's not enough,
from what I've seen maintainers also expect you to have read CONTRIBUTE section,
which is absolutely large, much bigger than "Sending patches". (to be fair, if you
are a new contributor, you won't know it exists because "Sending patches" has no
mention of it).

This alone may eliminate a number of contributors who has no experience with
contributing via mailing lists (I think a lot of devs has no such experience, because
offhand the only widely popular projects that still use MLs are the kernel, glibc,
gcc and Emacs), and who wouldn't like to have to spend too much time figuring it out.

But some devs know how contributing via ML works. They will probably send their
patchset to bug-gnu-emacs, and… they will find out that debbugs for some reason
created a dozen bugreports for each individual patch 😄 Amazing.

But let's set aside the "newness" problem, let's imagine a developer who already has
experience, know all these problems and obstacles. Like me. Even in this case
contributing is inconvenient, because you can't "just push new revision" and be done,
you need to also send it to some URL. And then some maintainers have differing
requirements: typically in ML-managed project you just do `git send-email`, but I've
also been asked once by someone to attach patches instead, which makes situation even
more complicated. You see: these are complete no-brainer in 90% of projects. But
every time I contribute here I have to think about such stuff which is completely
irrelevant to the changes being sent.

And how do you even get a link where to send new patch revision? I have two dozens
email notifications coming to my email everyday. So I will have to search through all
that stuff.

And then, debbugs has no syntax highlight whatsoever and does not show the latest
patch revision. So studying the patch quickly in the interface is inconvenient at
best, you'd rather open it locally in Emacs (if you have the patch locally).

How do maintainers review code being sent I don't even know. I am a co-maintainer of
`color-identifiers-mode`, and we have set up CI and tests, so I immediately know a
contribution at least passes tests. But in absence of CI I guess you have to manually
check that the patch someone sent at least compiles…?

So, yes, contributing to Emacs is hard.

Re: contributing to Emacs

[Alfred M. Szmidt]

   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.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sat, 2023-06-17 at 17:00 -0400, Alfred M. Szmidt wrote:
>    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.

Well. You clearly don't want to get into discussion, because ignored most of my
points, and then you saying it's "8 relatively simple bullets" is misleading at
best. There's a lot of text, especially to someone new, especially when in other
projects you usually don't need to read anything at all. There's always CI if
something goes wrong with your contribution.

That's fine, let's not discuss it then.

Re: contributing to Emacs

[Alfred M. Szmidt]

   That's fine, let's not discuss it then.

You've not explained what is hard, you raised multiple preferences,
but not _why_.  Sending an email to emacs-devel@ with a patch, even
without following those eight bullets is not hard -- people seem to be
doing it all the time.

Your responsibility as a contributor ends as soon as you fixed
whatever issues are raised by the maintainters, and they commit the
patch.  There is no need to look at some CI machinery to know if you
screwed up -- it sorta isn't your problem.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sat, 2023-06-17 at 17:19 -0400, Alfred M. Szmidt wrote:
>    That's fine, let's not discuss it then.
> 
> You've not explained what is hard, you raised multiple preferences,
> but not _why_.  Sending an email to emacs-devel@ with a patch, even
> without following those eight bullets is not hard -- people seem to be
> doing it all the time.

Well, I don't know how, but you managed to completely miss my point. First of
all, this isn't a "preference", I enlisted actions that you *don't* do with
other projects, actions that create mental load. And then I also mentioned that
basically 90% of devs would expect such things to just work.

The reason I asked you if you ever contributed to other projects is because the
only reason you'd ask me what's the problem with development workflow here is if
you just have no other experience.

> Your responsibility as a contributor ends as soon as you fixed
> whatever issues are raised by the maintainters, and they commit the
> patch.  There is no need to look at some CI machinery to know if you
> screwed up -- it sorta isn't your problem.

Well… You are right. But then how do you expect a contributor to become a
maintainer when they see problems? 🤷‍♂️

Re: contributing to Emacs

[chad]

[-- Attachment #1: Type: text/plain, Size: 1945 bytes --]

HAving arguments on behalf of other people is an unfortunately common
conversational trap, especially in asynchronous mediums like mailing lists
and forums.

As someone who has been following emacs development and recruiting people
to help with it for multiple decades, let me say this: there is a common
(notorious) belief that contributing is difficult/complex/requiring of
confounding steps. The reality has improved a great deal over the pat ~5-6
years (due to heroic efforts of people like Eli, Lars, Stephan, Philip,
John, Chong, Stefan -- among others). At the same time, the baseline effort
required to participate in "open" development (whatever the term) has
dropped considerably, trending strongly towards the sort of "drive by
contrib" possibility that is common in many projects.

The end result is, I would have to agree, that it is still, at least
somewhat "notoriously hard to contribute to emacs". It's moving in a good
direction, but the effort surely has headroom left to fill.

There are frequent discussions on emacs-devel about new ways to address
this issue. I would caution people in this threat against getting caught in
yet another such thread, as they tend to consume a lot of oxygen, but
that's obviously up to each individual.

I hope that helps,
~Chad




On Sat, Jun 17, 2023 at 5:19 PM Alfred M. Szmidt <ams@gnu.org> wrote:

>    That's fine, let's not discuss it then.
>
> You've not explained what is hard, you raised multiple preferences,
> but not _why_.  Sending an email to emacs-devel@ with a patch, even
> without following those eight bullets is not hard -- people seem to be
> doing it all the time.
>
> Your responsibility as a contributor ends as soon as you fixed
> whatever issues are raised by the maintainters, and they commit the
> patch.  There is no need to look at some CI machinery to know if you
> screwed up -- it sorta isn't your problem.
>
>

[-- Attachment #2: Type: text/html, Size: 2428 bytes --]

Re: contributing to Emacs

[Alfred M. Szmidt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2811 bytes --]

   >    That's fine, let's not discuss it then.
   > 
   > You've not explained what is hard, you raised multiple preferences,
   > but not _why_.  Sending an email to emacs-devel@ with a patch, even
   > without following those eight bullets is not hard -- people seem to be
   > doing it all the time.

   Well, I don't know how, but you managed to completely miss my
   point. First of all, this isn't a "preference", I enlisted actions
   that you *don't* do with other projects, actions that create mental
   load. And then I also mentioned that basically 90% of devs would
   expect such things to just work.

Because you are over exaggerating the hurdle to contribute to Emacs.
You claimed that you "_need_ to go read HUGE 'Sending patches
section".  It is literally: send feature suggestions (patch or not!)
to emacs-devel@, and bugs to bug-gnu-emacs@ -- that is it.

If you plan on contributing a lot, it is quite courteous to read a few
documents like the Contributing section (or how about, Emacs Lisp
Coding Conventions?) which is not "absolutely large", it is respectful
to all to know what is expceted.  

Your message was quite far larger than both documents together
... consider that for a second.  

   The reason I asked you if you ever contributed to other projects is
   because the only reason you'd ask me what's the problem with
   development workflow here is if you just have no other experience.

Yes, plenty projects over the course of 30 years.  And the process you
outlined ("PR's") is probobly the worst -- in my experience -- you
might prefer it though.  Often leading to quite bad quality since it
is so easy to just accept anything that goes through "the test"
without any regard for what it does and how it does it.

But I wouldn't call the "PR process" hard, but it does cause a barrier
(IMHO...) for people, since they need to go through many more steps
(creating a login, an issue, branch, pr, ...) instead of just editing
a file, running C-x v = and sending the result to a list.

   > Your responsibility as a contributor ends as soon as you fixed
   > whatever issues are raised by the maintainters, and they commit
   > the patch.  There is no need to look at some CI machinery to know
   > if you screwed up -- it sorta isn't your problem.

   Well… You are right. But then how do you expect a contributor to
   become a maintainer when they see problems? 🤷‍♂️

It is unrealistic to _expect_ contributors to become maintainers.
Becoming a maintainer, specially for something complicated and large
like GNU Emacs should be hard, because it is a hard and complicated
job.

Emacs has a high bar when it comes to _standards_, and _quality_ --
but contributing is trivial.  And all the praise to the Emacs
maintainers for keeping things to high standards.

Re: contributing to Emacs

[Konstantin Kharlamov]

Okay, as mentioned elsewhere in thread, I think the problem is known and further
discussion here ain't productive. So I'm going to stop here. But to answer
something quickly verifiable:

On Sat, 2023-06-17 at 18:25 -0400, Alfred M. Szmidt wrote:
> Your message was quite far larger than both documents together
> ... consider that for a second.  

No. I measured specifically for you: "Sending Patches" alone is 5884 characters
not counting bullets, and my email was 3491 characters.

Re: contributing to Emacs

[Po Lu]

Contributing to Emacs is easy from a technical perspective.

What will make it hard, is rejecting complex new features on the basis
that they are written by only one person.  Which is a position
inconsistent with all other recent development activity anyway: Bidi
reordering and native compilation are two major features that have been
written by one person alone, and for whom we have only one expert on
board, while at least one other person in this thread has Android
development experience.

Richard, would you please look at the thread starting at
<83v8fnslfz.fsf@gnu.org>, and make a final decision?  I'm afraid that if
the Android port isn't eventually installed, there will be a fork, and I
don't have the energy to work on both the fork and Emacs at the same
time.  So it would be nice to know what to expect now.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: eliz@gnu.org, arne_bab@web.de, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 01:39:17 +0300
> 
> No. I measured specifically for you: "Sending Patches" alone is 5884 characters
> not counting bullets, and my email was 3491 characters.

When someone posts a patch, he or she is not requested to read that
section, let alone pass some kind of exam on being familiar with it.
I'm quite sure 99% of contributors don't even know that section exists
in the manual, and have never read it.  So the size of that node is
utterly irrelevant to how hard it is to contribute to Emacs.

If you are keen on studying how this is done and whether and how it
can be improved (as opposed to reiterating that "Cartage shall be
destroyed"), I invite you to read the typical discussions of such
submissions on our issue tracker.  There, you will see what we
_really_ require from the contributors and how the process goes.
Here's one recent example:

  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64126

Here's another:

  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64045

And one more:

  https://debbugs.gnu.org/cgi/bugreport.cgi?bug=63913

Yes, many other projects do it differently.  By and large, they are
toy projects whose median life time is about 1/10th that of Emacs, and
the size is accordingly small.  These quantitative differences call
for qualitatively different procedures.  Look at other large projects,
like GCC and GDB, and you will see very similar procedures.  As a
matter of fact, GDB even tried several times to move to PR-like
patch-review workflow based on several available frameworks, and each
time went back, concluding that those frameworks are lacking some
important features.  So the issue is not as clear-cut and simple as
you seem to present it, and the Emacs maintainers perhaps know what
they are doing when they stick to what we have, and not just out of
obstinance.

Re: contributing to Emacs

[Alfred M. Szmidt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 702 bytes --]

   Okay, as mentioned elsewhere in thread, I think the problem is
   known and further discussion here ain't productive. So I'm going to
   stop here. But to answer something quickly verifiable:

Several people agree that contributing to Emacs is trivial, to the
point that you do not need to read _anything_ to make a contriubution,
even a significant one.  So what problem exactly is known?

   > Your message was quite far larger than both documents together
   > ... consider that for a second.  

   No. I measured specifically for you: "Sending Patches" alone is 5884 characters
   not counting bullets, and my email was 3491 characters.

Exaggerated claims, get overblown responses.  *shurg*

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 08:20 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: eliz@gnu.org, arne_bab@web.de, luangruo@yahoo.com, emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 01:39:17 +0300
> > 
> > No. I measured specifically for you: "Sending Patches" alone is 5884
> > characters
> > not counting bullets, and my email was 3491 characters.
> 
> When someone posts a patch, he or she is not requested to read that
> section, let alone pass some kind of exam on being familiar with it.
> I'm quite sure 99% of contributors don't even know that section exists
> in the manual, and have never read it.  So the size of that node is
> utterly irrelevant to how hard it is to contribute to Emacs.

You can't send a patch if you don't know how and where to send it 😊 So you
can't avoid reading that section.

> If you are keen on studying how this is done and whether and how it
> can be improved (as opposed to reiterating that "Cartage shall be
> destroyed"), I invite you to read the typical discussions of such
> submissions on our issue tracker.  There, you will see what we
> _really_ require from the contributors and how the process goes.
> Here's one recent example:
> 
>   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64126
> 
> Here's another:
> 
>   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64045
> 
> And one more:
> 
>   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=63913

I looked through these links but I'm not sure what they supposed to show me.
I've been contributing patches from time to time and back when I had my first
ones I've been multiple times pointed to CONTRIBUTE file due to getting either
formatting or something else wrong. Which is why I'm saying there's an
expectation to read that file as well.

> Yes, many other projects do it differently.  By and large, they are
> toy projects whose median life time is about 1/10th that of Emacs, and
> the size is accordingly small.  

Mesa isn't small. Neither is systemd, docker, podman. These are very active
projects and they are in very active use today. If you go up the stack: Gnome,
KDE, they also are big active projects in use, and they use workflow similar to
Mesa and systemd. There's also WINE as another example.

> These quantitative differences call
> for qualitatively different procedures.  Look at other large projects,
> like GCC and GDB, and you will see very similar procedures.  As a
> matter of fact, GDB even tried several times to move to PR-like
> patch-review workflow based on several available frameworks, and each
> time went back, concluding that those frameworks are lacking some
> important features. 

I didn't know. Do you have a link at hand? I'd be curious to read what was the
problem. Apparently there wasn't an article on Phoronix about it, kind of sad.

>  So the issue is not as clear-cut and simple as
> you seem to present it, and the Emacs maintainers perhaps know what
> they are doing when they stick to what we have, and not just out of
> obstinance.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 04:34 -0400, Alfred M. Szmidt wrote:
>    Okay, as mentioned elsewhere in thread, I think the problem is
>    known and further discussion here ain't productive. So I'm going to
>    stop here. But to answer something quickly verifiable:
> 
> Several people agree that contributing to Emacs is trivial, to the
> point that you do not need to read _anything_ to make a contriubution,
> even a significant one.  So what problem exactly is known?
> 
>    > Your message was quite far larger than both documents together
>    > ... consider that for a second.  
> 
>    No. I measured specifically for you: "Sending Patches" alone is 5884
> characters
>    not counting bullets, and my email was 3491 characters.
> 
> Exaggerated claims, get overblown responses.  *shurg*

My claims are easily verifiable and correct. Your claim wasn't correct.

But I don't know what you're getting at here, because even if my claims were
exaggerated, replying them with a lie (because as I understand your last
sentence it wasn't a mistake, you actually okay with it being wrong just because
you think my claims are exaggerated) is non-technical at best. I don't see much
point in further discussion with you, thanks.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1764 bytes --]


Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> On Sat, 2023-06-17 at 14:36 -0400, Alfred M. Szmidt wrote:
> open sources projects only requires finding out their upstream URL,

And usually creating an account, putting SSH keys into it, and so forth …

> in Emacs case you
> also need to go read HUGE "Sending patches" section.

This sounds like a writing problem: such a section should be quick to
read. Do you have concrete ideas how to slim this down?

Maybe with some simple examples how to send the patches.

> And then if that's not enough, from what I've seen maintainers also
> expect you to have read CONTRIBUTE section, which is absolutely large,
> much bigger than "Sending patches". (to be fair, if you are a new
> contributor, you won't know it exists because "Sending patches" has no
> mention of it).

Same here. I see quite a bit of explanation in the CONTRIBUTE file that
makes that longer than the information a contributor really has to know.

> more complicated. You see: these are complete no-brainer in 90% of projects. But
> every time I contribute here I have to think about such stuff which is completely
> irrelevant to the changes being sent.
> And how do you even get a link where to send new patch revision? I have two dozens
> email notifications coming to my email everyday. So I will have to search through all
> that stuff.

Can this be improved with changes to debbug emails sent? Or to the
debbug web interface?

For a github project (to name the elefant in the room) you also have to
know the URL, but there it feels easier. Can we make that easier in the
existing infrastructure?

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> You can't send a patch if you don't know how and where to send it 😊
> So you can't avoid reading that section.

I cannot help but wonder how a person who is unable to read several
short paragraphs of text would have learned the programming languages in
which Emacs is written.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: ams@gnu.org, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 11:53:09 +0300
> 
> On Sun, 2023-06-18 at 08:20 +0300, Eli Zaretskii wrote:
> > 
> > When someone posts a patch, he or she is not requested to read that
> > section, let alone pass some kind of exam on being familiar with it.
> > I'm quite sure 99% of contributors don't even know that section exists
> > in the manual, and have never read it.  So the size of that node is
> > utterly irrelevant to how hard it is to contribute to Emacs.
> 
> You can't send a patch if you don't know how and where to send it 😊 So you
> can't avoid reading that section.

False.  People know how to reach us even without reading.  The few
Emacs mailing lists are common knowledge, and are just an Internet
search away if someone needs that.

> > If you are keen on studying how this is done and whether and how it
> > can be improved (as opposed to reiterating that "Cartage shall be
> > destroyed"), I invite you to read the typical discussions of such
> > submissions on our issue tracker.  There, you will see what we
> > _really_ require from the contributors and how the process goes.
> > Here's one recent example:
> > 
> >   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64126
> > 
> > Here's another:
> > 
> >   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64045
> > 
> > And one more:
> > 
> >   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=63913
> 
> I looked through these links but I'm not sure what they supposed to show me.

How patch submitting process works in reality.

> I've been contributing patches from time to time and back when I had my first
> ones I've been multiple times pointed to CONTRIBUTE file due to getting either
> formatting or something else wrong. Which is why I'm saying there's an
> expectation to read that file as well.

There's no such expectation.  We live in the real world, not in some
fantasy.  When the patch doesn't follow our conventions, we either
correct that by hand when installing it or (if the deviations are too
significant) ask the contributor to make those changes and resubmit.

> > Yes, many other projects do it differently.  By and large, they are
> > toy projects whose median life time is about 1/10th that of Emacs, and
> > the size is accordingly small.  
> 
> Mesa isn't small. Neither is systemd, docker, podman.

I said "by and large".

> > These quantitative differences call
> > for qualitatively different procedures.  Look at other large projects,
> > like GCC and GDB, and you will see very similar procedures.  As a
> > matter of fact, GDB even tried several times to move to PR-like
> > patch-review workflow based on several available frameworks, and each
> > time went back, concluding that those frameworks are lacking some
> > important features. 
> 
> I didn't know. Do you have a link at hand? I'd be curious to read what was the
> problem. Apparently there wasn't an article on Phoronix about it, kind of sad.

I don't have a link, you will have to search the archives of the GDB
list.

Re: contributing to Emacs

[Eli Zaretskii]

> Date: Sun, 18 Jun 2023 12:01:41 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: ams@gnu.org, emacs-devel@gnu.org
> 
> > You can't send a patch if you don't know how and where to send it 😊 So you
> > can't avoid reading that section.
> 
> False.  People know how to reach us even without reading.  The few
> Emacs mailing lists are common knowledge, and are just an Internet
> search away if someone needs that.

To say nothing of the fact that "Send Bug Report" is right there on
the Help menu.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 12:01 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: ams@gnu.org, emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 11:53:09 +0300
> > 
> > On Sun, 2023-06-18 at 08:20 +0300, Eli Zaretskii wrote:
> > > 
> > > When someone posts a patch, he or she is not requested to read that
> > > section, let alone pass some kind of exam on being familiar with it.
> > > I'm quite sure 99% of contributors don't even know that section exists
> > > in the manual, and have never read it.  So the size of that node is
> > > utterly irrelevant to how hard it is to contribute to Emacs.
> > 
> > You can't send a patch if you don't know how and where to send it 😊 So you
> > can't avoid reading that section.
> 
> False.  People know how to reach us even without reading.  The few
> Emacs mailing lists are common knowledge, and are just an Internet
> search away if someone needs that.

Okay, let's conduct an experiment. Suppose I am a new contributor who never
contributed via MLs. So first I search for "Emacs contribute". I get this URL
https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
There I see a suggestion to implement a new feature and submit a patch. So then
I use page search for word "patch" to see where are details on how to do that. I
find a link "Sending Patches". There I find a suggestion to send it to
bugtracker, and then various points about MIME types, what needs to be done,
etc.

In what case do you imagine such new developer would not need to read that
section and still will successfully send a patch? 🤷‍♂️

> > > If you are keen on studying how this is done and whether and how it
> > > can be improved (as opposed to reiterating that "Cartage shall be
> > > destroyed"), I invite you to read the typical discussions of such
> > > submissions on our issue tracker.  There, you will see what we
> > > _really_ require from the contributors and how the process goes.
> > > Here's one recent example:
> > > 
> > >   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64126
> > > 
> > > Here's another:
> > > 
> > >   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=64045
> > > 
> > > And one more:
> > > 
> > >   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=63913
> > 
> > I looked through these links but I'm not sure what they supposed to show me.
> 
> How patch submitting process works in reality.

I know how it works, I've been contributing to Emacs. Which is why I'm not sure
what was I supposed to see there. I looked at the links and it seems to be
pretty usual.

> > I've been contributing patches from time to time and back when I had my
> > first
> > ones I've been multiple times pointed to CONTRIBUTE file due to getting
> > either
> > formatting or something else wrong. Which is why I'm saying there's an
> > expectation to read that file as well.
> 
> There's no such expectation.  We live in the real world, not in some
> fantasy.  When the patch doesn't follow our conventions, we either
> correct that by hand when installing it or (if the deviations are too
> significant) ask the contributor to make those changes and resubmit.

Okay, maybe something changed. I am saying from my experience of contributing
patches.

> > > Yes, many other projects do it differently.  By and large, they are
> > > toy projects whose median life time is about 1/10th that of Emacs, and
> > > the size is accordingly small.  
> > 
> > Mesa isn't small. Neither is systemd, docker, podman.
> 
> I said "by and large".

Well, in this case I might be missing what you meant to say. You pointed out
there are small projects with different workflow, I pointed out there are large
ones. So I guess that cancels out. If that was meant to present some point to
me, I'm not seeing it.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 12:06 +0300, Eli Zaretskii wrote:
> > Date: Sun, 18 Jun 2023 12:01:41 +0300
> > From: Eli Zaretskii <eliz@gnu.org>
> > Cc: ams@gnu.org, emacs-devel@gnu.org
> > 
> > > You can't send a patch if you don't know how and where to send it 😊 So
> > > you
> > > can't avoid reading that section.
> > 
> > False.  People know how to reach us even without reading.  The few
> > Emacs mailing lists are common knowledge, and are just an Internet
> > search away if someone needs that.
> 
> To say nothing of the fact that "Send Bug Report" is right there on
> the Help menu.

It's not really relevant. Emacs is the unique project that tracks patches in the
bugtracker, so if you don't know yet that bugtracker is used to send a patch,
the only reason you'd use it if you didn't manage to find "sending patches"
section and decided to report a bug about the lack of docs (which would be of
course invalid, but that's not the point).

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 17:01 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > You can't send a patch if you don't know how and where to send it 😊
> > So you can't avoid reading that section.
> 
> I cannot help but wonder how a person who is unable to read several
> short paragraphs of text would have learned the programming languages in
> which Emacs is written.

The point is not (in)ability to read. The point is the additional mental load
from the many additional actions that are needed to contribute.

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> The point is not (in)ability to read. The point is the additional
> mental load from the many additional actions that are needed to
> contribute.

That effort is minimal, compared to the effort it takes to write the
code.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 3432 bytes --]


"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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 10:59 +0200, Dr. Arne Babenhauserheide wrote:
> 
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > On Sat, 2023-06-17 at 14:36 -0400, Alfred M. Szmidt wrote:
> > open sources projects only requires finding out their upstream URL,
> 
> And usually creating an account, putting SSH keys into it, and so forth …
> 
> > in Emacs case you
> > also need to go read HUGE "Sending patches" section.
> 
> This sounds like a writing problem: such a section should be quick to
> read. Do you have concrete ideas how to slim this down?
> 
> Maybe with some simple examples how to send the patches.

Well… Yes. I see that the section "Sending Patches" is actually mixed up also
with the information about what changes should be contained in it. It is a
useful information, but I think it could be great if that was *on the same page*
but *in a separate paragraph*. This would allow a person to immediately know
which part is related to just "how to send a patch" and which is about the
commit message and stuff like that.

I can send the changes if there's any interest.

> > And then if that's not enough, from what I've seen maintainers also
> > expect you to have read CONTRIBUTE section, which is absolutely large,
> > much bigger than "Sending patches". (to be fair, if you are a new
> > contributor, you won't know it exists because "Sending patches" has no
> > mention of it).
> 
> Same here. I see quite a bit of explanation in the CONTRIBUTE file that
> makes that longer than the information a contributor really has to know.

Eli said elsewhere that reading this file isn't required, so whatever. The
"Sending Patches" section does not refer to it anyway.

> > more complicated. You see: these are complete no-brainer in 90% of projects.
> > But
> > every time I contribute here I have to think about such stuff which is
> > completely
> > irrelevant to the changes being sent.
> > And how do you even get a link where to send new patch revision? I have two
> > dozens
> > email notifications coming to my email everyday. So I will have to search
> > through all
> > that stuff.
> 
> Can this be improved with changes to debbug emails sent? Or to the
> debbug web interface?
> 
> For a github project (to name the elefant in the room) you also have to
> know the URL, but there it feels easier. Can we make that easier in the
> existing infrastructure?

I will need to think about that, but I would guess there should be ways.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 12:30 +0300, Konstantin Kharlamov wrote:
> Well… Yes. I see that the section "Sending Patches" is actually mixed up also
> with the information about what changes should be contained in it. It is a
> useful information, but I think it could be great if that was *on the same
> page* but *in a separate paragraph*. 

Sorry, I mean to say "with a separate heading". In my language "paragraph" has a
bit different meaning, I meant as in, having a separate title on the same page.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: ams@gnu.org, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 12:18:09 +0300
> 
> > > You can't send a patch if you don't know how and where to send it 😊 So you
> > > can't avoid reading that section.
> > 
> > False.  People know how to reach us even without reading.  The few
> > Emacs mailing lists are common knowledge, and are just an Internet
> > search away if someone needs that.
> 
> Okay, let's conduct an experiment. Suppose I am a new contributor who never
> contributed via MLs. So first I search for "Emacs contribute". I get this URL
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
> There I see a suggestion to implement a new feature and submit a patch. So then
> I use page search for word "patch" to see where are details on how to do that. I
> find a link "Sending Patches". There I find a suggestion to send it to
> bugtracker, and then various points about MIME types, what needs to be done,
> etc.
> 
> In what case do you imagine such new developer would not need to read that
> section and still will successfully send a patch? 🤷‍♂️

All of them.  I never had anyone asking where to send a patch.  People
sometimes say they are not sure whether they send them to a correct
forum, but they do send them to the right place nonetheless.

> > > I've been contributing patches from time to time and back when I had my
> > > first
> > > ones I've been multiple times pointed to CONTRIBUTE file due to getting
> > > either
> > > formatting or something else wrong. Which is why I'm saying there's an
> > > expectation to read that file as well.
> > 
> > There's no such expectation.  We live in the real world, not in some
> > fantasy.  When the patch doesn't follow our conventions, we either
> > correct that by hand when installing it or (if the deviations are too
> > significant) ask the contributor to make those changes and resubmit.
> 
> Okay, maybe something changed. I am saying from my experience of contributing
> patches.

AFAIR, you insisted to know, for each comment during the patch review,
where is that requirement documented.  So you were pointed to those
places.  You could have simply done what you were asked, in which case
you wouldn't need to read on that.

> > > > Yes, many other projects do it differently.  By and large, they are
> > > > toy projects whose median life time is about 1/10th that of Emacs, and
> > > > the size is accordingly small.  
> > > 
> > > Mesa isn't small. Neither is systemd, docker, podman.
> > 
> > I said "by and large".
> 
> Well, in this case I might be missing what you meant to say. You pointed out
> there are small projects with different workflow, I pointed out there are large
> ones.

Your large ones are still smaller than Emacs by a factor of 3.  You
also forgot the point about the age of each project.

> So I guess that cancels out.

It doesn't.  Your argument was about 90% of projects, and my response
about most of them being small was about that majority.  Showing a few
examples that are in the same order of magnitude as Emacs doesn't
substantiate your claim, which basically is: it's easy and obvious
that Emacs should switch, but a few old-timers block that for
laughable reasons.

Re: contributing to Emacs

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org, luangruo@yahoo.com,
>  emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 10:59:42 +0200
> 
> > And then if that's not enough, from what I've seen maintainers also
> > expect you to have read CONTRIBUTE section, which is absolutely large,
> > much bigger than "Sending patches". (to be fair, if you are a new
> > contributor, you won't know it exists because "Sending patches" has no
> > mention of it).
> 
> Same here. I see quite a bit of explanation in the CONTRIBUTE file that
> makes that longer than the information a contributor really has to know.

People keep asking for more and more details to be described there, so
what you expect doesn't stand the test of time and user expectations.

It is clear that you personally may not need everything there, but
CONTRIBUTE is not for you and me, or others like we.

> For a github project (to name the elefant in the room) you also have to
> know the URL, but there it feels easier. Can we make that easier in the
> existing infrastructure?

Type "gnu emacs" into an Internet search window.  The first result
will likely to be the Emacs site.  Click on "Documentation & Support"
and read there.  How hard is that?

Are we perhaps making a mountain out of a proverbial molehill?

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 12:30 +0300, Konstantin Kharlamov wrote:
> On Sun, 2023-06-18 at 10:59 +0200, Dr. Arne Babenhauserheide wrote:
> > 
> > Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> > > more complicated. You see: these are complete no-brainer in 90% of
> > > projects.
> > > But
> > > every time I contribute here I have to think about such stuff which is
> > > completely
> > > irrelevant to the changes being sent.
> > > And how do you even get a link where to send new patch revision? I have
> > > two
> > > dozens
> > > email notifications coming to my email everyday. So I will have to search
> > > through all
> > > that stuff.
> > 
> > Can this be improved with changes to debbug emails sent? Or to the
> > debbug web interface?
> > 
> > For a github project (to name the elefant in the room) you also have to
> > know the URL, but there it feels easier. Can we make that easier in the
> > existing infrastructure?
> 
> I will need to think about that, but I would guess there should be ways.

Okay, so, here's an obvious one: a patch series sent to bug-gnu-emacs@gnu.org
should not create separate bugreports for every patch.

In ML-managed projects it is typical to send patches as a series, and when you
doing that results in such surprising behaviour, it creates an additional
emotional and mental load both for you and for maintainers who would need to do
something with these separate reports.

Re: contributing to Emacs

[Alfred M. Szmidt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 1116 bytes --]

   > > You can't send a patch if you don't know how and where to send it 😊
   > > So you can't avoid reading that section.
   > 
   > I cannot help but wonder how a person who is unable to read several
   > short paragraphs of text would have learned the programming languages in
   > which Emacs is written.

   The point is not (in)ability to read. The point is the additional mental load
   from the many additional actions that are needed to contribute.

What about the mental load of the maintainers?  Those chapers exist
for a reason, to make life easier for both contributors and
maintainers so that there is a well documented, agreed upon, standard
to follow.

And you're not even required to read them, the only action you have is
to send a patch -- if even that, since there are plenty of times when
someone sends a suggestion and the maintainers or someone else
implement the feature!  There are literally no additional actions.

Emacs is a luxurious project in that regard, and the little nod once
in a while to read one or two chapters is the least we can do to thank
those that do the daily work.

Re: contributing to Emacs

[Philip Kaludercic]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> On Sun, 2023-06-18 at 08:20 +0300, Eli Zaretskii wrote:
>> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
>> > Cc: eliz@gnu.org, arne_bab@web.de, luangruo@yahoo.com, emacs-devel@gnu.org
>> > Date: Sun, 18 Jun 2023 01:39:17 +0300
>> > 
>> > No. I measured specifically for you: "Sending Patches" alone is 5884
>> > characters
>> > not counting bullets, and my email was 3491 characters.
>> 
>> When someone posts a patch, he or she is not requested to read that
>> section, let alone pass some kind of exam on being familiar with it.
>> I'm quite sure 99% of contributors don't even know that section exists
>> in the manual, and have never read it.  So the size of that node is
>> utterly irrelevant to how hard it is to contribute to Emacs.
>
> You can't send a patch if you don't know how and where to send it 😊 So you
> can't avoid reading that section.

I think `submit-emacs-patch' is supposed to help here.  But I don't get
how this is a Emacs/ML specific issue?

-- 
Philip Kaludercic

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org, luangruo@yahoo.com, 
> 	emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 12:56:33 +0300
> 
> Okay, so, here's an obvious one: a patch series sent to bug-gnu-emacs@gnu.org
> should not create separate bugreports for every patch.
> 
> In ML-managed projects it is typical to send patches as a series, and when you
> doing that results in such surprising behaviour, it creates an additional
> emotional and mental load both for you and for maintainers who would need to do
> something with these separate reports.

Our preference is to send patches as a single patch, not as patch
series.

That said, people are sometimes sending series, and we don't ask them
to resend, we process those series anyway.

As for separate bug reports, this is easily fixed by merging them.

So I see no problem here.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 17:25 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > The point is not (in)ability to read. The point is the additional
> > mental load from the many additional actions that are needed to
> > contribute.
> 
> That effort is minimal, compared to the effort it takes to write the
> code.

These two are uncomparable. The "effort to write the code" is something people
often feel joy in doing. Whereas effort related to pushing your changes upstream
is just something necessary. You need to go through it, but it's usually not
something people enjoy doing.

And to make sure we're on the same page: note that I do not say "sending
patches" section alone is problematic (also below there's a discussion on
possible improvement to it), my point is there lots of such "unnecessary stuff",
which accumulates.

Re: contributing to Emacs

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: Konstantin Kharlamov <hi-angel@yandex.ru>, eliz@gnu.org,
>  luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 11:26:37 +0200
> 
> 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

This refers to other places, so if the reader needs to read them, the
gain is largely an illusory one: you must read those referenced places
as well.

Summary is only useful in cases like this if the details are
non-essential.  If they _are_ essential, a summary with references
doesn't make the reading simpler or shorter.

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> And to make sure we're on the same page: note that I do not say
> "sending patches" section alone is problematic (also below there's a
> discussion on possible improvement to it), my point is there lots of
> such "unnecessary stuff", which accumulates.

And that includes?

I'm sorry, but I haven't had the time to read through this discussion,
which also happens to be a tangent wrt the original topic of the thread.
Please forgive me if you have to repeat yourself.

Thanks.

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> Okay, so, here's an obvious one: a patch series sent to bug-gnu-emacs@gnu.org
> should not create separate bugreports for every patch.
>
> In ML-managed projects it is typical to send patches as a series, and when you
> doing that results in such surprising behaviour, it creates an additional
> emotional and mental load both for you and for maintainers who would need to do
> something with these separate reports.

What's a ``patch series''?

Typically, free software maintainers expect patches to be a single
context format diff, containing either edits to the appropriate
ChangeLog file(s), or with ChangeLog entries prepended.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 13:02 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org, luangruo@yahoo.com, 
> >         emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 12:56:33 +0300
> > 
> > Okay, so, here's an obvious one: a patch series sent to
> > bug-gnu-emacs@gnu.org
> > should not create separate bugreports for every patch.
> > 
> > In ML-managed projects it is typical to send patches as a series, and when
> > you
> > doing that results in such surprising behaviour, it creates an additional
> > emotional and mental load both for you and for maintainers who would need to
> > do
> > something with these separate reports.
> 
> Our preference is to send patches as a single patch, not as patch
> series.
> 
> That said, people are sometimes sending series, and we don't ask them
> to resend, we process those series anyway.
> 
> As for separate bug reports, this is easily fixed by merging them.

Unfortunately merging bugreports does not fix that. The last patch I had to
Emacs was sent with a cover letter and resulted in two reports: one for the
cover letter and another for the patch itself. You may remember that it resulted
in a confusion, because α) discussions happened on both threads, but then a new
patch version was only sent to one of them, so there other thread wasn't
notified that comments were addressed, and β) you may remember 3 months after
the patch got accepted someone was asking the status. Which is because one of
the threads was closed saying that the patch is applied, but then the other
thread into which a person was looking has no such comment.

> So I see no problem here.

This is psychology. Having a report per patch may not be a problem for you, but
when a contributor sends patches and gets into such situation, they do not know
it is okay. They will be frightened and frustrated, because it looks like
something just went wrong. Such situation being okay needs at least be mentioned
in "sending patches" section, and at best it should just work.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 10:00 +0000, Philip Kaludercic wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > On Sun, 2023-06-18 at 08:20 +0300, Eli Zaretskii wrote:
> > > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > > > Cc: eliz@gnu.org, arne_bab@web.de, luangruo@yahoo.com,
> > > > emacs-devel@gnu.org
> > > > Date: Sun, 18 Jun 2023 01:39:17 +0300
> > > > 
> > > > No. I measured specifically for you: "Sending Patches" alone is 5884
> > > > characters
> > > > not counting bullets, and my email was 3491 characters.
> > > 
> > > When someone posts a patch, he or she is not requested to read that
> > > section, let alone pass some kind of exam on being familiar with it.
> > > I'm quite sure 99% of contributors don't even know that section exists
> > > in the manual, and have never read it.  So the size of that node is
> > > utterly irrelevant to how hard it is to contribute to Emacs.
> > 
> > You can't send a patch if you don't know how and where to send it 😊 So you
> > can't avoid reading that section.
> 
> I think `submit-emacs-patch' is supposed to help here. 

You would need to know it exists.

>  But I don't get how this is a Emacs/ML specific issue?

We are discussing possible improvement to Emacs-specific contributing workflow.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1903 bytes --]


Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
>> Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org, luangruo@yahoo.com,
>>  emacs-devel@gnu.org
>> Date: Sun, 18 Jun 2023 10:59:42 +0200
>> 
>> > And then if that's not enough, from what I've seen maintainers also
>> > expect you to have read CONTRIBUTE section, which is absolutely large,
>> > much bigger than "Sending patches". (to be fair, if you are a new
>> > contributor, you won't know it exists because "Sending patches" has no
>> > mention of it).
>> 
>> Same here. I see quite a bit of explanation in the CONTRIBUTE file that
>> makes that longer than the information a contributor really has to know.
>
> People keep asking for more and more details to be described there, so
> what you expect doesn't stand the test of time and user expectations.

What would you do if CONTRIBUTING were a user interface? Would you
include every idea someone has?

> It is clear that you personally may not need everything there, but
> CONTRIBUTE is not for you and me, or others like we.

For whom *is* CONTRIBUTE?

>> For a github project (to name the elefant in the room) you also have to
>> know the URL, but there it feels easier. Can we make that easier in the
>> existing infrastructure?
>
> Type "gnu emacs" into an Internet search window.  The first result
> will likely to be the Emacs site.  Click on "Documentation & Support"
> and read there.  How hard is that?
>
> Are we perhaps making a mountain out of a proverbial molehill?

I don’t think so. I consider this a writing problem. But do see my other
email with a concrete description and proposal how to package the
information needed for contributing in a way that makes it much easier
to take in.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Philip Kaludercic]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> On Sun, 2023-06-18 at 10:00 +0000, Philip Kaludercic wrote:
>> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
>> 
>> > On Sun, 2023-06-18 at 08:20 +0300, Eli Zaretskii wrote:
>> > > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
>> > > > Cc: eliz@gnu.org, arne_bab@web.de, luangruo@yahoo.com,
>> > > > emacs-devel@gnu.org
>> > > > Date: Sun, 18 Jun 2023 01:39:17 +0300
>> > > > 
>> > > > No. I measured specifically for you: "Sending Patches" alone is 5884
>> > > > characters
>> > > > not counting bullets, and my email was 3491 characters.
>> > > 
>> > > When someone posts a patch, he or she is not requested to read that
>> > > section, let alone pass some kind of exam on being familiar with it.
>> > > I'm quite sure 99% of contributors don't even know that section exists
>> > > in the manual, and have never read it.  So the size of that node is
>> > > utterly irrelevant to how hard it is to contribute to Emacs.
>> > 
>> > You can't send a patch if you don't know how and where to send it 😊 So you
>> > can't avoid reading that section.
>> 
>> I think `submit-emacs-patch' is supposed to help here. 
>
> You would need to know it exists.

True, but that can be fixed.

>>  But I don't get how this is a Emacs/ML specific issue?
>
> We are discussing possible improvement to Emacs-specific contributing workflow.

My point is that this is an issue that all projects have in some sense
or another.  You always have to find out how they work, and what you
need to do to submit a patch.

One idea (but I don't know if this is practicable), is to use the
configure script to set up Git's `sendemail.to' option or to add
`vc-default-patch-addressee' to .dir-locals.el.

-- 
Philip Kaludercic

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 13:13:23 +0300
> 
> On Sun, 2023-06-18 at 13:02 +0300, Eli Zaretskii wrote:
> > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > > Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org, luangruo@yahoo.com, 
> > >         emacs-devel@gnu.org
> > > Date: Sun, 18 Jun 2023 12:56:33 +0300
> > > 
> > > Okay, so, here's an obvious one: a patch series sent to
> > > bug-gnu-emacs@gnu.org
> > > should not create separate bugreports for every patch.
> > > 
> > > In ML-managed projects it is typical to send patches as a series, and when
> > > you
> > > doing that results in such surprising behaviour, it creates an additional
> > > emotional and mental load both for you and for maintainers who would need to
> > > do
> > > something with these separate reports.
> > 
> > Our preference is to send patches as a single patch, not as patch
> > series.
> > 
> > That said, people are sometimes sending series, and we don't ask them
> > to resend, we process those series anyway.
> > 
> > As for separate bug reports, this is easily fixed by merging them.
> 
> Unfortunately merging bugreports does not fix that. The last patch I had to
> Emacs was sent with a cover letter and resulted in two reports: one for the
> cover letter and another for the patch itself. You may remember that it resulted
> in a confusion, because α) discussions happened on both threads, but then a new
> patch version was only sent to one of them, so there other thread wasn't
> notified that comments were addressed, and β) you may remember 3 months after
> the patch got accepted someone was asking the status. Which is because one of
> the threads was closed saying that the patch is applied, but then the other
> thread into which a person was looking has no such comment.
> 
> > So I see no problem here.
> 
> This is psychology. Having a report per patch may not be a problem for you, but
> when a contributor sends patches and gets into such situation, they do not know
> it is okay. They will be frightened and frustrated, because it looks like
> something just went wrong. Such situation being okay needs at least be mentioned
> in "sending patches" section, and at best it should just work.

Like I said: we prefer a single patch for each changeset.  The
problems presented by patch series are one reason.  And yet, we will
never reject a patch series, even though it makes the process
inconvenient and confusing.

I don't see what else do we need to argued about here.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 18:12 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > Okay, so, here's an obvious one: a patch series sent to
> > bug-gnu-emacs@gnu.org
> > should not create separate bugreports for every patch.
> > 
> > In ML-managed projects it is typical to send patches as a series, and when
> > you
> > doing that results in such surprising behaviour, it creates an additional
> > emotional and mental load both for you and for maintainers who would need to
> > do
> > something with these separate reports.
> 
> What's a ``patch series''?
> 
> Typically, free software maintainers expect patches to be a single
> context format diff, containing either edits to the appropriate
> ChangeLog file(s), or with ChangeLog entries prepended.

Ideally, each commit in the repository should contain minimal functional
changes. It allows for easier code review at the moment and for better figuring
out why some change was done later in the life of the project. Usually at this
point I refer people to this old article from kernel HID subsystem maintainer
and libinput creator http://who-t.blogspot.com/2009/12/on-commit-messages.html
Old — but gold! 😄

When project contributions are done via mailing list (such as kernel, gdb, gcc,
and in the past were also Xorg and Mesa), you usually turn a number of commits
to separate patches and send them. E.g. here's one example:
https://lore.kernel.org/dri-devel/20230612104658.1386996-1-tvrtko.ursulin@linux.intel.com/
it starts with a "zero patch" that is the title of the series, and then
individual patches follow.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 13:22 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 13:13:23 +0300
> > 
> > On Sun, 2023-06-18 at 13:02 +0300, Eli Zaretskii wrote:
> > > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > > > Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org, luangruo@yahoo.com, 
> > > >         emacs-devel@gnu.org
> > > > Date: Sun, 18 Jun 2023 12:56:33 +0300
> > > > 
> > > > Okay, so, here's an obvious one: a patch series sent to
> > > > bug-gnu-emacs@gnu.org
> > > > should not create separate bugreports for every patch.
> > > > 
> > > > In ML-managed projects it is typical to send patches as a series, and
> > > > when
> > > > you
> > > > doing that results in such surprising behaviour, it creates an
> > > > additional
> > > > emotional and mental load both for you and for maintainers who would
> > > > need to
> > > > do
> > > > something with these separate reports.
> > > 
> > > Our preference is to send patches as a single patch, not as patch
> > > series.
> > > 
> > > That said, people are sometimes sending series, and we don't ask them
> > > to resend, we process those series anyway.
> > > 
> > > As for separate bug reports, this is easily fixed by merging them.
> > 
> > Unfortunately merging bugreports does not fix that. The last patch I had to
> > Emacs was sent with a cover letter and resulted in two reports: one for the
> > cover letter and another for the patch itself. You may remember that it
> > resulted
> > in a confusion, because α) discussions happened on both threads, but then a
> > new
> > patch version was only sent to one of them, so there other thread wasn't
> > notified that comments were addressed, and β) you may remember 3 months
> > after
> > the patch got accepted someone was asking the status. Which is because one
> > of
> > the threads was closed saying that the patch is applied, but then the other
> > thread into which a person was looking has no such comment.
> > 
> > > So I see no problem here.
> > 
> > This is psychology. Having a report per patch may not be a problem for you,
> > but
> > when a contributor sends patches and gets into such situation, they do not
> > know
> > it is okay. They will be frightened and frustrated, because it looks like
> > something just went wrong. Such situation being okay needs at least be
> > mentioned
> > in "sending patches" section, and at best it should just work.
> 
> Like I said: we prefer a single patch for each changeset.  The
> problems presented by patch series are one reason.  And yet, we will
> never reject a patch series, even though it makes the process
> inconvenient and confusing.
> 
> I don't see what else do we need to argued about here.

Well, you see, the "sending patches" section has no mention that a series is
unwelcome. And Emacs is the unique project where a squashed patch with many
commits is preferred over a series.

If series is indeed unwelcome, it would be better to reflect in "sending
patches" section and provide copy-paste instructions for the people to quickly
squash their commits before sending to ML (and I think something needs to be
figured out about commit messages too in this case). Because when you are
developing, it is easier to separate changes to distinct commits to make sure
that if something break you know what exactly change was the reason to it. Even
if these commits will have to be squashed later.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 938 bytes --]


Eli Zaretskii <eliz@gnu.org> writes:

>> For more details, please read at
>> https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html
>
> This refers to other places, so if the reader needs to read them, the
> gain is largely an illusory one: you must read those referenced places
> as well.

You don’t have to read those places. I took care to ensure that all the
essential parts for contributing a patch are in my shorter version.

The reference to other places is there for people who think they have
special requirements or want to understand *why* the rules are as they
are.

Maybe the text should make that clear, so this should not be "for more
details", but "for explanations of these rules, please read
https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html"

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: hi-angel@yandex.ru, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 12:19:45 +0200
> 
> > People keep asking for more and more details to be described there, so
> > what you expect doesn't stand the test of time and user expectations.
> 
> What would you do if CONTRIBUTING were a user interface? Would you
> include every idea someone has?

Who said anything about including "every idea"?  We try very hard to
include there only what's really necessary and non-obvious, you can
search the archives for discussions about CONTRIBUTE to see it for
yourself.  But still, the instructions grow over time, because people
ask questions about the details, and enough people here consider some
of those details worthy to be included.

> > It is clear that you personally may not need everything there, but
> > CONTRIBUTE is not for you and me, or others like we.
> 
> For whom *is* CONTRIBUTE?

For people who only start contributing and need to study our
conventions and requirements.  If they bother reading the file, of
course.  (If they don't, we will inform them about the relevant
conventions as part of the patch review process.)

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 13:27:47 +0300
> 
> > Like I said: we prefer a single patch for each changeset.  The
> > problems presented by patch series are one reason.  And yet, we will
> > never reject a patch series, even though it makes the process
> > inconvenient and confusing.
> > 
> > I don't see what else do we need to argued about here.
> 
> Well, you see, the "sending patches" section has no mention that a series is
> unwelcome.

They aren't "unwelcome", please don't misquote what I write.

> If series is indeed unwelcome, it would be better to reflect in "sending
> patches" section and provide copy-paste instructions for the people to quickly
> squash their commits before sending to ML (and I think something needs to be
> figured out about commit messages too in this case). Because when you are
> developing, it is easier to separate changes to distinct commits to make sure
> that if something break you know what exactly change was the reason to it. Even
> if these commits will have to be squashed later.

It sounds like you have just asked us to make that section larger, is
that right?

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 13:36 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 13:27:47 +0300
> > 
> > > Like I said: we prefer a single patch for each changeset.  The
> > > problems presented by patch series are one reason.  And yet, we will
> > > never reject a patch series, even though it makes the process
> > > inconvenient and confusing.
> > > 
> > > I don't see what else do we need to argued about here.
> > 
> > Well, you see, the "sending patches" section has no mention that a series is
> > unwelcome.
> 
> They aren't "unwelcome", please don't misquote what I write.

Hmm, I feel like there's some confusion. You said that a single patch is
preferred over a series, right? And then you said it is the reason we don't need
to do anything about the problem with sending a series to bug-gnu-emacs@gnu.org

But the problem exists, so I'm suggesting that if you don't want it to be fixed,
perhaps we should put some docs about that.

If you say a series is not "unwelcome", then this documentation should simply
mention the problem.

> > If series is indeed unwelcome, it would be better to reflect in "sending
> > patches" section and provide copy-paste instructions for the people to
> > quickly
> > squash their commits before sending to ML (and I think something needs to be
> > figured out about commit messages too in this case). Because when you are
> > developing, it is easier to separate changes to distinct commits to make
> > sure
> > that if something break you know what exactly change was the reason to it.
> > Even
> > if these commits will have to be squashed later.
> 
> It sounds like you have just asked us to make that section larger, is
> that right?

Yes, but it can still be easier to read than it is now. A few mails above I put
a suggestion to separate "how to send a patch" and "what changes should it
contain" to different chapters (ideally contained on a single page though). I
can rewrite the section and send it here if there's any interest. I didn't get
any reply if such change is welcome or not, but I imagine it would simplify the
page a lot.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 2500 bytes --]


Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
>> Cc: hi-angel@yandex.ru, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
>> Date: Sun, 18 Jun 2023 12:19:45 +0200
>> 
>> > People keep asking for more and more details to be described there, so
>> > what you expect doesn't stand the test of time and user expectations.
>> 
>> What would you do if CONTRIBUTING were a user interface? Would you
>> include every idea someone has?
>
> Who said anything about including "every idea"?

Sorry about that, it was too careless wording. I meant that 

> We try very hard to
> include there only what's really necessary and non-obvious, you can
> search the archives for discussions about CONTRIBUTE to see it for
> yourself.  But still, the instructions grow over time, because people
> ask questions about the details, and enough people here consider some
> of those details worthy to be included.

With instructions it’s similar as with code: At some point it’s
necessary to refactor, because incremental changes resulted in something
that’s harder to work with than necessary.

There are explanations *why* something is as it is — both in
CONTRIBUTING and in Sending Patches. These are not necessary for someone
wanting to submit a patch, but they are necessary for someone wanting to
improve the instructions or wondering "why that rule?" — which at least
to me is a common question when I see a list of rules.

⇒ not for first contact, but useful at the second or third patch.

>> > It is clear that you personally may not need everything there, but
>> > CONTRIBUTE is not for you and me, or others like we.
>> 
>> For whom *is* CONTRIBUTE?
>
> For people who only start contributing and need to study our
> conventions and requirements.  If they bother reading the file, of
> course.  (If they don't, we will inform them about the relevant
> conventions as part of the patch review process.)

This informing about convention causes load on the maintainers, so I
think we should increase the number of people who read instructions and
get enough information from them that they need not be informed about
convention ⇒ The shorter version I wrote is intended to reduce that load.

At this point I’d say that this may be better as a bug report for the
website. Where can I send these?

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: ams@gnu.org, hi-angel@yandex.ru, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 12:30:04 +0200
> 
> > This refers to other places, so if the reader needs to read them, the
> > gain is largely an illusory one: you must read those referenced places
> > as well.
> 
> You don’t have to read those places. I took care to ensure that all the
> essential parts for contributing a patch are in my shorter version.
> 
> The reference to other places is there for people who think they have
> special requirements or want to understand *why* the rules are as they
> are.

AFAICT, without reading all those places the instructions are
incomplete.  We might as well just said: send the patches to us, and
omit all the rest.

> Maybe the text should make that clear, so this should not be "for more
> details", but "for explanations of these rules, please read
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html"

Those are neither "more details" nor "explanations", they are what we
expect from a perfect patch submit.  I don't see how we can omit them,
if we want to describe our conventions in full.  Without such a full
description, that whole section is unnecessary.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 3722 bytes --]


Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> On Sun, 2023-06-18 at 13:22 +0300, Eli Zaretskii wrote:
>> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
>> > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
>> > Date: Sun, 18 Jun 2023 13:13:23 +0300
>> > 
>> > On Sun, 2023-06-18 at 13:02 +0300, Eli Zaretskii wrote:
>> > > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
>> > > > Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org, luangruo@yahoo.com, 
>> > > >         emacs-devel@gnu.org
>> > > > Date: Sun, 18 Jun 2023 12:56:33 +0300
>> > > > 
>> > > > Okay, so, here's an obvious one: a patch series sent to
>> > > > bug-gnu-emacs@gnu.org
>> > > > should not create separate bugreports for every patch.
>> > > > 
>> > > > In ML-managed projects it is typical to send patches as a series, and
>> > > > when
>> > > > you
>> > > > doing that results in such surprising behaviour, it creates an
>> > > > additional
>> > > > emotional and mental load both for you and for maintainers who would
>> > > > need to
>> > > > do
>> > > > something with these separate reports.
>> > > 
>> > > Our preference is to send patches as a single patch, not as patch
>> > > series.
>> > > 
>> > > That said, people are sometimes sending series, and we don't ask them
>> > > to resend, we process those series anyway.
>> > > 
>> > > As for separate bug reports, this is easily fixed by merging them.
>> > 
>> > Unfortunately merging bugreports does not fix that. The last patch I had to
>> > Emacs was sent with a cover letter and resulted in two reports: one for the
>> > cover letter and another for the patch itself. You may remember that it
>> > resulted
>> > in a confusion, because α) discussions happened on both threads, but then a
>> > new
>> > patch version was only sent to one of them, so there other thread wasn't
>> > notified that comments were addressed, and β) you may remember 3 months
>> > after
>> > the patch got accepted someone was asking the status. Which is because one
>> > of
>> > the threads was closed saying that the patch is applied, but then the other
>> > thread into which a person was looking has no such comment.
>> > 
>> > > So I see no problem here.
>> > 
>> > This is psychology. Having a report per patch may not be a problem for you,
>> > but
>> > when a contributor sends patches and gets into such situation, they do not
>> > know
>> > it is okay. They will be frightened and frustrated, because it looks like
>> > something just went wrong. Such situation being okay needs at least be
>> > mentioned
>> > in "sending patches" section, and at best it should just work.
>> 
>> Like I said: we prefer a single patch for each changeset.  The
>> problems presented by patch series are one reason.  And yet, we will
>> never reject a patch series, even though it makes the process
>> inconvenient and confusing.
>> 
>> I don't see what else do we need to argued about here.
>
> Well, you see, the "sending patches" section has no mention that a series is
> unwelcome. And Emacs is the unique project where a squashed patch with many
> commits is preferred over a series.

There is "When you have all these pieces, bundle them up in a mail
message and send it to the developers."¹ which to me implies to send a
single email.

But it can easily get missed in the long text (datapoint for that: you
missed it), that’s why I think the text shown to new contributors should
get changed.

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 11:26 +0200, Dr. Arne Babenhauserheide wrote:
> ------ ------ ------ ------ ------ ------
>
> 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).

While at it, I think it may be worth to improve this a bit as well. I presume
the "old version as first version" refers to Emacs before it started using git?
I think there's no point to mention it because if you contribute to a project,
you always need the very latest code, in which case there's git support. So I
think `diff -u` mention may be removed. Perhaps:

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

And I'm also wondering if there's any point mentioning `git diff` as well. I think
it's reasonable to expect most people know how to use git and they probably have made
commits, so the `git format-patch` is the way to go.

But even is a person is complete newbie, having to `git-diff` and then to write
commit message manually is uncomfortable, because you have to write the message anew
every time you address a review. It may be better to just suggest to do `git
format-patch` instead.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 13:44:59 +0300
> 
> > > Well, you see, the "sending patches" section has no mention that a series is
> > > unwelcome.
> > 
> > They aren't "unwelcome", please don't misquote what I write.
> 
> Hmm, I feel like there's some confusion. You said that a single patch is
> preferred over a series, right?

"Preferred", yes.  That's a far cry from "unwelcoming" patch series.

> And then you said it is the reason we don't need
> to do anything about the problem with sending a series to bug-gnu-emacs@gnu.org
> 
> But the problem exists, so I'm suggesting that if you don't want it to be fixed,
> perhaps we should put some docs about that.

The problem, such as it exists, is mine and of other people who review
patches.  It isn't the problem of those who _submit_ patches.
Therefore, there is no need to make the instructions longer on behalf
of what isn't the contributor's problem.  In the rare case that a
first-time contributor submits a whole series of patches, he or she
will be told that we prefer a single patch.  That's all, end of story.
Most contributors will never even bump into this, because it is rare
for a casual contributor to submit such complex patches.

> > It sounds like you have just asked us to make that section larger, is
> > that right?
> 
> Yes, but it can still be easier to read than it is now. A few mails above I put
> a suggestion to separate "how to send a patch" and "what changes should it
> contain" to different chapters (ideally contained on a single page though). I
> can rewrite the section and send it here if there's any interest. I didn't get
> any reply if such change is welcome or not, but I imagine it would simplify the
> page a lot.

So when we write text that explains our conventions, it's "too long",
but when you suggest to add more stuff, that makes it "easier to
read"?  Doesn't sound consistent to me.

We only describe in the instructions stuff that is important enough,
and try to keep the details to the absolute minimum that is necessary.
You may think that other aspects are more important, but, with all due
respect, it isn't your call.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1289 bytes --]


Eli Zaretskii <eliz@gnu.org> writes:

>> Maybe the text should make that clear, so this should not be "for more
>> details", but "for explanations of these rules, please read
>> https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html"
>
> Those are neither "more details" nor "explanations", they are what we
> expect from a perfect patch submit.  I don't see how we can omit them,
> if we want to describe our conventions in full.  Without such a full
> description, that whole section is unnecessary.

That sounds like improving the average patch submitted would be useless
if the instructions are not perfect for every case.

But that risks losing contributors because they give up when reading the
instructions.

The goal is easier onboarding. Any hurdle in the way of sending a good
patch¹ causes fewer good patches to be sent — and more bad patches,
because people then don’t read the section at all (or don’t even find
it, because on the website only CONTRIBUTING is linked with a description
that indicates that says that this is about contributing).

¹: good need not be perfect, but good enough to make maintenance easy.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 12:54 +0200, Dr. Arne Babenhauserheide wrote:
> 
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > On Sun, 2023-06-18 at 13:22 +0300, Eli Zaretskii wrote:
> > > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > > > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com,
> > > > emacs-devel@gnu.org
> > > > Date: Sun, 18 Jun 2023 13:13:23 +0300
> > > > 
> > > > On Sun, 2023-06-18 at 13:02 +0300, Eli Zaretskii wrote:
> > > > > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > > > > > Cc: "Alfred M. Szmidt" <ams@gnu.org>, eliz@gnu.org,
> > > > > > luangruo@yahoo.com, 
> > > > > >         emacs-devel@gnu.org
> > > > > > Date: Sun, 18 Jun 2023 12:56:33 +0300
> > > > > > 
> > > > > > Okay, so, here's an obvious one: a patch series sent to
> > > > > > bug-gnu-emacs@gnu.org
> > > > > > should not create separate bugreports for every patch.
> > > > > > 
> > > > > > In ML-managed projects it is typical to send patches as a series,
> > > > > > and
> > > > > > when
> > > > > > you
> > > > > > doing that results in such surprising behaviour, it creates an
> > > > > > additional
> > > > > > emotional and mental load both for you and for maintainers who would
> > > > > > need to
> > > > > > do
> > > > > > something with these separate reports.
> > > > > 
> > > > > Our preference is to send patches as a single patch, not as patch
> > > > > series.
> > > > > 
> > > > > That said, people are sometimes sending series, and we don't ask them
> > > > > to resend, we process those series anyway.
> > > > > 
> > > > > As for separate bug reports, this is easily fixed by merging them.
> > > > 
> > > > Unfortunately merging bugreports does not fix that. The last patch I had
> > > > to
> > > > Emacs was sent with a cover letter and resulted in two reports: one for
> > > > the
> > > > cover letter and another for the patch itself. You may remember that it
> > > > resulted
> > > > in a confusion, because α) discussions happened on both threads, but
> > > > then a
> > > > new
> > > > patch version was only sent to one of them, so there other thread wasn't
> > > > notified that comments were addressed, and β) you may remember 3 months
> > > > after
> > > > the patch got accepted someone was asking the status. Which is because
> > > > one
> > > > of
> > > > the threads was closed saying that the patch is applied, but then the
> > > > other
> > > > thread into which a person was looking has no such comment.
> > > > 
> > > > > So I see no problem here.
> > > > 
> > > > This is psychology. Having a report per patch may not be a problem for
> > > > you,
> > > > but
> > > > when a contributor sends patches and gets into such situation, they do
> > > > not
> > > > know
> > > > it is okay. They will be frightened and frustrated, because it looks
> > > > like
> > > > something just went wrong. Such situation being okay needs at least be
> > > > mentioned
> > > > in "sending patches" section, and at best it should just work.
> > > 
> > > Like I said: we prefer a single patch for each changeset.  The
> > > problems presented by patch series are one reason.  And yet, we will
> > > never reject a patch series, even though it makes the process
> > > inconvenient and confusing.
> > > 
> > > I don't see what else do we need to argued about here.
> > 
> > Well, you see, the "sending patches" section has no mention that a series is
> > unwelcome. And Emacs is the unique project where a squashed patch with many
> > commits is preferred over a series.
> 
> There is "When you have all these pieces, bundle them up in a mail
> message and send it to the developers."¹ which to me implies to send a
> single email.
> 
> But it can easily get missed in the long text (datapoint for that: you
> missed it), that’s why I think the text shown to new contributors should
> get changed.

Well… yes, I did miss it. I see suggestions to have a change per patch (which
implies a series), but this sentence… Even now that I know the meaning, it reads
differently for me due to the context around it. It is not about the amount of
text on the page.

Well. Basically, the problem here is that this sentence just drowns among the
talk about sending "multiple patches" (e.g. 2nd paragraphs starts with "Every
patch…") and me knowing that in ML-managed projects you always send a series.

I also don't think there's a built-in way to send a series as a single message
via `git-send-email`. At least ChatGPT says there isn't, though I didn't exactly
study the man page to see if that's correct. And if a person has experience with
other ML-managed projects, they will likely send patches via `git-send-email`.

I think this phrase needs to be a separate point at the beginning, to emphasise
its significance.

But then, if this is true, this again makes contribution harder for people,
because this is different from every other ML-managed project, and creates
additional work to open your email client, and attach the patches.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 13:59 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 13:44:59 +0300
> > 
> > > > Well, you see, the "sending patches" section has no mention that a
> > > > series is
> > > > unwelcome.
> > > 
> > > They aren't "unwelcome", please don't misquote what I write.
> > 
> > Hmm, I feel like there's some confusion. You said that a single patch is
> > preferred over a series, right?
> 
> "Preferred", yes.  That's a far cry from "unwelcoming" patch series.
> 
> > And then you said it is the reason we don't need
> > to do anything about the problem with sending a series to
> > bug-gnu-emacs@gnu.org
> > 
> > But the problem exists, so I'm suggesting that if you don't want it to be
> > fixed,
> > perhaps we should put some docs about that.
> 
> The problem, such as it exists, is mine and of other people who review
> patches.  It isn't the problem of those who _submit_ patches.
> Therefore, there is no need to make the instructions longer on behalf
> of what isn't the contributor's problem.  In the rare case that a
> first-time contributor submits a whole series of patches, he or she
> will be told that we prefer a single patch.  That's all, end of story.
> Most contributors will never even bump into this, because it is rare
> for a casual contributor to submit such complex patches.

Well… Okay.

> > > It sounds like you have just asked us to make that section larger, is
> > > that right?
> > 
> > Yes, but it can still be easier to read than it is now. A few mails above I
> > put
> > a suggestion to separate "how to send a patch" and "what changes should it
> > contain" to different chapters (ideally contained on a single page though).
> > I
> > can rewrite the section and send it here if there's any interest. I didn't
> > get
> > any reply if such change is welcome or not, but I imagine it would simplify
> > the
> > page a lot.
> 
> So when we write text that explains our conventions, it's "too long",
> but when you suggest to add more stuff, that makes it "easier to
> read"?  Doesn't sound consistent to me.

You missed my point. The section "how to submit patches" will become
significantly shorter. Because it will be separated from all the other points
about what a patch should contain.

Re: contributing to Emacs

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: hi-angel@yandex.ru, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 12:50:28 +0200
> 
> At this point I’d say that this may be better as a bug report for the
> website. Where can I send these?

To the same places where any other bug about Emacs is submitted:
bug-gnu-emacs@gnu.org.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 14:14:55 +0300
> 
> You missed my point. The section "how to submit patches" will become
> significantly shorter. Because it will be separated from all the other points
> about what a patch should contain.

Separating them will be even more confusing: people will read one, but
not the other, and tell us they didn't find something.

Would you please trust me that I care about those instructions very
much and take every opportunity to make them better, in every aspect?

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 14:32 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 14:14:55 +0300
> > 
> > You missed my point. The section "how to submit patches" will become
> > significantly shorter. Because it will be separated from all the other
> > points
> > about what a patch should contain.
> 
> Separating them will be even more confusing: people will read one, but
> not the other, and tell us they didn't find something.

Not necessarily. Let me reiterate: the chapter "Sending Patches" has two
different things: "How to send patches" and "What should patch contain". It is
*already* the case, all I am suggesting is simply divide them with a title
(well, maybe a little bit of refactoring may be needed to make sure the two
parts has only relevant texts).

Why would a person complain they didn't find text about patch content in section
"how to send patches" if it belongs to the section right next to it "What should
a patch contain".

If these two sections are on the same page, a person would see them both,
especially so given the "how to send patches" section would be very short.

(we can think of better sections naming, these two titles are just something I
made up offhand)

> Would you please trust me that I care about those instructions very
> much and take every opportunity to make them better, in every aspect?

Of course, this is why we're discussing them 😊

Re: contributing to Emacs

[Michael Albinus]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

Hi Konstantin,

>> To say nothing of the fact that "Send Bug Report" is right there on
>> the Help menu.
>
> It's not really relevant. Emacs is the unique project that tracks patches in the
> bugtracker,

No. At least Guix does it also, FTR.

Best regards, Michael.

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> Ideally, each commit in the repository should contain minimal functional
> changes. It allows for easier code review at the moment and for better figuring
> out why some change was done later in the life of the project. Usually at this
> point I refer people to this old article from kernel HID subsystem maintainer
> and libinput creator http://who-t.blogspot.com/2009/12/on-commit-messages.html
> Old — but gold! 😄

That's the purpose of ChangeLog, not the VCS.

> When project contributions are done via mailing list (such as kernel, gdb, gcc,
> and in the past were also Xorg and Mesa), you usually turn a number of commits
> to separate patches and send them. E.g. here's one example:
> https://lore.kernel.org/dri-devel/20230612104658.1386996-1-tvrtko.ursulin@linux.intel.com/
> it starts with a "zero patch" that is the title of the series, and then
> individual patches follow.

Mesa and Linux are hardly all the world, and that wasn't my experience
with GDB or GCC development.

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> Well, you see, the "sending patches" section has no mention that a series is
> unwelcome. And Emacs is the unique project where a squashed patch with many
> commits is preferred over a series.
>
> If series is indeed unwelcome, it would be better to reflect in "sending
> patches" section and provide copy-paste instructions for the people to quickly
> squash their commits before sending to ML (and I think something needs to be
> figured out about commit messages too in this case). Because when you are
> developing, it is easier to separate changes to distinct commits to make sure
> that if something break you know what exactly change was the reason to it. Even
> if these commits will have to be squashed later.

What's a ``squashed patch''?

Anyway, patches can only be generated by the VCS if the user has access
to the Emacs version control files, which is hardly given.  So prefering
ordinary diffs leads to more people being able to work on Emacs, not
less.

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> We are discussing possible improvement to Emacs-specific contributing
> workflow.

It's hard to not be drawn into the bikeshedding, and I've failed, but
perhaps if everyone realizes what this discussion is, it will stop.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 14:54:11 +0300
> 
> > Separating them will be even more confusing: people will read one, but
> > not the other, and tell us they didn't find something.
> 
> Not necessarily. Let me reiterate: the chapter "Sending Patches" has two
> different things: "How to send patches" and "What should patch contain". It is
> *already* the case, all I am suggesting is simply divide them with a title
> (well, maybe a little bit of refactoring may be needed to make sure the two
> parts has only relevant texts).

A new contributor needs to know both.

> Why would a person complain they didn't find text about patch content in section
> "how to send patches" if it belongs to the section right next to it "What should
> a patch contain".

Because in an Info reader you don't necessarily see the "section right
next to the current one".

> If these two sections are on the same page, a person would see them both,
> especially so given the "how to send patches" section would be very short.

You assume the contributors read a paper copy or a PDF version of the
manual?

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 15:18 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 14:54:11 +0300
> > 
> > > Separating them will be even more confusing: people will read one, but
> > > not the other, and tell us they didn't find something.
> > 
> > Not necessarily. Let me reiterate: the chapter "Sending Patches" has two
> > different things: "How to send patches" and "What should patch contain". It
> > is
> > *already* the case, all I am suggesting is simply divide them with a title
> > (well, maybe a little bit of refactoring may be needed to make sure the two
> > parts has only relevant texts).
> 
> A new contributor needs to know both.
> 
> > Why would a person complain they didn't find text about patch content in
> > section
> > "how to send patches" if it belongs to the section right next to it "What
> > should
> > a patch contain".
> 
> Because in an Info reader you don't necessarily see the "section right
> next to the current one".

I assume it's a question of markup. I don't know offhand what format is used for
this document, but I can tell that in the worst case a section title may be
created by simply putting a text in bold.

> > If these two sections are on the same page, a person would see them both,
> > especially so given the "how to send patches" section would be very short.
> 
> You assume the contributors read a paper copy or a PDF version of the
> manual?

I am assuming that if a person doesn't know how to contribute to Emacs, they
will query a search engine about that. And search engine would send them to this
page
https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 20:13 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > We are discussing possible improvement to Emacs-specific contributing
> > workflow.
> 
> It's hard to not be drawn into the bikeshedding, and I've failed, but
> perhaps if everyone realizes what this discussion is, it will stop.

Why? There's possibility that "sending patches" will be improved as result of the discussion, isn't that good? Perhaps something else will come out of this as well, I can hope at least.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 20:10 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > Well, you see, the "sending patches" section has no mention that a series is
> > unwelcome. And Emacs is the unique project where a squashed patch with many
> > commits is preferred over a series.
> > 
> > If series is indeed unwelcome, it would be better to reflect in "sending
> > patches" section and provide copy-paste instructions for the people to
> > quickly
> > squash their commits before sending to ML (and I think something needs to be
> > figured out about commit messages too in this case). Because when you are
> > developing, it is easier to separate changes to distinct commits to make
> > sure
> > that if something break you know what exactly change was the reason to it.
> > Even
> > if these commits will have to be squashed later.
> 
> What's a ``squashed patch''?

When you have multiple patches squashed into one.

> Anyway, patches can only be generated by the VCS if the user has access
> to the Emacs version control files, which is hardly given.  So prefering
> ordinary diffs leads to more people being able to work on Emacs, not
> less.

How do you get latest upstream code without access to VCS?

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 20:09 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > Ideally, each commit in the repository should contain minimal functional
> > changes. It allows for easier code review at the moment and for better
> > figuring
> > out why some change was done later in the life of the project. Usually at
> > this
> > point I refer people to this old article from kernel HID subsystem
> > maintainer
> > and libinput creator
> > http://who-t.blogspot.com/2009/12/on-commit-messages.html
> > Old — but gold! 😄
> 
> That's the purpose of ChangeLog, not the VCS.
> 
> > When project contributions are done via mailing list (such as kernel, gdb,
> > gcc,
> > and in the past were also Xorg and Mesa), you usually turn a number of
> > commits
> > to separate patches and send them. E.g. here's one example:
> > https://lore.kernel.org/dri-devel/20230612104658.1386996-1-tvrtko.ursulin@linux.intel.com/
> > it starts with a "zero patch" that is the title of the series, and then
> > individual patches follow.
> 
> Mesa and Linux are hardly all the world, and that wasn't my experience
> with GDB or GCC development.

I am not sure what you mean. Here's GCC ML with patches for the last month
https://gcc.gnu.org/pipermail/gcc-patches/2023-May/thread.html You can see they
send series as well. Here's an arbitrary cover letter "zero patch" for a series
https://gcc.gnu.org/pipermail/gcc-patches/2023-May/618426.html

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 20:09 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > Ideally, each commit in the repository should contain minimal functional
> > changes. It allows for easier code review at the moment and for better
> > figuring
> > out why some change was done later in the life of the project. Usually at
> > this
> > point I refer people to this old article from kernel HID subsystem
> > maintainer
> > and libinput creator
> > http://who-t.blogspot.com/2009/12/on-commit-messages.html
> > Old — but gold! 😄
> 
> That's the purpose of ChangeLog, not the VCS.

Sorry, I didn't reply this one.

Well. You can use Changelog instead of VCS. But what's the point of VCS then? 😊
I mean, if you have changes, you have to know what *are* these changes. I can
imagine some weird workflow where each commit adds a line to Changelog and then
commit messages itself will be empty… But such workflow will be awkward to say
the least.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: Eli Zaretskii <eliz@gnu.org>, arne_bab@web.de, ams@gnu.org, 
> 	emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 15:28:01 +0300
> 
> How do you get latest upstream code without access to VCS?

You can request a snapshot tarball from Savannah.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 15:51 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: Eli Zaretskii <eliz@gnu.org>, arne_bab@web.de, ams@gnu.org, 
> >         emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 15:28:01 +0300
> > 
> > How do you get latest upstream code without access to VCS?
> 
> You can request a snapshot tarball from Savannah.

Does it imply sending an email to Savannah admins? Because I'm browsing page
https://git.savannah.gnu.org/cgit/emacs.git/ and I don't see any link to a
tarball.

Either way, is it even a realistic usecase? When you develop you need to make
sure there's no conflicts. So every time you send patches, you rebase your local
version to make sure it's okay. And `rebase` is only possible with a VCS access.
So someone developing purely from a tarball seems to me like a case of a purely
academic interest.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: luangruo@yahoo.com, arne_bab@web.de, ams@gnu.org, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 16:02:10 +0300
> 
> On Sun, 2023-06-18 at 15:51 +0300, Eli Zaretskii wrote:
> > > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > > Cc: Eli Zaretskii <eliz@gnu.org>, arne_bab@web.de, ams@gnu.org, 
> > >         emacs-devel@gnu.org
> > > Date: Sun, 18 Jun 2023 15:28:01 +0300
> > > 
> > > How do you get latest upstream code without access to VCS?
> > 
> > You can request a snapshot tarball from Savannah.
> 
> Does it imply sending an email to Savannah admins?

No.

> Because I'm browsing page
> https://git.savannah.gnu.org/cgit/emacs.git/ and I don't see any
> link to a tarball.

Do you really need one?

> Either way, is it even a realistic usecase?

No, not really.  Maybe in some emergency.

But one can have a release tarball as the base for preparing a patch,
or a tree moved from another system, or a system that's off-line, etc.
Which is why we also accept diffs, not just "git format-patch".

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> On Sun, 2023-06-18 at 20:09 +0800, Po Lu wrote:
>> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
>> 
>> > Ideally, each commit in the repository should contain minimal functional
>> > changes. It allows for easier code review at the moment and for better
>> > figuring
>> > out why some change was done later in the life of the project. Usually at
>> > this
>> > point I refer people to this old article from kernel HID subsystem
>> > maintainer
>> > and libinput creator
>> > http://who-t.blogspot.com/2009/12/on-commit-messages.html
>> > Old — but gold! 😄
>> 
>> That's the purpose of ChangeLog, not the VCS.
>> 
>> > When project contributions are done via mailing list (such as kernel, gdb,
>> > gcc,
>> > and in the past were also Xorg and Mesa), you usually turn a number of
>> > commits
>> > to separate patches and send them. E.g. here's one example:
>> > https://lore.kernel.org/dri-devel/20230612104658.1386996-1-tvrtko.ursulin@linux.intel.com/
>> > it starts with a "zero patch" that is the title of the series, and then
>> > individual patches follow.
>> 
>> Mesa and Linux are hardly all the world, and that wasn't my experience
>> with GDB or GCC development.
>
> I am not sure what you mean. Here's GCC ML with patches for the last month
> https://gcc.gnu.org/pipermail/gcc-patches/2023-May/thread.html You can see they
> send series as well. Here's an arbitrary cover letter "zero patch" for a series
> https://gcc.gnu.org/pipermail/gcc-patches/2023-May/618426.html

Where is it said that GCC development prefers changes to be submitted in
this format?

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> Well. You can use Changelog instead of VCS. But what's the point of
> VCS then?

So that you can easily restore earlier versions of a file, and prevent
files from being modified by two people at the same time through
locking?

Re: contributing to Emacs

[Po Lu]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> When you have multiple patches squashed into one.

When there are multiple orthogonal changes to Emacs, we prefer one
change be submitted at a time, so I'm not sure what the difference
between that and our preferred practice is.

> How do you get latest upstream code without access to VCS?

Changes to the latest Emacs release will generally apply to the
development source code as well.

Re: contributing to Emacs

[Alfred M. Szmidt]

   > > We are discussing possible improvement to Emacs-specific contributing
   > > workflow.
   > 
   > It's hard to not be drawn into the bikeshedding, and I've failed, but
   > perhaps if everyone realizes what this discussion is, it will stop.

   Why? There's possibility that "sending patches" will be improved as
   result of the discussion, isn't that good? Perhaps something else
   will come out of this as well, I can hope at least.

The improvments suggested so far have been very superficial, and do
not change the way how one contributes to Emacs -- which was what was
the supposed hard part at the start of the discussion.

So yeah, this is mostly bikeshedding at this point ...

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 21:32 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > When you have multiple patches squashed into one.
> 
> When there are multiple orthogonal changes to Emacs, we prefer one
> change be submitted at a time, so I'm not sure what the difference
> between that and our preferred practice is.

Yeah, comparing docs and what Eli says, I think Eli didn't mean to say that a
patch series is not preferred in general, but rather that it's not preferred to
send a patch-series as it's usually done in ML-managed projects, i.e. via `git
send-email`. Apparently it is preferred to have the series attached and sent via
an email client.

So I think on that topic there's not much to discuss (besides of course the
according improvements to "Sending Patches" docs, but improvements are discussed
elsewhere in the thread).

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 21:29 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > On Sun, 2023-06-18 at 20:09 +0800, Po Lu wrote:
> > > Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> > > 
> > > > Ideally, each commit in the repository should contain minimal functional
> > > > changes. It allows for easier code review at the moment and for better
> > > > figuring
> > > > out why some change was done later in the life of the project. Usually
> > > > at
> > > > this
> > > > point I refer people to this old article from kernel HID subsystem
> > > > maintainer
> > > > and libinput creator
> > > > http://who-t.blogspot.com/2009/12/on-commit-messages.html
> > > > Old — but gold! 😄
> > > 
> > > That's the purpose of ChangeLog, not the VCS.
> > > 
> > > > When project contributions are done via mailing list (such as kernel,
> > > > gdb,
> > > > gcc,
> > > > and in the past were also Xorg and Mesa), you usually turn a number of
> > > > commits
> > > > to separate patches and send them. E.g. here's one example:
> > > > https://lore.kernel.org/dri-devel/20230612104658.1386996-1-tvrtko.ursulin@linux.intel.com/
> > > > it starts with a "zero patch" that is the title of the series, and then
> > > > individual patches follow.
> > > 
> > > Mesa and Linux are hardly all the world, and that wasn't my experience
> > > with GDB or GCC development.
> > 
> > I am not sure what you mean. Here's GCC ML with patches for the last month
> > https://gcc.gnu.org/pipermail/gcc-patches/2023-May/thread.html You can see
> > they
> > send series as well. Here's an arbitrary cover letter "zero patch" for a
> > series
> > https://gcc.gnu.org/pipermail/gcc-patches/2023-May/618426.html
> 
> Where is it said that GCC development prefers changes to be submitted in
> this format?

Well, if you want to see the docs, then you can go here
https://gcc.gnu.org/contribute.html#patches and you'll see that it starts with
words "Every patch", which implies that you send multiple patches rather than
just one. "Multiple patches" is a series.

Then if you look a bit further, you'll see this paragraph:

> Series identifier
>
> The series identifier is optional and is only relevant if a number of patches
are needed in order to effect an overall change[…]

So yeah, here's an official text about patch series for GCC, as you wanted.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 21:30 +0800, Po Lu wrote:
> Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> 
> > Well. You can use Changelog instead of VCS. But what's the point of
> > VCS then?
> 
> So that you can easily restore earlier versions of a file,

Alright, and then, how do you know which version to restore if you don't have
commit descriptions? 😊

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1235 bytes --]


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

>    > > We are discussing possible improvement to Emacs-specific contributing
>    > > workflow.
>    > 
>    > It's hard to not be drawn into the bikeshedding, and I've failed, but
>    > perhaps if everyone realizes what this discussion is, it will stop.
>
>    Why? There's possibility that "sending patches" will be improved as
>    result of the discussion, isn't that good? Perhaps something else
>    will come out of this as well, I can hope at least.
>
> The improvments suggested so far have been very superficial, and do
> not change the way how one contributes to Emacs -- which was what was
> the supposed hard part at the start of the discussion.

In the discussion it became clear (at least to me) that the way to
contribute is not the main complication, but the discoverability of that
way and that the way seems hard when you see more than a sheet of paper
in print as instructions.

As a contributor I find "just send your patch by email" to be much
easier than any other workflow. Though that may be due to using Emacs to
send emails (via mu4e).

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 2068 bytes --]


Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> I am assuming that if a person doesn't know how to contribute to Emacs, they
> will query a search engine about that. And search engine would send them to this
> page
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Sending-Patches.html

When I looked up instructions (instead of just using M-x report bug (and
completing on report-emacs-bug with amx), I used the tried and true
approach to look for a "contributing" link on the project-website.

It didn’t work.

I think that’s a bug in the website and may be part of the explanation
why additional ports did not bring many additional developers.
(though the Emacs website is already much, much better than it was two
decades ago)

- today: https://web.archive.org/web/20230602202220/http://www.gnu.org/software/emacs/
- one decade ago: https://web.archive.org/web/20130704144538/http://www.gnu.org/software/emacs/
- two decades ago: https://web.archive.org/web/20030205055456/http://www.gnu.org/software/emacs/

Though for contributors, there’s actually one thing that got worse:
searching on the website for "contribut" turned up the CONTRIBUTING file
before the current design and now doesn’t turn up a result.

Two decades ago:

>  To contact the maintainers of Emacs, either to report a bug or to
>  contribute fixes or improvements, send mail to
>  <bug-gnu-emacs@gnu.org>.

One decade ago:

> To report bugs, or to contribute fixes and improvements, use the
> built-in Emacs bug reporter (M-x report-emacs-bug) or send email to
> bug-gnu-emacs@gnu.org. You can browse our bug database at
> debbugs.gnu.org. For more information on contributing, see the
> CONTRIBUTE file (also distributed with Emacs).

Now:

(you have to click on "Documentation & Support" or on "Further
information" to find something about contributing or development).

I think that’s a regression that needs fixing.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: Konstantin Kharlamov <hi-angel@yandex.ru>, luangruo@yahoo.com,
>  philipk@posteo.net, eliz@gnu.org, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 16:57:56 +0200
> 
> In the discussion it became clear (at least to me) that the way to
> contribute is not the main complication, but the discoverability of that
> way and that the way seems hard when you see more than a sheet of paper
> in print as instructions.

You are inventing a problem where there is none.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 977 bytes --]


Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
>> Cc: Konstantin Kharlamov <hi-angel@yandex.ru>, luangruo@yahoo.com,
>>  philipk@posteo.net, eliz@gnu.org, emacs-devel@gnu.org
>> Date: Sun, 18 Jun 2023 16:57:56 +0200
>> 
>> In the discussion it became clear (at least to me) that the way to
>> contribute is not the main complication, but the discoverability of that
>> way and that the way seems hard when you see more than a sheet of paper
>> in print as instructions.
>
> You are inventing a problem where there is none.

You said that the w32 port didn’t get many additional devs. I’m trying
to find reasons — and on the website I see obvious reasons that keep
people from contributing. And the more I look into it, the more I see
how broken the new-dev-wants-to-contribute usecase of the website is.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Alfred M. Szmidt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 941 bytes --]

   >> In the discussion it became clear (at least to me) that the way to
   >> contribute is not the main complication, but the discoverability of that
   >> way and that the way seems hard when you see more than a sheet of paper
   >> in print as instructions.
   >
   > You are inventing a problem where there is none.

   You said that the w32 port didn’t get many additional devs. I’m trying
   to find reasons — and on the website I see obvious reasons that keep
   people from contributing. And the more I look into it, the more I see
   how broken the new-dev-wants-to-contribute usecase of the website is.

Someone contributing a complicated feature like w32 most surley would
have read the Emacs manual once or twice.  Or at least looked over the
source code -- maybe starting with README file.

What keeps people from contributing complicated thing is that they are
complicated.  Lets stop making a mountain of a molehill.

Re: contributing to Emacs

[Eli Zaretskii]

> From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> Cc: ams@gnu.org, hi-angel@yandex.ru, luangruo@yahoo.com, philipk@posteo.net,
>  emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 20:52:43 +0200
> 
> >> In the discussion it became clear (at least to me) that the way to
> >> contribute is not the main complication, but the discoverability of that
> >> way and that the way seems hard when you see more than a sheet of paper
> >> in print as instructions.
> >
> > You are inventing a problem where there is none.
> 
> You said that the w32 port didn’t get many additional devs. I’m trying
> to find reasons — and on the website I see obvious reasons that keep
> people from contributing. And the more I look into it, the more I see
> how broken the new-dev-wants-to-contribute usecase of the website is.

I understand and appreciate what you are trying to do, but those
aren't the reasons for lack of active contributors to Emacs.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sun, 2023-06-18 at 22:11 +0300, Eli Zaretskii wrote:
> > From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> > Cc: ams@gnu.org, hi-angel@yandex.ru, luangruo@yahoo.com, philipk@posteo.net,
> >  emacs-devel@gnu.org
> > Date: Sun, 18 Jun 2023 20:52:43 +0200
> > 
> > > > In the discussion it became clear (at least to me) that the way to
> > > > contribute is not the main complication, but the discoverability of that
> > > > way and that the way seems hard when you see more than a sheet of paper
> > > > in print as instructions.
> > > 
> > > You are inventing a problem where there is none.
> > 
> > You said that the w32 port didn’t get many additional devs. I’m trying
> > to find reasons — and on the website I see obvious reasons that keep
> > people from contributing. And the more I look into it, the more I see
> > how broken the new-dev-wants-to-contribute usecase of the website is.
> 
> I understand and appreciate what you are trying to do, but those
> aren't the reasons for lack of active contributors to Emacs.

I think it cumulative of many factors, and fixing every small factor that comes
into play increases probability of getting a new contributor.

Re: contributing to Emacs

[Dmitry Gutov]

On 18/06/2023 12:35, Eli Zaretskii wrote:
>> From: Konstantin Kharlamov<hi-angel@yandex.ru>
>> Cc:ams@gnu.org,emacs-devel@gnu.org
>> Date: Sun, 18 Jun 2023 12:18:09 +0300
>>
>>>> You can't send a patch if you don't know how and where to send it 😊 So you
>>>> can't avoid reading that section.
>>> False.  People know how to reach us even without reading.  The few
>>> Emacs mailing lists are common knowledge, and are just an Internet
>>> search away if someone needs that.
>> Okay, let's conduct an experiment. Suppose I am a new contributor who never
>> contributed via MLs. So first I search for "Emacs contribute". I get this URL
>> https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
>> There I see a suggestion to implement a new feature and submit a patch. So then
>> I use page search for word "patch" to see where are details on how to do that. I
>> find a link "Sending Patches". There I find a suggestion to send it to
>> bugtracker, and then various points about MIME types, what needs to be done,
>> etc.
>>
>> In what case do you imagine such new developer would not need to read that
>> section and still will successfully send a patch? 🤷‍♂️
> All of them.  I never had anyone asking where to send a patch.  People
> sometimes say they are not sure whether they send them to a correct
> forum, but they do send them to the right place nonetheless.

You don't see people asking where to send the patch because they simply 
stop at that point. Or they spend some time searching the web and trying.

Most people who know where to send the question, will probably have 
found the bug tracker as well by that point.

https://en.wikipedia.org/wiki/Survivorship_bias#/media/File:Survivorship-bias.svg

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: ams@gnu.org, luangruo@yahoo.com, philipk@posteo.net, emacs-devel@gnu.org
> Date: Sun, 18 Jun 2023 23:10:57 +0300
> 
> On Sun, 2023-06-18 at 22:11 +0300, Eli Zaretskii wrote:
> > > From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
> > > Cc: ams@gnu.org, hi-angel@yandex.ru, luangruo@yahoo.com, philipk@posteo.net,
> > >  emacs-devel@gnu.org
> > > Date: Sun, 18 Jun 2023 20:52:43 +0200
> > > 
> > > > > In the discussion it became clear (at least to me) that the way to
> > > > > contribute is not the main complication, but the discoverability of that
> > > > > way and that the way seems hard when you see more than a sheet of paper
> > > > > in print as instructions.
> > > > 
> > > > You are inventing a problem where there is none.
> > > 
> > > You said that the w32 port didn’t get many additional devs. I’m trying
> > > to find reasons — and on the website I see obvious reasons that keep
> > > people from contributing. And the more I look into it, the more I see
> > > how broken the new-dev-wants-to-contribute usecase of the website is.
> > 
> > I understand and appreciate what you are trying to do, but those
> > aren't the reasons for lack of active contributors to Emacs.
> 
> I think it cumulative of many factors, and fixing every small factor that comes
> into play increases probability of getting a new contributor.

The suggested measures will not fix any such factors.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 888 bytes --]


Eli Zaretskii <eliz@gnu.org> writes:

>> > > You said that the w32 port didn’t get many additional devs. I’m trying
>> > > to find reasons — and on the website I see obvious reasons that keep
>> > > people from contributing. And the more I look into it, the more I see
>> > > how broken the new-dev-wants-to-contribute usecase of the website is.
>> > 
>> > I understand and appreciate what you are trying to do, but those
>> > aren't the reasons for lack of active contributors to Emacs.
>> 
>> I think it cumulative of many factors, and fixing every small factor that comes
>> into play increases probability of getting a new contributor.
>
> The suggested measures will not fix any such factors.

I obviously disagree strongly but will not pursue this further.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[David Masterson]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Konstantin Kharlamov <hi-angel@yandex.ru>
>> 
>> On Sun, 2023-06-18 at 22:11 +0300, Eli Zaretskii wrote:
>> > > From: "Dr. Arne Babenhauserheide" <arne_bab@web.de>
>> > > 
>> > > > > In the discussion it became clear (at least to me) that the way to
>> > > > > contribute is not the main complication, but the discoverability of that
>> > > > > way and that the way seems hard when you see more than a sheet of paper
>> > > > > in print as instructions.
>> > > > 
>> > > > You are inventing a problem where there is none.
>> > > 
>> > > You said that the w32 port didn’t get many additional devs. I’m trying
>> > > to find reasons — and on the website I see obvious reasons that keep
>> > > people from contributing. And the more I look into it, the more I see
>> > > how broken the new-dev-wants-to-contribute usecase of the website is.
>> > 
>> > I understand and appreciate what you are trying to do, but those
>> > aren't the reasons for lack of active contributors to Emacs.
>> 
>> I think it cumulative of many factors, and fixing every small factor that comes
>> into play increases probability of getting a new contributor.
>
> The suggested measures will not fix any such factors.

Would you say that Emacs still has development practices from the
80s/90s that, given the chance and newer toolsets, you could see being
done differently and better?

It's okay to say that what Emacs has now is working well for the current
developers, but is difficult for on-boarding new developers that want to
start out simple before graduating into Emacs internals.

-- 
David Masterson

Re: contributing to Emacs

[Eli Zaretskii]

> From: David Masterson <dsmasterson@gmail.com>
> Cc: Konstantin Kharlamov <hi-angel@yandex.ru>,  arne_bab@web.de,
>   ams@gnu.org,  luangruo@yahoo.com,  philipk@posteo.net,
>   emacs-devel@gnu.org
> Date: Mon, 19 Jun 2023 11:07:07 -0700
> 
> Would you say that Emacs still has development practices from the
> 80s/90s that, given the chance and newer toolsets, you could see being
> done differently and better?

What are "development practices from the 80s/90s"?

> It's okay to say that what Emacs has now is working well for the current
> developers, but is difficult for on-boarding new developers that want to
> start out simple before graduating into Emacs internals.

Practical suggestions for changes that would make it easier are
welcome, but they must not make the lives of the current developers
significantly harder.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Mon, 2023-06-19 at 21:50 +0300, Eli Zaretskii wrote:
> > From: David Masterson <dsmasterson@gmail.com>
> > Cc: Konstantin Kharlamov <hi-angel@yandex.ru>,  arne_bab@web.de,
> >   ams@gnu.org,  luangruo@yahoo.com,  philipk@posteo.net,
> >   emacs-devel@gnu.org
> > Date: Mon, 19 Jun 2023 11:07:07 -0700
> > 
> > Would you say that Emacs still has development practices from the
> > 80s/90s that, given the chance and newer toolsets, you could see being
> > done differently and better?
> 
> What are "development practices from the 80s/90s"?

I would abstain from answering this question, because this will turn into a
completely useless flamewar.

> > It's okay to say that what Emacs has now is working well for the current
> > developers, but is difficult for on-boarding new developers that want to
> > start out simple before graduating into Emacs internals.
> 
> Practical suggestions for changes that would make it easier are
> welcome, but they must not make the lives of the current developers
> significantly harder.

For starters I would be happy if at least the section about submitting patches
was reformatted into two sections. My last email explaining that no information
will be lost in such reformat¹ was unanswered, so I don't know what is the
current state of this discussion.

1: https://lists.gnu.org/archive/html/emacs-devel/2023-06/msg00506.html

Re: contributing to Emacs

[David Masterson]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Masterson <dsmasterson@gmail.com>
>> 
>> Would you say that Emacs still has development practices from the
>> 80s/90s that, given the chance and newer toolsets, you could see being
>> done differently and better?
>
> What are "development practices from the 80s/90s"?

I'm not a developer of Emacs -- I've kibitzed around in it off and on
for 40+ years.  In the 80s, there was reliance on email/news for comms
(there wasn't much else available).  It worked good, but things got
misplaced once in awhile because of the disconnect between email & news.
I'm sure things have improved with newer tools (like Git allowing direct
checkout/checkin of code with proper controls rather than emailed patch
files), but I asked if you could see things being better.

>> It's okay to say that what Emacs has now is working well for the current
>> developers, but is difficult for on-boarding new developers that want to
>> start out simple before graduating into Emacs internals.
>
> Practical suggestions for changes that would make it easier are
> welcome, but they must not make the lives of the current developers
> significantly harder.

This is what I thought.  You, as a current developer, should be
commenting on suggestions from the standpoint of "will it make my life
harder?" (with a grain of flexibility).

I hope others understand that point.

-- 
David Masterson

Re: contributing to Emacs

[David Masterson]

Konstantin Kharlamov <hi-angel@yandex.ru> writes:

> On Mon, 2023-06-19 at 21:50 +0300, Eli Zaretskii wrote:
>> > From: David Masterson <dsmasterson@gmail.com>
>> > 
>> > Would you say that Emacs still has development practices from the
>> > 80s/90s that, given the chance and newer toolsets, you could see being
>> > done differently and better?
>> 
>> What are "development practices from the 80s/90s"?
>
> I would abstain from answering this question, because this will turn into a
> completely useless flamewar.

I think I understand his question and I'm not going to answer it like I
know better -- he's been much more embedded in Emacs development than me.

-- 
David Masterson

Re: contributing to Emacs

[Po Lu]

David Masterson <dsmasterson@gmail.com> writes:

> I'm not a developer of Emacs -- I've kibitzed around in it off and on
> for 40+ years.  In the 80s, there was reliance on email/news for comms
> (there wasn't much else available).  It worked good, but things got
> misplaced once in awhile because of the disconnect between email & news.

I'm sure the proper fix is for the FSF to fix the news to mail gateways
between the various lists and GNUsenet.

Re: contributing to Emacs

[David Masterson]

Po Lu <luangruo@yahoo.com> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> I'm not a developer of Emacs -- I've kibitzed around in it off and on
>> for 40+ years.  In the 80s, there was reliance on email/news for comms
>> (there wasn't much else available).  It worked good, but things got
>> misplaced once in awhile because of the disconnect between email & news.
>
> I'm sure the proper fix is for the FSF to fix the news to mail gateways
> between the various lists and GNUsenet.

Mostly yes.  Back in the early days (~1987), that happened now and then.

But more that the "flow" of email is a bit different than news and new
people (as I was then) can miss something in email (because they weren't
on all the MLs) or news (because threads split and rejoined and you
missed something).  Also, working with patches via email/news was
sometimes problematic.

Things have gotten better over time.

-- 
David Masterson

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Richard, would you please look at the thread starting at
  > <83v8fnslfz.fsf@gnu.org>, and make a final decision?

That was a big discussion and I've been very backlogged.  It seems to
be around 150 messages, according to grep.  I can't read that many!
It would take me hours.

It seems to be a matter of ease of maintenance, not directly a specific
technical point, and not an ethical issue.  I think the active maintainers
are the best people to decide this.

  >   I'm afraid that if
  > the Android port isn't eventually installed, there will be a fork,

1. Why would it be a fork, rather than updating a set of changes as has
happened with Emacs for MacOS?

2. Why would a fork be a very bad thing?

  >  and I
  > don't have the energy to work on both the fork and Emacs at the same
  > time.

3. Could you please tell me in 20 lines what the crucial issue is?
Has someone proposed a policy that we don't install a big change
if only one person can understand it?

4. Could we recruit Android wizards to help work on it?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Po Lu]

Richard Stallman <rms@gnu.org> writes:

> That was a big discussion and I've been very backlogged.  It seems to
> be around 150 messages, according to grep.  I can't read that many!
> It would take me hours.
>
> It seems to be a matter of ease of maintenance, not directly a specific
> technical point, and not an ethical issue.  I think the active maintainers
> are the best people to decide this.

No active Emacs developers, aside from Eli and me, have commented on the
technical aspects of the issue.

> 1. Why would it be a fork, rather than updating a set of changes as has
> happened with Emacs for MacOS?

That hasn't happened with Emacs for Mac OS.  The NS port is part of the
GNU Emacs distribution.

> 2. Why would a fork be a very bad thing?

Because we will soon have a proliferation of subtly incompatible
varities of Emacs.

> 3. Could you please tell me in 20 lines what the crucial issue is?
> Has someone proposed a policy that we don't install a big change
> if only one person can understand it?

Not ``if only one person can understand it'', but rather ``if there is
_currently_ only one person who understands it.''

> 4. Could we recruit Android wizards to help work on it?

Probably, if the necessity arrives.  However, the work is finished.
All that remains is to install the changes.

Thanks.

Re: contributing to Emacs

[Alfred M. Szmidt]

   David Masterson <dsmasterson@gmail.com> writes:

   > I'm not a developer of Emacs -- I've kibitzed around in it off and on
   > for 40+ years.  In the 80s, there was reliance on email/news for comms
   > (there wasn't much else available).  It worked good, but things got
   > misplaced once in awhile because of the disconnect between email & news.

   I'm sure the proper fix is for the FSF to fix the news to mail gateways
   between the various lists and GNUsenet.

If it is something we, the GNU project wants, it is _us_ who should
make it happen.  Not the FSF.  So as usual, someone has to volunteer
to do that work.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, philipk@posteo.net, 
> 	emacs-devel@gnu.org
> Date: Tue, 20 Jun 2023 00:29:10 +0300
> 
> > Practical suggestions for changes that would make it easier are
> > welcome, but they must not make the lives of the current developers
> > significantly harder.
> 
> For starters I would be happy if at least the section about submitting patches
> was reformatted into two sections. My last email explaining that no information
> will be lost in such reformat¹ was unanswered, so I don't know what is the
> current state of this discussion.
> 
> 1: https://lists.gnu.org/archive/html/emacs-devel/2023-06/msg00506.html

I already said I didn't think this was a good idea, and explained why
I thought so.

In any case, that section hardly has any bearing on the main issue at
hand: how to make it easier for people to contribute.  I explained
that as well.

I'd appreciate if this seasonal "what's wrong with Emacs
contributions" discussion would either switch to discussing some
innovative and useful ideas for how to make it easier for
contributors, or just died if there are no such ideas yet.
Reiterating the same claims and the same arguments doesn't sound like
a good use of our time and bandwidth.

Re: contributing to Emacs

[Eli Zaretskii]

> From: David Masterson <dsmasterson@gmail.com>
> Cc: hi-angel@yandex.ru,  arne_bab@web.de,  ams@gnu.org,  luangruo@yahoo.com,
>   philipk@posteo.net,  emacs-devel@gnu.org
> Date: Mon, 19 Jun 2023 15:47:05 -0700
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: David Masterson <dsmasterson@gmail.com>
> >> 
> >> Would you say that Emacs still has development practices from the
> >> 80s/90s that, given the chance and newer toolsets, you could see being
> >> done differently and better?
> >
> > What are "development practices from the 80s/90s"?
> 
> I'm not a developer of Emacs -- I've kibitzed around in it off and on
> for 40+ years.  In the 80s, there was reliance on email/news for comms
> (there wasn't much else available).  It worked good, but things got
> misplaced once in awhile because of the disconnect between email & news.

If this is about problems between email and news, then I don't think
it's relevant anymore, since hardly anyone here uses news anymore for
submitting changes and discussing them.

If I misunderstood, and "development practices from the 80s/90s"
something else, please elaborate.

> > Practical suggestions for changes that would make it easier are
> > welcome, but they must not make the lives of the current developers
> > significantly harder.
> 
> This is what I thought.  You, as a current developer, should be
> commenting on suggestions from the standpoint of "will it make my life
> harder?" (with a grain of flexibility).

That's one consideration, yes.  The other is what are the advantages
of the suggested changes.  Their balance is what drives the final
decisions.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: ams@gnu.org, hi-angel@yandex.ru, eliz@gnu.org, arne_bab@web.de,
> 	emacs-devel@gnu.org
> Date: Mon, 19 Jun 2023 22:55:27 -0400
> 
> Has someone proposed a policy that we don't install a big change
> if only one person can understand it?

I don't think it's useful to bring up such general questions here.

What I did ask was whether in this particular case we'd want to
install the Android changes, and describe some of the downsides I saw
to doing that.  Having just one individual who fully understands the
platform and the code was one of the downsides, but not the only one.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Tue, 2023-06-20 at 14:14 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com, philipk@posteo.net, 
> >         emacs-devel@gnu.org
> > Date: Tue, 20 Jun 2023 00:29:10 +0300
> > 
> > > Practical suggestions for changes that would make it easier are
> > > welcome, but they must not make the lives of the current developers
> > > significantly harder.
> > 
> > For starters I would be happy if at least the section about submitting
> > patches
> > was reformatted into two sections. My last email explaining that no
> > information
> > will be lost in such reformat¹ was unanswered, so I don't know what is the
> > current state of this discussion.
> > 
> > 1: https://lists.gnu.org/archive/html/emacs-devel/2023-06/msg00506.html
> 
> I already said I didn't think this was a good idea, and explained why
> I thought so.

You said you afraid some information will be lost. I explained that it won't.
You didn't provide any counter-arguments, so I kind of hoped it is clear at this
point that it will only bring benefit. If you are referring to something I
didn't answer, please point that out, because to my knowledge I replied to
everything.

> In any case, that section hardly has any bearing on the main issue at
> hand: how to make it easier for people to contribute.  I explained
> that as well.

That is because the large issue consists of many small ones! The only single
"big move" that is theoretically possible is just move Emacs to a Gitlab
instance, which will remove necessity to care of any docs because finding a
developer who doesn't know how git-forges work is unlikely. But I *do not*
suggest doing that because I know many long-timers would not want that. So
instead I am trying to bite at different pieces that could be improved without
affecting existing workflow. This docs discussion is just one small piece.

> I'd appreciate if this seasonal "what's wrong with Emacs
> contributions" discussion would either switch to discussing some
> innovative and useful ideas for how to make it easier for
> contributors, or just died if there are no such ideas yet.
> Reiterating the same claims and the same arguments doesn't sound like
> a good use of our time and bandwidth.

To my knowledge, I didn't "reiterate same claims", but was answering your
reasoning about not wanting to change the docs, and your reasoning didn't seem
to have been recursive so far. And it is pointless to suggest new ideas if we
didn't even finish discussing old ones.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: dsmasterson@gmail.com, arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com,
>   philipk@posteo.net, emacs-devel@gnu.org
> Date: Tue, 20 Jun 2023 18:45:03 +0300
> 
> > I already said I didn't think this was a good idea, and explained why
> > I thought so.
> 
> You said you afraid some information will be lost. I explained that it won't.
> You didn't provide any counter-arguments, so I kind of hoped it is clear at this
> point that it will only bring benefit. If you are referring to something I
> didn't answer, please point that out, because to my knowledge I replied to
> everything.

If you carefully re-read what I wrote about those suggestions, you
will see that the issue is exhausted from my POV.

> > In any case, that section hardly has any bearing on the main issue at
> > hand: how to make it easier for people to contribute.  I explained
> > that as well.
> 
> That is because the large issue consists of many small ones!

You cannot solve a complex problem by explaining it.  So adding more
and more explanations will not get us closer to the goal.  Especially
since almost no one reads that, especially not the new contributors.
They instead learn it on the job, one bit at a time.  And there's
nothing wrong with that, from where I stand.

> The only single
> "big move" that is theoretically possible is just move Emacs to a Gitlab
> instance, which will remove necessity to care of any docs because finding a
> developer who doesn't know how git-forges work is unlikely. But I *do not*
> suggest doing that because I know many long-timers would not want that. So
> instead I am trying to bite at different pieces that could be improved without
> affecting existing workflow. This docs discussion is just one small piece.

We considered Gitlab, and also a couple of other alternatives.  They
all had problems that needed to be solved first, and no one stepped
forward or succeeded to do that.  You can find all this in the
archives, including our minimum requirements to any such
workflow/framework.

Re: contributing to Emacs

[Alfred M. Szmidt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 934 bytes --]

   > In any case, that section hardly has any bearing on the main issue at
   > hand: how to make it easier for people to contribute.  I explained
   > that as well.

   That is because the large issue consists of many small ones! The only single
   "big move" that is theoretically possible is just move Emacs to a Gitlab
   instance, which will remove necessity to care of any docs because finding a
   developer who doesn't know how git-forges work is unlikely. But I *do not*
   suggest doing that because I know many long-timers would not want that. So
   instead I am trying to bite at different pieces that could be improved without
   affecting existing workflow. This docs discussion is just one small piece.

I'm sorry, but this cannot be taken seriously.  "remove necessity to
care of any docs"?  This is now how good software development works,
and such naive attiude for silver bullets is not only counter productive.

Re: contributing to Emacs

[Lynn Winebarger]

[-- Attachment #1: Type: text/plain, Size: 1020 bytes --]

On Tue, Jun 20, 2023, 12:15 PM Eli Zaretskii <eliz@gnu.org> wrote:

> > The only single
> > "big move" that is theoretically possible is just move Emacs to a Gitlab
> > instance, which will remove necessity to care of any docs because
> finding a
> > developer who doesn't know how git-forges work is unlikely. But I *do
> not*
> > suggest doing that because I know many long-timers would not want that.
> So
> > instead I am trying to bite at different pieces that could be improved
> without
> > affecting existing workflow. This docs discussion is just one small
> piece.
>
> We considered Gitlab, and also a couple of other alternatives.  They
> all had problems that needed to be solved first, and no one stepped
> forward or succeeded to do that.  You can find all this in the
> archives, including our minimum requirements to any such
> workflow/framework
>

Have the problems with the search interface for the mailing list archive
been fixed?  Unless you meant some other archives, that seems problematic.

Lynn

[-- Attachment #2: Type: text/html, Size: 1631 bytes --]

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1287 bytes --]


Konstantin Kharlamov <hi-angel@yandex.ru> writes:
> On Tue, 2023-06-20 at 14:14 +0300, Eli Zaretskii wrote:
>> I'd appreciate if this seasonal "what's wrong with Emacs
>> contributions" discussion would either switch to discussing some
>> innovative and useful ideas for how to make it easier for
>> contributors, or just died if there are no such ideas yet.
>> Reiterating the same claims and the same arguments doesn't sound like
>> a good use of our time and bandwidth.
>
> To my knowledge, I didn't "reiterate same claims", but was answering your
> reasoning about not wanting to change the docs, and your reasoning didn't seem
> to have been recursive so far. And it is pointless to suggest new ideas if we
> didn't even finish discussing old ones.

Maybe this was to both your arguments and my arguments which are
similar, though our proposed solutions differ.

I decided to stop pushing that point, because I realized that while I
know that part of my experience is fixing broken information flows (so I
actually think that I am right in this), it will not be a good use of my
or Eli's time if I keep pushing there but it gets rejected in the end
anyway.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Eli Zaretskii]

> From: Lynn Winebarger <owinebar@gmail.com>
> Date: Tue, 20 Jun 2023 12:32:25 -0400
> Cc: Konstantin Kharlamov <hi-angel@yandex.ru>, dsmasterson@gmail.com, arne_bab@web.de, ams@gnu.org, 
> 	Po Lu <luangruo@yahoo.com>, Philip Kaludercic <philipk@posteo.net>, 
> 	emacs-devel <emacs-devel@gnu.org>
> 
> Have the problems with the search interface for the mailing list archive been fixed?  Unless you meant
> some other archives, that seems problematic.

How many different and almost unrelated problems do we want to discuss
in a single thread??

No, search problems have not been solved, AFAIK, and I have no idea
what else can be done to solve them.  If you ask me, I suggest that
interested people download the archives (each month can be downloaded
as a single mbox file) and archive them locally, using some search
software, like mairix or another.

But please! don't add more topics to this discussion, which already
wasted enough time and bandwidth without any positive results.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Tue, 2023-06-20 at 19:14 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: dsmasterson@gmail.com, arne_bab@web.de, ams@gnu.org, luangruo@yahoo.com,
> >   philipk@posteo.net, emacs-devel@gnu.org
> > Date: Tue, 20 Jun 2023 18:45:03 +0300
> > 
> > > I already said I didn't think this was a good idea, and explained why
> > > I thought so.
> > 
> > You said you afraid some information will be lost. I explained that it
> > won't.
> > You didn't provide any counter-arguments, so I kind of hoped it is clear at
> > this
> > point that it will only bring benefit. If you are referring to something I
> > didn't answer, please point that out, because to my knowledge I replied to
> > everything.
> 
> If you carefully re-read what I wrote about those suggestions, you
> will see that the issue is exhausted from my POV.

Sorry, I am not the best person to read for cues between the lines, if that's
what you meant. You explained my suggestion has a problem, I disproved that. As
far as I understand you just do not want to discuss this issue (not because it's
wrong or something, but because you just don't have the motivation). It's okay.
I think at this point I should ask if there any other person who can apply the
change to the docs who I can discuss it with, although to be honest I'm kind of
exhausted too.

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I'm sure the proper fix is for the FSF to fix the news to mail gateways
  > between the various lists and GNUsenet.

Can someone please report this in a concrete way?  I can forward
it to the sysadmins.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Po Lu]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > I'm sure the proper fix is for the FSF to fix the news to mail gateways
>   > between the various lists and GNUsenet.
>
> Can someone please report this in a concrete way?  I can forward
> it to the sysadmins.

Sure: articles posted to gnu.emacs.help don't end up on help-gnu-emacs,
and vice versa.

Re: contributing to Emacs

[David Masterson]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > I'm sure the proper fix is for the FSF to fix the news to mail gateways
>   > between the various lists and GNUsenet.
>
> Can someone please report this in a concrete way?  I can forward
> it to the sysadmins.

This particular discussion was in regards to the way things were a long
time ago in a place far, far away.  Things have improved since then.

-- 
David Masterson

Re: contributing to Emacs

[Gregory Heytings]

>
> No active Emacs developers, aside from Eli and me, have commented on the 
> technical aspects of the issue.
>

That remark is inelegant at best.

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > 2. Why would a fork be a very bad thing?

  > Because we will soon have a proliferation of subtly incompatible
  > varities of Emacs.

I dom't think that is necessarily so bad.

  > > Has someone proposed a policy that we don't install a big change
  > > if only one person can understand it?

  > Not ``if only one person can understand it'', but rather ``if there is
  > _currently_ only one person who understands it.''

Could you show me the actual proposal that was made?

  > > 4. Could we recruit Android wizards to help work on it?

  > Probably, if the necessity arrives.  However, the work is finished.
  > All that remains is to install the changes.

What work does "the work" refer to?  Various messages seem to say
that the code that has been written is only partial support for Emacs on Android -- that some important features are not yet implemented.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Po Lu]

Richard Stallman <rms@gnu.org> writes:

> I dom't think that is necessarily so bad.

It is: look at XEmacs, and the waste it led to.

> Could you show me the actual proposal that was made?

I suggest reading the first article in this thread.  Namely, this:

>  . currently, we have a single developer who understands the
>    specifics of the Android port and works on developing it; it is
>    not good for Emacs to depend on a single individual for a port
>    that should be kept alive and up-to-date for the observable future

> Various messages seem to say that the code that has been written is
> only partial support for Emacs on Android -- that some important
> features are not yet implemented.

Would you please show me any of those messages?  I've been unequivocally
clear on this point: the port has already been completed (and was as far
back as April.)

Re: contributing to Emacs

[Philip Kaludercic]

Po Lu <luangruo@yahoo.com> writes:

> Richard Stallman <rms@gnu.org> writes:
>
>> I dom't think that is necessarily so bad.
>
> It is: look at XEmacs, and the waste it led to.

I think we have to distinguish between a diverging fork like XEmacs and
a "parallel" fork, that aims to preserve mutual compatibility.  In the
former case, the two projects will find it more and more difficult over
time to share code, while in the latter is just a question of
organisation and administration, that doesn't matter that much to the
user.

>> Could you show me the actual proposal that was made?
>
> I suggest reading the first article in this thread.  Namely, this:
>
>>  . currently, we have a single developer who understands the
>>    specifics of the Android port and works on developing it; it is
>>    not good for Emacs to depend on a single individual for a port
>>    that should be kept alive and up-to-date for the observable future
>
>> Various messages seem to say that the code that has been written is
>> only partial support for Emacs on Android -- that some important
>> features are not yet implemented.
>
> Would you please show me any of those messages?  I've been unequivocally
> clear on this point: the port has already been completed (and was as far
> back as April.)

I recall reading that GNUTLS was not supported on Android, making it
difficult to fetch packages from ELPA.  Has this been addressed?  I
would have looked it up myself, but I don't know where to begin.

Re: contributing to Emacs

[Po Lu]

Philip Kaludercic <philipk@posteo.net> writes:

> I recall reading that GNUTLS was not supported on Android, making it
> difficult to fetch packages from ELPA.  Has this been addressed?  I
> would have looked it up myself, but I don't know where to begin.

GnuTLS is supported, and my own builds are built with it enabled.  This
misconception results from F-Droid packaging Emacs without GnuTLS.

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1089 bytes --]


Philip Kaludercic <philipk@posteo.net> writes:

> Po Lu <luangruo@yahoo.com> writes:
>
>> Richard Stallman <rms@gnu.org> writes:
>>
>>> I dom't think that is necessarily so bad.
>>
>> It is: look at XEmacs, and the waste it led to.
>
> I think we have to distinguish between a diverging fork like XEmacs and
> a "parallel" fork, that aims to preserve mutual compatibility.  In the
> former case, the two projects will find it more and more difficult over
> time to share code, while in the latter is just a question of
> organisation and administration, that doesn't matter that much to the
> user.

It means that the parallel fork has to be rebased everytime a change is
made and that people working on the original codebase do not see whether
their change breaks the parallel fork.

That creates additional work that does not exist at all if the codebases
are merged.

Just think of it like a long-running pull-request. In my experience
these always bitrot.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > This particular discussion was in regards to the way things were a long
  > time ago in a place far, far away.  Things have improved since then.

I'm glad things have improved.  I have not heard anything concrete
about netnews since many years ago, except perhaps Google has taken
over netnews.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Po Lu]

Richard Stallman <rms@gnu.org> writes:

> perhaps Google has taken over netnews.

This is not true!

Google operates a large news server that can only be used through their
web page.  But there are many other sites in existence, as always.

Re: contributing to Emacs

[Sean Whitton]

Hello,

On Sun 18 Jun 2023 at 10:22AM GMT, Philip Kaludercic wrote:

> One idea (but I don't know if this is practicable), is to use the
> configure script to set up Git's `sendemail.to' option or to add
> `vc-default-patch-addressee' to .dir-locals.el.

I thought we were going to do that anyway, just as soon as enough time
had passed that people are not going to get unsafe local variable
popups?

-- 
Sean Whitton

Re: contributing to Emacs

[Sean Whitton]

Hello,

On Sun 18 Jun 2023 at 06:12PM +08, Po Lu wrote:

> Typically, free software maintainers expect patches to be a single
> context format diff, containing either edits to the appropriate
> ChangeLog file(s), or with ChangeLog entries prepended.

This is not the typical case anymore.  If a project is in git or
similar, then the expectation is that you send a patches series for all
but trivial changes.

-- 
Sean Whitton

Re: contributing to Emacs

[Po Lu]

Sean Whitton <spwhitton@spwhitton.name> writes:

> This is not the typical case anymore.  If a project is in git or
> similar, then the expectation is that you send a patches series for all
> but trivial changes.

Such expectations are based on the assumption that the user sending the
patch has access to the version control files associated with the
program being used, which is hardly guaranteed to be true.  I've never
seen Git repository files distributed together with a program.

Re: contributing to Emacs

[Sean Whitton]

Hello,

On Fri 23 Jun 2023 at 03:06PM +08, Po Lu wrote:

> Sean Whitton <spwhitton@spwhitton.name> writes:
>
>> This is not the typical case anymore.  If a project is in git or
>> similar, then the expectation is that you send a patches series for all
>> but trivial changes.
>
> Such expectations are based on the assumption that the user sending the
> patch has access to the version control files associated with the
> program being used, which is hardly guaranteed to be true.  I've never
> seen Git repository files distributed together with a program.

Not guaranteed, but it's the default.

If a project is in git, and you want to contribute, you 'git clone'.

-- 
Sean Whitton

Re: contributing to Emacs

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: Konstantin Kharlamov <hi-angel@yandex.ru>,  "Dr. Arne Babenhauserheide"
>  <arne_bab@web.de>,  "Alfred M. Szmidt" <ams@gnu.org>,  eliz@gnu.org,
>   emacs-devel@gnu.org
> Date: Fri, 23 Jun 2023 07:51:41 +0100
> 
> On Sun 18 Jun 2023 at 06:12PM +08, Po Lu wrote:
> 
> > Typically, free software maintainers expect patches to be a single
> > context format diff, containing either edits to the appropriate
> > ChangeLog file(s), or with ChangeLog entries prepended.
> 
> This is not the typical case anymore.  If a project is in git or
> similar, then the expectation is that you send a patches series for all
> but trivial changes.

Not in this project.  Here, the preference is the opposite one (but we
will gladly accept series as well).

Re: contributing to Emacs

[Björn Bidar]

Eli Zaretskii <eliz@gnu.org> writes:

>> The only single
>> "big move" that is theoretically possible is just move Emacs to a Gitlab
>> instance, which will remove necessity to care of any docs because finding a
>> developer who doesn't know how git-forges work is unlikely. But I *do not*
>> suggest doing that because I know many long-timers would not want that. So
>> instead I am trying to bite at different pieces that could be improved without
>> affecting existing workflow. This docs discussion is just one small piece.
>
> We considered Gitlab, and also a couple of other alternatives.  They
> all had problems that needed to be solved first, and no one stepped
> forward or succeeded to do that.  You can find all this in the
> archives, including our minimum requirements to any such
> workflow/framework.

Have you considered updating mailman to mailman3 plus hyperkitty? The
new hyperkitty interface is easier to use and works better different
screen layouts such as mobile or high dpi.

Also considering that Mailman2 uses Python 2 which is EOL.

Re: contributing to Emacs

[Po Lu]

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Have you considered updating mailman to mailman3 plus hyperkitty? The
> new hyperkitty interface is easier to use and works better different
> screen layouts such as mobile or high dpi.

Please, no.  Hyperkitty is much more difficult to use, one reason being
that it seems to assume _everyone_ is using one of those new screen
layouts, and increases the size of the padding around hyperlinks
accordingly.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Björn Bidar <bjorn.bidar@thaodan.de>
> Cc: Konstantin Kharlamov <hi-angel@yandex.ru>,  dsmasterson@gmail.com,
>   arne_bab@web.de,  ams@gnu.org,  luangruo@yahoo.com,  philipk@posteo.net,
>   emacs-devel@gnu.org
> Date: Sat, 24 Jun 2023 04:44:19 +0300
> 
> Have you considered updating mailman to mailman3 plus hyperkitty? The
> new hyperkitty interface is easier to use and works better different
> screen layouts such as mobile or high dpi.
> 
> Also considering that Mailman2 uses Python 2 which is EOL.

Mailman is not maintained by us, it's infrastructure used by the
entire GNU Project.  If you want to suggest changes in that, please
post to mailman@gnu.org and savannah-hackers-public@gnu.org.

The Emacs project just uses the infrastructure provided by GNU.

Also, the bug tracker is not built on mailman, it just sends messages
to a mailing list, but that's all.

Re: contributing to Emacs

[Sean Whitton]

Hello,

On Fri 23 Jun 2023 at 10:17AM +03, Eli Zaretskii wrote:

> Not in this project.  Here, the preference is the opposite one (but we
> will gladly accept series as well).

I know, I just wanted to update Po's impression of the wider ecosystem.

-- 
Sean Whitton

Re: contributing to Emacs

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Cc: luangruo@yahoo.com,  hi-angel@yandex.ru,  arne_bab@web.de,  ams@gnu.org,
>  emacs-devel@gnu.org
> Date: Sat, 24 Jun 2023 08:21:25 +0100
> 
> On Fri 23 Jun 2023 at 10:17AM +03, Eli Zaretskii wrote:
> 
> > Not in this project.  Here, the preference is the opposite one (but we
> > will gladly accept series as well).
> 
> I know, I just wanted to update Po's impression of the wider ecosystem.
                                                               ^^^^^^^^^
(Expect a comment from RMS for using that word.)

The problem with that preference is that most contributors
misunderstand how to arrange the series correctly, and end up sending
series which require extra work, because the same places were modified
several times.  On top of that, the series doesn't really allow
applying only some of the patches, which is the main raison d'être of
the technique.

To correctly subdivide a large patch into a series, one must identify
changes in the changeset that are (a) independent, i.e., can be
applied without all the rest, and in any order; and (b) changes which
_make_sense_ as separate changes, so the project might consider
applying just them, even though the rest will be rejected.

What most people do instead is they provide a series where each patch
is a step towards the solution.  First, a patch with some refactoring,
then another patch with the first aspect of the solution, another
patch with the second aspect, etc.  Such series make no sense as a
series, because the patches are not really independent; instead, they
are _incremental_.  For example, it usually makes no sense to do the
refactoring if we aren't installing the changes which need it.
Moreover, this technique frequently leads to multiple patches touching
the same places several times, so when you review the first patch, you
are looking at code that will be modified later, and risk providing
comments that are irrelevant, because a later patch in the series
rewrites that code anyway, perhaps exactly in a way that you want to
tell the contributor to use.  Basically, the only sane method of
reviewing such "series" is to apply the entire series, then produce
the unified diffs from all of them, and than review those diffs
instead of the patch series.

Since the correct way of breaking patches into individual ones is hard
to explain, and requires good knowledge of the project's conventions
and practices to determine how to break the large patch, I find it
easier to ask contributors to not bother with series and submit a
single large patch.  IME, it's TRT in the majority of cases anyway,
especially with contributions that provide some minor change or fix,
and it definitely makes patch review much more convenient and easy
than the opposite preference.

Re: contributing to Emacs

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

Hi,

>> Have you considered updating mailman to mailman3 plus hyperkitty? The
>> new hyperkitty interface is easier to use and works better different
>> screen layouts such as mobile or high dpi.
>>
>> Also considering that Mailman2 uses Python 2 which is EOL.
>
> Mailman is not maintained by us, it's infrastructure used by the
> entire GNU Project.  If you want to suggest changes in that, please
> post to mailman@gnu.org and savannah-hackers-public@gnu.org.
>
> The Emacs project just uses the infrastructure provided by GNU.
>
> Also, the bug tracker is not built on mailman, it just sends messages
> to a mailing list, but that's all.

I don't know what you mean with not "built on mailman", but the bug
tracker on debbugs.gnu.org uses mailman for moderation. However, it is
not the mailman instance of the GNU project, but an own one.

JFTR, although this might be tangent information to this thread.

Best regards, Michael.

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sat, 2023-06-24 at 10:43 +0300, Eli Zaretskii wrote:
> 
> What most people do instead is they provide a series where each patch
> is a step towards the solution.  First, a patch with some refactoring,
> then another patch with the first aspect of the solution, another
> patch with the second aspect, etc.  Such series make no sense as a
> series, because the patches are not really independent; instead, they
> are _incremental_.  For example, it usually makes no sense to do the
> refactoring if we aren't installing the changes which need it.

I might be misunderstanding something, but as someone who regularly posts such
"incremental changes" at my work, I tend to disagree that such refactoring will
not be needed if the final change not applied.

The point of such refactoring is improving existing code. Like, separating
larger functions to smaller one, encapsulating logic and reducing variables
scope, constifying stuff… I agree that the driving force for these changes is
making some final change that adds some new feature or something… However, even
if the final feature does not make it through, the changes per se make code
easier to maintain and review. I even had multiple occasions at work where I was
making such incremental changes, but the final point I was doing them for was
never reached for one reason or another. But we still applied the refactoring,
because it's an improvement nonetheless.

> Moreover, this technique frequently leads to multiple patches touching
> the same places several times, so when you review the first patch, you
> are looking at code that will be modified later, and risk providing
> comments that are irrelevant, because a later patch in the series
> rewrites that code anyway, perhaps exactly in a way that you want to
> tell the contributor to use.

Actually, this is exactly how review works. It *does not* matter if later code
rewrote the same place again. If you found a problem in *current* commit/patch,
that means that exactly *this* commit/patch needs to be fixed.

That α) simplifies review, and β) makes sure that if later commit gets reverted
at some point, the code that is left would still be valid.

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: luangruo@yahoo.com, arne_bab@web.de, ams@gnu.org, emacs-devel@gnu.org
> Date: Sat, 24 Jun 2023 15:36:20 +0300
> 
> On Sat, 2023-06-24 at 10:43 +0300, Eli Zaretskii wrote:
> > 
> > What most people do instead is they provide a series where each patch
> > is a step towards the solution.  First, a patch with some refactoring,
> > then another patch with the first aspect of the solution, another
> > patch with the second aspect, etc.  Such series make no sense as a
> > series, because the patches are not really independent; instead, they
> > are _incremental_.  For example, it usually makes no sense to do the
> > refactoring if we aren't installing the changes which need it.
> 
> I might be misunderstanding something, but as someone who regularly posts such
> "incremental changes" at my work, I tend to disagree that such refactoring will
> not be needed if the final change not applied.

You might disagree, but such considerations and decisions are the
prerogative of the project maintainers, not of the contributors.  In
Emacs, we don't like code churn unless it has a purpose, and
refactoring by itself doesn't justify the downsides of making the code
less familiar to those who read and audit it very frequently, and need
to be able to find the relevant parts as fast as possible.  Keep in
mind that this is an old project with code written by excellent
programmers (I exclude myself from that group, obviously), and the
code is generally in very good shape.  Thus, refactoring is not really
an urgent need, like it might be in an average project out there.

Again, you might disagree, but this is not your call.  My point was
precisely that since it is not the call of the contributors, they
cannot be expected to make those decisions on our behalf, and are
therefore better off not dividing the patches into several individual
ones.

> > Moreover, this technique frequently leads to multiple patches touching
> > the same places several times, so when you review the first patch, you
> > are looking at code that will be modified later, and risk providing
> > comments that are irrelevant, because a later patch in the series
> > rewrites that code anyway, perhaps exactly in a way that you want to
> > tell the contributor to use.
> 
> Actually, this is exactly how review works. It *does not* matter if later code
> rewrote the same place again. If you found a problem in *current* commit/patch,
> that means that exactly *this* commit/patch needs to be fixed.

I think you misunderstood what I tried to explain, because you are
actually saying that wasting effort on reviewing of and commenting on
code that will be changed or reverted by a further commit is a Good
Thing.

But even if you did understand my point, are you really going to tell
me how to review patches?  Don't you think it's my decision, and not
yours?  In the project of which you are the maintainer, you can define
the procedures and the preferences as you see fit (and I will follow
if I need to contribute, as I do, for example, with GDB, where they do
want patch series), but you cannot force me use the procedures that
you find convenient and natural in a project where I need to review so
many patches each day.

Bottom line: I explained the rationale so that people could understand
the preferences better, and in particular realize that they aren't
arbitrary.  I hope that better understanding will make it easier to
respect the preferences, even if some don't agree with them.

Re: contributing to Emacs

[Philip Kaludercic]

Sean Whitton <spwhitton@spwhitton.name> writes:

> Hello,
>
> On Sun 18 Jun 2023 at 10:22AM GMT, Philip Kaludercic wrote:
>
>> One idea (but I don't know if this is practicable), is to use the
>> configure script to set up Git's `sendemail.to' option or to add
>> `vc-default-patch-addressee' to .dir-locals.el.
>
> I thought we were going to do that anyway, just as soon as enough time
> had passed that people are not going to get unsafe local variable
> popups?

That was (is?) the plan, but I guess it was just delayed because people
on older versions got irritated by the unsafe variable warnings, and
then everyone forgot.

-- 
Philip Kaludercic

Re: contributing to Emacs

[Konstantin Kharlamov]

On Sat, 2023-06-24 at 17:44 +0300, Eli Zaretskii wrote:
> > From: Konstantin Kharlamov <hi-angel@yandex.ru>
> > Cc: luangruo@yahoo.com, arne_bab@web.de, ams@gnu.org, emacs-devel@gnu.org
> > Date: Sat, 24 Jun 2023 15:36:20 +0300
> > 
> > On Sat, 2023-06-24 at 10:43 +0300, Eli Zaretskii wrote:
> > > 
> > > What most people do instead is they provide a series where each patch
> > > is a step towards the solution.  First, a patch with some refactoring,
> > > then another patch with the first aspect of the solution, another
> > > patch with the second aspect, etc.  Such series make no sense as a
> > > series, because the patches are not really independent; instead, they
> > > are _incremental_.  For example, it usually makes no sense to do the
> > > refactoring if we aren't installing the changes which need it.
> > 
> > I might be misunderstanding something, but as someone who regularly posts
> > such
> > "incremental changes" at my work, I tend to disagree that such refactoring
> > will
> > not be needed if the final change not applied.
> 
> You might disagree, but such considerations and decisions are the
> prerogative of the project maintainers, not of the contributors.  In
> Emacs, we don't like code churn unless it has a purpose, and
> refactoring by itself doesn't justify the downsides of making the code
> less familiar to those who read and audit it very frequently, and need
> to be able to find the relevant parts as fast as possible.  Keep in
> mind that this is an old project with code written by excellent
> programmers (I exclude myself from that group, obviously), and the
> code is generally in very good shape.  Thus, refactoring is not really
> an urgent need, like it might be in an average project out there.
> 
> Again, you might disagree, but this is not your call.  My point was
> precisely that since it is not the call of the contributors, they
> cannot be expected to make those decisions on our behalf, and are
> therefore better off not dividing the patches into several individual
> ones.
> 
> > > Moreover, this technique frequently leads to multiple patches touching
> > > the same places several times, so when you review the first patch, you
> > > are looking at code that will be modified later, and risk providing
> > > comments that are irrelevant, because a later patch in the series
> > > rewrites that code anyway, perhaps exactly in a way that you want to
> > > tell the contributor to use.
> > 
> > Actually, this is exactly how review works. It *does not* matter if later
> > code
> > rewrote the same place again. If you found a problem in *current*
> > commit/patch,
> > that means that exactly *this* commit/patch needs to be fixed.
> 
> I think you misunderstood what I tried to explain, because you are
> actually saying that wasting effort on reviewing of and commenting on
> code that will be changed or reverted by a further commit is a Good
> Thing.

I did not say that.

> But even if you did understand my point, are you really going to tell
> me how to review patches?  Don't you think it's my decision, and not
> yours?  In the project of which you are the maintainer, you can define
> the procedures and the preferences as you see fit (and I will follow
> if I need to contribute, as I do, for example, with GDB, where they do
> want patch series), but you cannot force me use the procedures that
> you find convenient and natural in a project where I need to review so
> many patches each day.

Neither I said how *you* should review patches. You seem to be out of context:
you previous email was a reply to Sean's one-sentence email that they is talking
about the wider ecosystem. And your next reply was not in Emacs-only context,
but instead you were explaining problems with the wider approach. And so my
explanation about code review practices is also in general.

I did not expect you would start applying the practices used in "the wider
ecosystem", because you clearly seem to be fine with how it works for you. My
reply was just an explanation of why other projects do what they are doing.

(also, due to this misunderstanding I opted not to elaborate further on the
other text above, because you seem to be taking this a bit personally)

Re: contributing to Emacs

[Eli Zaretskii]

> From: Konstantin Kharlamov <hi-angel@yandex.ru>
> Cc: spwhitton@spwhitton.name, luangruo@yahoo.com, arne_bab@web.de,
>  ams@gnu.org,  emacs-devel@gnu.org
> Date: Sat, 24 Jun 2023 19:17:34 +0300
> 
> > But even if you did understand my point, are you really going to tell
> > me how to review patches?  Don't you think it's my decision, and not
> > yours?  In the project of which you are the maintainer, you can define
> > the procedures and the preferences as you see fit (and I will follow
> > if I need to contribute, as I do, for example, with GDB, where they do
> > want patch series), but you cannot force me use the procedures that
> > you find convenient and natural in a project where I need to review so
> > many patches each day.
> 
> Neither I said how *you* should review patches. You seem to be out of context:
> you previous email was a reply to Sean's one-sentence email that they is talking
> about the wider ecosystem. And your next reply was not in Emacs-only context,
> but instead you were explaining problems with the wider approach. And so my
> explanation about code review practices is also in general.

Then you did misunderstand, and if my wording somehow caused that, I
apologize.  I described the rationale for the preference of this
project to have contributions submitted as a single patch.

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Google operates a large news server that can only be used through their
  > web page.  But there are many other sites in existence, as always.

That is good news.  I had heard otherwise.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The Emacs developers are not in charge of how the FSF handles mailing
lists.  It handles all its mailing lists with the same software.

This is not a useful place to have a discussion about that,
but I don't know what list might be a good place for it.  Sorry.
-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Sean Whitton]

Hello,

On Sat 24 Jun 2023 at 10:43AM +03, Eli Zaretskii wrote:

> The problem with that preference is that most contributors
> misunderstand how to arrange the series correctly, and end up sending
> series which require extra work, because the same places were modified
> several times.  On top of that, the series doesn't really allow
> applying only some of the patches, which is the main raison d'être of
> the technique.
>
> To correctly subdivide a large patch into a series, one must identify
> changes in the changeset that are (a) independent, i.e., can be
> applied without all the rest, and in any order; and (b) changes which
> _make_sense_ as separate changes, so the project might consider
> applying just them, even though the rest will be rejected.
>
> What most people do instead is they provide a series where each patch
> is a step towards the solution.  First, a patch with some refactoring,
> then another patch with the first aspect of the solution, another
> patch with the second aspect, etc.  Such series make no sense as a
> series, because the patches are not really independent; instead, they
> are _incremental_.  For example, it usually makes no sense to do the
> refactoring if we aren't installing the changes which need it.
> Moreover, this technique frequently leads to multiple patches touching
> the same places several times, so when you review the first patch, you
> are looking at code that will be modified later, and risk providing
> comments that are irrelevant, because a later patch in the series
> rewrites that code anyway, perhaps exactly in a way that you want to
> tell the contributor to use.  Basically, the only sane method of
> reviewing such "series" is to apply the entire series, then produce
> the unified diffs from all of them, and than review those diffs
> instead of the patch series.
>
> Since the correct way of breaking patches into individual ones is hard
> to explain, and requires good knowledge of the project's conventions
> and practices to determine how to break the large patch, I find it
> easier to ask contributors to not bother with series and submit a
> single large patch.  IME, it's TRT in the majority of cases anyway,
> especially with contributions that provide some minor change or fix,
> and it definitely makes patch review much more convenient and easy
> than the opposite preference.

This all makes sense.  Separating changes usefully is a skill that
people have to acquire.  And it's reasonable to conclude from experience
that enough people get it wrong that it is better to ask people not to
do it at all.

I do disagree that the main reason for separating them is to allow
applying only some of them.  I think making review easier, and improving
the level of detail in the VCS history, are more singificant reasons.

-- 
Sean Whitton

Re: contributing to Emacs

[Sean Whitton]

Hello,

On Sat 24 Jun 2023 at 03:37PM GMT, Philip Kaludercic wrote:

> Sean Whitton <spwhitton@spwhitton.name> writes:
>
>> Hello,
>>
>> On Sun 18 Jun 2023 at 10:22AM GMT, Philip Kaludercic wrote:
>>
>>> One idea (but I don't know if this is practicable), is to use the
>>> configure script to set up Git's `sendemail.to' option or to add
>>> `vc-default-patch-addressee' to .dir-locals.el.
>>
>> I thought we were going to do that anyway, just as soon as enough time
>> had passed that people are not going to get unsafe local variable
>> popups?
>
> That was (is?) the plan, but I guess it was just delayed because people
> on older versions got irritated by the unsafe variable warnings, and
> then everyone forgot.

Let's go ahead now?

-- 
Sean Whitton

Re: contributing to Emacs

[Corwin Brust]

On Sat, Jun 24, 2023 at 9:25 PM Richard Stallman <rms@gnu.org> wrote:
>
> This is not a useful place to have a discussion about that,
> but I don't know what list might be a good place for it.  Sorry.

Speaking from a savannah standpoint, there is no (public) mailing list
for FSF/GNU infrastructure discussion, at the moment.

Please write to mailman@gnu.org as the official place to contact
mailman admins.  This will also reach the GNU vols and FSF sys admins
who need to be kept in the loop as changes are made.

Re: contributing to Emacs

[Björn Bidar]

Corwin Brust <corwin@bru.st> writes:

R> On Sat, Jun 24, 2023 at 9:25 PM Richard Stallman <rms@gnu.org> wrote:
>>
>> This is not a useful place to have a discussion about that,
>> but I don't know what list might be a good place for it.  Sorry.
>
> Speaking from a savannah standpoint, there is no (public) mailing list
> for FSF/GNU infrastructure discussion, at the moment.
>
> Please write to mailman@gnu.org as the official place to contact
> mailman admins.  This will also reach the GNU vols and FSF sys admins
> who need to be kept in the loop as changes are made.

Ok I will summarize my point to them and cc the list.

In this thread we got sidetracked and talked about improving the
accessibility of contributing to Emacs (and thous all Gnu projects in
this case).

Gnu still uses Mailman2 which uses Python2 which is EOL.

Is there a plan to upgrade to Mailman3? Doing so and also enabling
Hyperkitty could help the accessibility because of a more modern ui that
helps people on different screen resolutions and less familiarity of
using email.


Br,

Björn Bidar

Re: contributing to Emacs

[Ian Kelling]

Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Corwin Brust <corwin@bru.st> writes:
>
> R> On Sat, Jun 24, 2023 at 9:25 PM Richard Stallman <rms@gnu.org> wrote:
>>>
>>> This is not a useful place to have a discussion about that,
>>> but I don't know what list might be a good place for it.  Sorry.
>>
>> Speaking from a savannah standpoint, there is no (public) mailing list
>> for FSF/GNU infrastructure discussion, at the moment.
>>
>> Please write to mailman@gnu.org as the official place to contact
>> mailman admins.  This will also reach the GNU vols and FSF sys admins
>> who need to be kept in the loop as changes are made.
>
> Ok I will summarize my point to them and cc the list.
>
> In this thread we got sidetracked and talked about improving the
> accessibility of contributing to Emacs (and thous all Gnu projects in
> this case).
>
> Gnu still uses Mailman2 which uses Python2 which is EOL.
>
> Is there a plan to upgrade to Mailman3? Doing so and also enabling
> Hyperkitty could help the accessibility because of a more modern ui that
> helps people on different screen resolutions and less familiarity of
> using email.

Yes, we, the FSF tech team, plan to upgrade to Mialman 3 this year. And
also deploy https://public-inbox.org/README.html. We are open to
volunteer help.  https://www.fsf.org/volunteer links to
https://libreplanet.org/wiki/Group:FSF:Tech_Team_Volunteers

-- 
Ian Kelling | Senior Systems Administrator, Free Software Foundation
GPG Key: B125 F60B 7B28 7FF6 A2B7  DF8F 170A F0E2 9542 95DF
https://fsf.org | https://gnu.org

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Please write to mailman@gnu.org as the official place to contact
  > mailman admins.  This will also reach the GNU vols and FSF sys admins
  > who need to be kept in the loop as changes are made.

We are always looking for skilled GNU/Linux sysadmins to volunteer to
help in this work.  Would you be willing to join in part time?  Please
write to sysadmin@gnu.org.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Yuchen Pei]

On Mon 2023-06-26 02:31:12 +0300, Björn Bidar wrote:

> Is there a plan to upgrade to Mailman3? Doing so and also enabling
> Hyperkitty could help the accessibility because of a more modern ui that
> helps people on different screen resolutions and less familiarity of
> using email.

Can you elaborate on the accessibility issue, especially how is the
mailman 2 archive web interface not as accessible?

One problem with Hyperkitty is that it requires javascript to display
any message, which is makes it kind of useless in non-js browsers like
eww and lynx.

Best,
Yuchen

-- 
PGP Key: 47F9 D050 1E11 8879 9040  4941 2126 7E93 EF86 DFD0
          <https://ypei.org/assets/ypei-pubkey.txt>

Re: contributing to Emacs

[Corwin Brust]

On Tue, Jun 27, 2023 at 6:08 AM Yuchen Pei <id@ypei.org> wrote:
>
> One problem with Hyperkitty is that it requires javascript to display

Hi Everyone,

As Richard has said, there's little or no value in discussion of
general infrastructure (or even mail infra specifically) on this list.
FTR, concerns like "some of us use text browsers and/or don't want to
run any javascript at all" is something that the sysadmin teams all
understand very well about our community.

If you have thoughts or suggestions I'd encourage you to write Ian and
the other FSF and GNU vols who help with mail infra directly at
mailman@gnu.org

Thanks & regards,
Corwin

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Please write to mailman@gnu.org as the official place to contact
  > mailman admins.  This will also reach the GNU vols and FSF sys admins
  > who need to be kept in the loop as changes are made.

I wrote this:

    We are always looking for skilled GNU/Linux sysadmins to volunteer to
    help in this work.  Would you be willing to join in part time?  Please
    write to sysadmin@gnu.org.

But what I really want to say is this:

We are always looking for skilled GNU/Linux sysadmins to volunteer
to help in this work.  Would any of you be willing to join in part
time?  Please write to sysadmin@gnu.org.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Björn Bidar]

Just answering once here as other already mentioned this is wrong place
although it's related.

Yuchen Pei <id@ypei.org> writes:

> On Mon 2023-06-26 02:31:12 +0300, Björn Bidar wrote:
>
>> Is there a plan to upgrade to Mailman3? Doing so and also enabling
>> Hyperkitty could help the accessibility because of a more modern ui that
>> helps people on different screen resolutions and less familiarity of
>> using email.
>
> Can you elaborate on the accessibility issue, especially how is the
> mailman 2 archive web interface not as accessible?

Scaling doesn't work for high dpi displays, smaller displays or those
that use touch input such as phones.

Subjectively it is also an issue that so few content is on a page
requiring to click to the next page for each message.

> One problem with Hyperkitty is that it requires javascript to display
> any message, which is makes it kind of useless in non-js browsers like
> eww and lynx.

If I understand correctly there was some improvements on that recently:
https://gitlab.com/mailman/hyperkitty/-/merge_requests/418

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > One problem with Hyperkitty is that it requires javascript to display
  > any message, which is makes it kind of useless in non-js browsers like
  > eww and lynx.

Features that require Javascript are totallky unacceptable if the JS
code is nonfree (see https://gnu.org/philosophy/javascript-trap.html)
and problematical even if the JS code is free
(see https://gnu.org/philosophy/wwworst-app-store.html).

We should avoid web features that send JS code, whenever possible.
Sending code to run immediately in the user's computer, in a way that
gives the user community no feasible opportunity to study the code and
release modified versions that people have a real option to use,
undermines the freedom of free software.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Björn Bidar]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > One problem with Hyperkitty is that it requires javascript to display
>   > any message, which is makes it kind of useless in non-js browsers like
>   > eww and lynx.
>
> Features that require Javascript are totallky unacceptable if the JS
> code is nonfree (see https://gnu.org/philosophy/javascript-trap.html)
> and problematical even if the JS code is free
> (see https://gnu.org/philosophy/wwworst-app-store.html).


Why do you assume JavaScript = nonfree? Mailman3-Hyperkitty is free
software.

> We should avoid web features that send JS code, whenever possible.
> Sending code to run immediately in the user's computer, in a way that

Besides avoiding JavaScript in modern web is impossible in 99% of the
cases besides for websites that load all of their content synchronously
on the initial load of the page.

> gives the user community no feasible opportunity to study the code and
> release modified versions that people have a real option to use,
> undermines the freedom of free software.

You can't modify code of content that is loaded of from other computers,
the entity that hosts a web application such as Hyperkitty is in control
which JavaScript is shipped.

In such a case GPL isn't enuogh as you don't have to release modified
versions of the app, AGPL is required. 

Re: contributing to Emacs

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 3593 bytes --]


Björn Bidar <bjorn.bidar@thaodan.de> writes:

> Richard Stallman <rms@gnu.org> writes:

>>   > One problem with Hyperkitty is that it requires javascript to display
>>   > any message, which is makes it kind of useless in non-js browsers like
>>   > eww and lynx.
>>
>> Features that require Javascript are totallky unacceptable if the JS
>> code is nonfree (see https://gnu.org/philosophy/javascript-trap.html)
>> and problematical even if the JS code is free
>> (see https://gnu.org/philosophy/wwworst-app-store.html).
>
> Why do you assume JavaScript = nonfree? Mailman3-Hyperkitty is free software.

If he had assumed that, the second part of the sentence (problematic
even if free) would not make sense.

⇒ just quoting policy, not implying something about hyperkitty.

>> We should avoid web features that send JS code, whenever possible.
>> Sending code to run immediately in the user's computer, in a way that
>
> Besides avoiding JavaScript in modern web is impossible in 99% of the
> cases besides for websites that load all of their content synchronously
> on the initial load of the page.

While this is true in this very precise wording, the large majority of
websites that use Javascript can be implemented such that all of their
content is loaded on initial page load — including interactivity that
can be provided via CSS and standard form-validation.

The advantage of using that approach is that it usually degrades more
gracefully when using simpler frontends like lynx or ewww — I’ve been
limited to a text terminal quite a few times already while trying to
find answers to a problem and being able to read bug reports from a
browser that does not support JS is very useful for that.

(that said: if JS is used for progressive enhancement and the site is
 usable without JS, this just uses more of the capabilities of powerful
 clients without locking out those in simpler browsers
 https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement )

>> gives the user community no feasible opportunity to study the code and
>> release modified versions that people have a real option to use,
>> undermines the freedom of free software.
>
> You can't modify code of content that is loaded of from other computers,
> the entity that hosts a web application such as Hyperkitty is in control
> which JavaScript is shipped.
>
> In such a case GPL isn't enuogh as you don't have to release modified
> versions of the app, AGPL is required. 

This has also been discussed a lot already and is addressed in a third
article:
https://www.gnu.org/philosophy/network-services-arent-free-or-nonfree.html

«In this case, we call it Service as a Software Substitute, or SaaSS (we
coined that to be less vague and general than “Software as a Service”),
and such a service is always a bad thing. … However, most services'
principal functions are communicating or publishing information; they
are nothing like running any program yourself, so they are not SaaSS.
They could not be replaced by your copy of a program, either; a program
running in your own computers, used solely by you and isolated from
others, is not communicating with anyone else.»

@RMS: this article is not linked in
      https://www.gnu.org/philosophy/javascript-trap.html
      but it appears that it would be useful to link it there, maybe
      in the sentence “We are addressing the server issue separately.”

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Features that require Javascript are totallky unacceptable if the JS
  > > code is nonfree (see https://gnu.org/philosophy/javascript-trap.html)
  > > and problematical even if the JS code is free
  > > (see https://gnu.org/philosophy/wwworst-app-store.html).


  > Why do you assume JavaScript = nonfree? Mailman3-Hyperkitty is free
  > software.

I don't assume that.  In fact, I said explicitly that I don't.  I said,

> Features that require Javascript are totallky unacceptable if the JS
> code is nonfree (see https://gnu.org/philosophy/javascript-trap.html)
> and problematical even if the JS code is free
> (see https://gnu.org/philosophy/wwworst-app-store.html).

You're arguing against a moral issue based on practical convenience.
For the free software movement, moral issues are the most important.

  > Besides avoiding JavaScript in modern web is impossible in 99% of the
  > cases besides for websites that load all of [what they display] synchronously
  > on the initial load of the page.

Web sites hand a method for handling that in 2000: divide the material
into pages in a sensible way, and show each page completely when the user
goes there.

  > You can't modify code... that is loaded of from other computers,

That ie exactly the problem I mentioned.  This is why it is bad
for web sites to send code to execute in the user's browser.

  > the entity that hosts a web application such as Hyperkitty is in control
  > which JavaScript is shipped.

Yes, exactly.  That why Hyperkitty is fundamentally morally flawed.




-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > @RMS: this article is not linked in
  >       https://www.gnu.org/philosophy/javascript-trap.html
  >       but it appears that it would be useful to link it there, maybe
  >       in the sentence “We are addressing the server issue separately.”

Interesting idea.

I was skeptical about it, because SaaSS has nothing particularly to do with
use of JS.  That computing in the web site could be done with any sort
of computing method.

But it could be useful to mention at the start of the page that there
two kinds of problems a web page can have.

Thanks.
-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: contributing to Emacs

[Yuchen Pei]

On Wed 2023-06-28 23:03:34 -0400, Richard Stallman wrote:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > One problem with Hyperkitty is that it requires javascript to display
>   > any message, which is makes it kind of useless in non-js browsers like
>   > eww and lynx.
>
> Features that require Javascript are totallky unacceptable if the JS
> code is nonfree (see https://gnu.org/philosophy/javascript-trap.html)
> and problematical even if the JS code is free
> (see https://gnu.org/philosophy/wwworst-app-store.html).
>
> We should avoid web features that send JS code, whenever possible.
> Sending code to run immediately in the user's computer, in a way that
> gives the user community no feasible opportunity to study the code and
> release modified versions that people have a real option to use,
> undermines the freedom of free software.

This is why I think it would be a good idea to write emacs/elisp client
packages to replace web/javascript clients. The former is much more free
than javascript you can't change. Examples of such packages include
osm.el[1] for openstreetmap, sx.el[2] for stackexchange, org-jira[3] for
JIRA , as well as the buildbot package I'm submitting to ELPA[4]. It
does not solve the server side issue (SaaSS), but it does offer complete
freedom on the client side.

[1] https://github.com/minad/osm
[2] https://github.com/vermiculus/sx.el
[3] https://github.com/ahungry/org-jira
[4] https://g.ypei.me/buildbot.el.git/about/

Best,
Yuchen

-- 
PGP Key: 47F9 D050 1E11 8879 9040  4941 2126 7E93 EF86 DFD0
          <https://ypei.org/assets/ypei-pubkey.txt>

Re: contributing to Emacs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > This is why I think it would be a good idea to write emacs/elisp client
  > packages to replace web/javascript clients. The former is much more free
  > than javascript you can't change.

I agree.

  >  It
  > does not solve the server side issue (SaaSS), but it does offer complete
  > freedom on the client side.

If a service does SaaSS, that problem is inherent in the server's
essence.  Nothing we might do on the client side will alter it.
I just don't use those servers.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)