Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Stefan Monnier]

> +(defun file-tree-walk (dir action &rest args)
> +  "Walk DIR executing ACTION.  Each call gets as arguments DIR, a file path,

The first line should be self-sufficient, so better add a newline after
the ".".

> +and optional ARGS. The ACTION is applied to each subdirectory
                    ^^
Use two spaces to separate sentences.

> +before descending into it, and if nil is returned at that point
> +the descent will be prevented.  Directory entries are sorted with
> +string-lessp"
             ^^^
Don't forget to punctuate your docstrings.

I think C-u M-x checkdoc-current-buffer RET would have caught all those.

We really should try and setup flymake.el automatically for Elisp
buffers to flag those things on-the-fly.

> +  (cond ((file-directory-p dir)
> +	 (or (char-equal ?/ (aref dir (1- (length dir))))
> +	     (setq dir (file-name-as-directory dir)))
> +	 (let ((lst (directory-files dir nil nil t))

Experience taught me that file-name-all-completions followed by testing
the presence of a trailing "/" is *much* faster because calling
file-directory-p on each entry ends up costly.

I got this trick from Eshell's code for ** globbing, where the speed
difference was a factor 10 when I tested it.


        Stefan

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eric S. Raymond]

Stefan Monnier <monnier@iro.umontreal.ca>:
> > +(defun file-tree-walk (dir action &rest args)
> > +  "Walk DIR executing ACTION.  Each call gets as arguments DIR, a file path,
> 
> The first line should be self-sufficient, so better add a newline after
> the ".".
> 
> > +and optional ARGS. The ACTION is applied to each subdirectory
>                     ^^
> Use two spaces to separate sentences.
> 
> > +before descending into it, and if nil is returned at that point
> > +the descent will be prevented.  Directory entries are sorted with
> > +string-lessp"
>              ^^^
> Don't forget to punctuate your docstrings.
> 
> I think C-u M-x checkdoc-current-buffer RET would have caught all those.
> 
> We really should try and setup flymake.el automatically for Elisp
> buffers to flag those things on-the-fly.
> 
> > +  (cond ((file-directory-p dir)
> > +	 (or (char-equal ?/ (aref dir (1- (length dir))))
> > +	     (setq dir (file-name-as-directory dir)))
> > +	 (let ((lst (directory-files dir nil nil t))
> 
> Experience taught me that file-name-all-completions followed by testing
> the presence of a trailing "/" is *much* faster because calling
> file-directory-p on each entry ends up costly.
> 
> I got this trick from Eshell's code for ** globbing, where the speed
> difference was a factor 10 when I tested it.

I can fix these things easily enough, of course.  But since you got annoyed
about the last commit message, I need to know of this kind of fix requires
a ChangeLog entry.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Stefan Monnier]

> I can fix these things easily enough, of course.  But since you got annoyed
> about the last commit message, I need to know of this kind of fix requires
> a ChangeLog entry.

Every commit should come with a commit message, yes.
And every commit message should use the ChangeLog format (plus
a summary if appropriate).
And every commit message should be duplicated in the ChangeLog file.


        Stefan

Metaproblem, part 3

[Eric S. Raymond]

Stefan Monnier <monnier@iro.umontreal.ca>:
> Every commit should come with a commit message, yes.
> And every commit message should use the ChangeLog format (plus
> a summary if appropriate).
> And every commit message should be duplicated in the ChangeLog file.

But Paul Eggert said: "It's not needed for one-liners."

So not only do we have commenting conventions that are duplicative,
fussy, and undocumented, the senior developers seem not to agree on the
details.

Hello?  Hello?  Am I the only one that sees a problem here?

I've been hacking on Emacs since before it was GNU Emacs and now *I*
feel like I'm walking on eggshells and the overhead of contributing is
irritatingly high.  How much more forbidding do you suppose it is for
J. Random Junior Hacker?

Put differently: #emacs has over 500 regulars.  It appears to me that
no more than a dozen, if that, have contributed a line of code to the
development tree.  Does nobody in the project leadership ever think
about what that implies?

My next commit will be me diligently attempting to comply with
Stefan's instruction.  And thinking that a hell of a lot besides the
version-control system needs to change around here.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: Metaproblem, part 3

[Stefan Monnier]

> But Paul Eggert said: "It's not needed for one-liners."

That meant that if the ChangeLog is a one-liner, you can use it as
the summary.

> My next commit will be me diligently attempting to comply with
> Stefan's instruction.

As explained earlier, write the ChangeLog first and then use C-c C-a
from the *VC-Log* buffer.


        Stefan

Re: Metaproblem, part 3

[Eli Zaretskii]

> Date: Wed, 3 Dec 2014 16:54:26 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: emacs-devel@gnu.org
> 
> Stefan Monnier <monnier@iro.umontreal.ca>:
> > Every commit should come with a commit message, yes.
> > And every commit message should use the ChangeLog format (plus
> > a summary if appropriate).
> > And every commit message should be duplicated in the ChangeLog file.
> 
> But Paul Eggert said: "It's not needed for one-liners."

Yes, a single one line ChangeLog-style entry can serve also as a
summary for itself.

> So not only do we have commenting conventions that are duplicative,
> fussy, and undocumented, the senior developers seem not to agree on the
> details.
> 
> Hello?  Hello?  Am I the only one that sees a problem here?

There is no problem, see above.

> I've been hacking on Emacs since before it was GNU Emacs and now *I*
> feel like I'm walking on eggshells and the overhead of contributing is
> irritatingly high.  How much more forbidding do you suppose it is for
> J. Random Junior Hacker?

They usually get told once, or even just read the previous commit log
messages and understand the style by themselves.

> Put differently: #emacs has over 500 regulars.  It appears to me that
> no more than a dozen, if that, have contributed a line of code to the
> development tree.  Does nobody in the project leadership ever think
> about what that implies?

We do.  I do.

> My next commit will be me diligently attempting to comply with
> Stefan's instruction.  And thinking that a hell of a lot besides the
> version-control system needs to change around here.

I agree.  The question, as always, is what should change and in what
ways.  "The devil is in the details."

Re: Metaproblem, part 3

[Paul Eggert]

Eric S. Raymond wrote:
> Am I the only one that sees a problem here?

As I mentioned earlier, I use vc-dwim.  You might want to try it out.  It'll 
save you the hassle of remembering these niggly details, since it generates the 
commit message automatically from the ChangeLog entries.

I've also suggested that we generate the ChangeLog automatically.  This would 
address the problem even better, since it would be simpler for most contributors 
than our current practice of having to deal with vc-dwim or its equivalent to 
generate commit messages that are near-duplicates of ChangeLogs.  However, 
Stefan wanted explicit agreement from all the core developers on that, which 
I've taken as a polite "no".  (Maybe someday he'll change his mind and say 
"yes"....)

Re: Metaproblem, part 3

[Stefan Monnier]

> ChangeLogs.  However, Stefan wanted explicit agreement from all the core
> developers on that, which I've taken as a polite "no".

It's not.  It's just that I'm tired of being the maintainer.


        Stefan

Re: Metaproblem, part 3

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> It's not.  It's just that I'm tired of being the maintainer.

Eek.  That's not good.  Er...  is there anything we can do to un-tire
you somehow?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Metaproblem, part 3

[Stefan Monnier]

>> It's not.  It's just that I'm tired of being the maintainer.
> Eek.  That's not good.  Er...  is there anything we can do to un-tire
> you somehow?

You could volunteer to take over as new maintainer,


        Stefan

Re: Metaproblem, part 3

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> You could volunteer to take over as new maintainer,

I could, but I'm a total ditz, so it wouldn't really work.

I know we're a taciturn bunch of people here on emacs-devel, so we don't
compliment each other much.  But you've (along with Chong the first
years) been the best maintainer Emacs has had.  (Sorry, other
maintainers.)  So the thought that you're contemplating resigning is
kinda depressing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Metaproblem, part 3

[Paul Eggert]

On 12/04/2014 09:53 AM, Stefan Monnier wrote:
> You could volunteer to take over as new maintainer,

Hey, maybe we could ask RMS to be maintainer again.  Isn't it his turn 
again yet?

But seriously -- if there's some way we can help you recharge your 
batteries please let us know.  Sometimes all it takes is a little break, 
but often it takes more than that.

Re: Metaproblem, part 3

[Stefan Monnier]

> But seriously -- if there's some way we can help you recharge your batteries
> please let us know.

The issue is not just to recharge my batteries but to lighten the load.
I see various ways that could happen:
- Someone else could take care of GNU ELPA (look for new packages, collect
  signatures, improve the infrastructure, ...).
- More people helping deal with bug-reports at all levels: classify
  bugs, tag them, make sure we reply to each one of them, make sure we
  have enough data from the reporter, help pinpoint the actual bug,
  write a sample patch.
- Setup some kind of patch-queue-manager so we can review patches and
  let the pqm do the commit/push itself.
- I find the bug-tracker not helpful enough.  Not sure if it's my fault
  for not using it well enough, maybe.  I keep feeling like I can't get
  a good overview of which bugs I should focus on, and to make sure all
  bugs receive enough attention (I hate this constant feeling I have
  that most bug reports go simply unanswered).
- Spend less time arguing and more time coding.  E.g. package.el still
  doesn't keep track of which packages have been explicitly installed by
  the user.  There's still no code to bundle GNU ELPA packages in the
  tarball releases.
- The resistance to change on CC-mode's side didn't help my morale.

But also I think on the coding side I don't have that much to contribute
to Emacs nowadays, and it's time for someone else to take over, with
fresh new ideas.


        Stefan

Re: Metaproblem, part 3

[Stephen J. Turnbull]

Stefan Monnier writes:

 > - The resistance to change on CC-mode's side didn't help my morale.

That's one reason why XEmacs has a fiercely enforced rule that all
changes to external packages go through the list maintainer, whose
decisions are final.  I don't always like those decisions, but
conformance is a no-brainer with little stress.

N.B. Now that it's clear that breaking that rule means I resign,
nobody even thinks about it.

BTW, you've been a great maintainer so far.  Thanks!

Re: Metaproblem, part 3

[Glenn Morris]

Stefan,

You do a wonderful job maintaining Emacs. I can't think of anyone else
who could do it anywhere near as well, from the point of view of either
your technical accomplishments, or being so damnably nice to people...
Many thanks for all the work you put in.

I can quite understand you being tired of it.
I'm sorry that I can't help with any of the specific points you raised.
(Well, I've been trying to stay out of arguments.)
I really hope people step up in response. Eg, there seem to be several
people interested in package-related matters.

Yours really-worried-about-the-future-ly,

Re: Metaproblem, part 3

[andres.ramirez]

+1 to this.

Thanks Stefan. and Thank You guys who keep this great product and an
active community alive. I am always thinking about You guys, how do
You organize your time, not knowing details about it. I think It is a
very demanding task, besides Emacs you have Work, Family, and Life.

Even Glenn, who was very worried lately trying to release emacs
24.4. I think that process tired Chong before.

Best Regards
At Fri, 05 Dec 2014 03:06:30 -0500,
Glenn Morris wrote:
> 
> 
> Stefan,
> 
> You do a wonderful job maintaining Emacs. I can't think of anyone else
> who could do it anywhere near as well, from the point of view of either
> your technical accomplishments, or being so damnably nice to people...
> Many thanks for all the work you put in.
> 
> I can quite understand you being tired of it.
> I'm sorry that I can't help with any of the specific points you raised.
> (Well, I've been trying to stay out of arguments.)
> I really hope people step up in response. Eg, there seem to be several
> people interested in package-related matters.
> 
> Yours really-worried-about-the-future-ly,
> 
> 

Re: Metaproblem, part 3

[Stefan Monnier]

Lots of people sent their thanks, and told me how great a maintainer
I am and how nice I am, and despite the fact that some of you forgot to
mention how good I look and how well I sing, I really thank you all for
it, it's really super fun to read.


        Stefan


PS: Of course, it doesn't lighten the load very much.
PPS: And do remember that life wasn't that bad with previous
maintainers, so I'm sure things can be even better with the next.

Re: Metaproblem, part 3

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Lots of people sent their thanks, and told me how great a maintainer
> I am and how nice I am, and despite the fact that some of you forgot to
> mention how good I look and how well I sing, I really thank you all for
> it, it's really super fun to read.

Well, I can't remember having a problem with you.  If that is not an
outstanding achievement, I don't know what is.

-- 
David Kastrup

Re: Metaproblem, part 3

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> - I find the bug-tracker not helpful enough.  Not sure if it's my fault
>   for not using it well enough, maybe.  I keep feeling like I can't get
>   a good overview of which bugs I should focus on, and to make sure all
>   bugs receive enough attention (I hate this constant feeling I have
>   that most bug reports go simply unanswered).

Do you use `M-x debbugs-gnu'?  It sorts and displays bug reports based
on whether they have been responded to at all, or followed up recently.

If there's something we could add there that makes it more easy to work
with, let me know.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Metaproblem, part 3

[Stefan Monnier]

> Do you use `M-x debbugs-gnu'?

Kinda.

> It sorts and displays bug reports based on whether they have been
> responded to at all, or followed up recently.

Yes, it helps.  But there are still way too many reports in there so
I find it difficult to see which ones I should attend to.  I need to be
able to flush all those reports which are outside my field of expertise,
for example (Windows-specific, about the GUI, about the rendering, ...).

Worse yet: it doesn't fix the bugs on its own, I still have to go and
fix them by hand.


        Stefan

Re: Metaproblem, part 3

[Lars Magne Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Yes, it helps.  But there are still way too many reports in there so
> I find it difficult to see which ones I should attend to.  I need to be
> able to flush all those reports which are outside my field of expertise,
> for example (Windows-specific, about the GUI, about the rendering, ...).

The `t' command toggles a local tag that makes the bug number be
displayed in red.  I use it to mark bug reports that I have no interest
in.

> Worse yet: it doesn't fix the bugs on its own, I still have to go and
> fix them by hand.

The next version of debbugs-gnu is sure to fix that.  Any month now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Metaproblem, part 3

[Lars Magne Ingebrigtsen]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> The `t' command toggles a local tag that makes the bug number be
> displayed in red.  I use it to mark bug reports that I have no interest
> in.

I've now made the `x' command flush those, too, so that you get a
cleaner display after you've `t'agged all the reports you have no
interest in.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Metaproblem, part 3

[Alan Mackenzie]

On Thu, Dec 04, 2014 at 11:40:35PM -0500, Stefan Monnier wrote:
> > But seriously -- if there's some way we can help you recharge your batteries
> > please let us know.

> The issue is not just to recharge my batteries but to lighten the load.
> I see various ways that could happen:
   ....
> - The resistance to change on CC-mode's side didn't help my morale.

Stefan and I have discussed the relevant issues in private mail, and
they have now been resolved.

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).

Generate ChangeLogs (was: Metaproblem, part 3)

[Lars Magne Ingebrigtsen]

Paul Eggert <eggert@cs.ucla.edu> writes:

> However, Stefan wanted explicit agreement from all the core developers
> on that, which I've taken as a polite "no".  (Maybe someday he'll
> change his mind and say "yes"....)

Hey, is this where we start the explicit agreement list?

In that case, I say "yes" to start generating the ChangeLogs.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: Generate ChangeLogs

[Karl Fogel]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:
>Paul Eggert <eggert@cs.ucla.edu> writes:
>
>> However, Stefan wanted explicit agreement from all the core developers
>> on that, which I've taken as a polite "no".  (Maybe someday he'll
>> change his mind and say "yes"....)
>
>Hey, is this where we start the explicit agreement list?
>
>In that case, I say "yes" to start generating the ChangeLogs.

Same here, FWIW.

Re: Generate ChangeLogs

[Eric S. Raymond]

Karl Fogel <kfogel@red-bean.com>:
> Lars Magne Ingebrigtsen <larsi@gnus.org> writes:
> >Paul Eggert <eggert@cs.ucla.edu> writes:
> >
> >> However, Stefan wanted explicit agreement from all the core developers
> >> on that, which I've taken as a polite "no".  (Maybe someday he'll
> >> change his mind and say "yes"....)
> >
> >Hey, is this where we start the explicit agreement list?
> >
> >In that case, I say "yes" to start generating the ChangeLogs.
> 
> Same here, FWIW.

And here.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: Generate ChangeLogs

[Paul Eggert]

On 12/04/2014 07:40 AM, Lars Magne Ingebrigtsen wrote:
> In that case, I say "yes" to start generating the ChangeLogs.

Stefan wrote that he's in favor of the idea, so there's a+1 there, too.  
(I wrote the patch to do it, so it should be pretty obvious that I'm in 
favor.)

My biggest worry, to be honest, is Glenn, who tidies up ChangeLogs more 
than anyone else does.  It's more of a hassle to do that when ChangeLogs 
are generated automatically.  My own feeling is that, although I 
understand the pull of having the logs look good, our limited resources 
can be put to better use in areas other than tidying up ChangeLogs, and 
I'm willing to live with somewhat-messier ChangeLogs if we can trade 
that for a simpler workflow and/or other improvements elsewhere.

Re: Generate ChangeLogs

[Achim Gratz]

Paul Eggert writes:
> My biggest worry, to be honest, is Glenn, who tidies up ChangeLogs
> more than anyone else does.  It's more of a hassle to do that when
> ChangeLogs are generated automatically.

That's not more of a problem than it is at the moment when only the
changes to the ChangeLog were auto-generated instead of the whole
ChangeLog.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf Blofeld:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds

Re: Generate ChangeLogs

[Glenn Morris]

Paul Eggert wrote:

> My biggest worry, to be honest, is Glenn, who tidies up ChangeLogs
> more than anyone else does.  It's more of a hassle to do that when
> ChangeLogs are generated automatically.  My own feeling is that,
> although I understand the pull of having the logs look good, our
> limited resources can be put to better use in areas other than tidying
> up ChangeLogs, and I'm willing to live with somewhat-messier
> ChangeLogs if we can trade that for a simpler workflow and/or other
> improvements elsewhere.

You don't have to worry, because I'll simply stop doing that.

I feel like you mischaracterized my position as some such of obsession
with making things look pretty. Rather I care about things being
well-documented. But, good news! I don't care any more.

I wrote a more detailed response to your bug report.
Short answer: do what you like.

Re: Generate ChangeLogs

[Paul Eggert]

Glenn Morris wrote:
> I feel like you mischaracterized my position as some such of obsession
> with making things look pretty.

Although I didn't intend that interpretation, in rereading my email I now see 
that it could easily be read that way, and that I should have used language like 
"fixes ChangeLogs" instead of "tidies up ChangeLogs".  My apologies.  There's 
nothing at all wrong with fixing ChangeLogs, of course.  I'll follow up further 
at Bug#19113.

Re: Generate ChangeLogs

[Ted Zlatanov]

On Thu, 04 Dec 2014 16:40:49 +0100 Lars Magne Ingebrigtsen <larsi@gnus.org> wrote: 

LMI> Hey, is this where we start the explicit agreement list?

LMI> In that case, I say "yes" to start generating the ChangeLogs.

I agree. I haven't reviewed Paul's patches. For instance, I don't know
how hard it will be to override specific commit messages, or to amend
them. And we need server-side hooks to prevent badly formatted commit
messages.

But those are technological problems we can overcome, so I'm not worried
about them.

Ted

Re: Metaproblem, part 3

[Phillip Lord]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Stefan Monnier <monnier@iro.umontreal.ca>:
>> Every commit should come with a commit message, yes.
>> And every commit message should use the ChangeLog format (plus
>> a summary if appropriate).
>> And every commit message should be duplicated in the ChangeLog file.
>
> But Paul Eggert said: "It's not needed for one-liners."
>
> So not only do we have commenting conventions that are duplicative,
> fussy, and undocumented, the senior developers seem not to agree on the
> details.
>
> Hello?  Hello?  Am I the only one that sees a problem here?
>
> I've been hacking on Emacs since before it was GNU Emacs and now *I*
> feel like I'm walking on eggshells and the overhead of contributing is
> irritatingly high.  How much more forbidding do you suppose it is for
> J. Random Junior Hacker?

I would like to contribute a little, as my time and skills (both very
limited) allow. So, I've been on the mailing list for a while. I've got
the repo checkout out (on git, thanks Eric!), and am running my daily
emacs of trunk. It's take me quite a while to achieve this. I was
genuinely quite nervous about pushing to ELPA -- normally, I just push
to my own repos and if I trash then, its my problem, no one elses.

I've mailed Stefan a few times about things (out-of-band). I feel a
little guilty about this because I know his time is limited. Ultimately,
though, it's his own fault because he gives simple, clear and thoughtful
anwsers that I understand. How we has managed to survive in academia
while doing this, I don't understand.

Cheesy as it sounds, perhaps, what is needed is "mentors". So, someone
wants to fix something or change something about Emacs, they get a short
term mentor to help them through the process (both at a code level, and
at a rules of community level). So, the first piece of advice in
contribute wouldn't be "do this, do that", it would be "think of a
problem, ask for a mentor".

Eli is right, Emacs is complex because it's a big project and some of
this will remain. There may be ways to reduce the initimidation levels.

Phil

Re: Metaproblem, part 3

[João Távora]

phillip.lord@newcastle.ac.uk (Phillip Lord) writes:

> Cheesy as it sounds, perhaps, what is needed is "mentors". So, someone
> wants to fix something or change something about Emacs, they get a short
> term mentor to help them through the process (both at a code level, and
> at a rules of community level). So, the first piece of advice in
> contribute wouldn't be "do this, do that", it would be "think of a
> problem, ask for a mentor".

+1 to this. In every software project I've worked on, some form of
mentorship has proven essential in every first-time
contribution. Including projects that I started, and including Emacs
(thanks Stefan!).

</delurk>

João

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Date: Thu, 04 Dec 2014 14:32:23 +0000
> Cc: esr@thyrsus.com, emacs-devel@gnu.org
> 
> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
> 
> > Cheesy as it sounds, perhaps, what is needed is "mentors". So, someone
> > wants to fix something or change something about Emacs, they get a short
> > term mentor to help them through the process (both at a code level, and
> > at a rules of community level). So, the first piece of advice in
> > contribute wouldn't be "do this, do that", it would be "think of a
> > problem, ask for a mentor".
> 
> +1 to this. In every software project I've worked on, some form of
> mentorship has proven essential in every first-time
> contribution. Including projects that I started, and including Emacs
> (thanks Stefan!).

I also think that we have mentoring here, so I don't understand what
exactly is this gripe about.  People ask questions, both here and on
bug-gnu-emacs, and get helpful answers and guidance even when the
questions are only tangentially related to Emacs (or even not at
all).  What exactly is missing?

Or maybe I don't understand what "mentoring" is being alluded to here.

Re: Metaproblem, part 3

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joaotavora@gmail.com (João Távora)
>> Date: Thu, 04 Dec 2014 14:32:23 +0000
>> Cc: esr@thyrsus.com, emacs-devel@gnu.org
>> 
>> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
>> 
>> > Cheesy as it sounds, perhaps, what is needed is "mentors". So, someone
>> > wants to fix something or change something about Emacs, they get a short
>> > term mentor to help them through the process (both at a code level, and
>> > at a rules of community level). So, the first piece of advice in
>> > contribute wouldn't be "do this, do that", it would be "think of a
>> > problem, ask for a mentor".
>> 
>> +1 to this. In every software project I've worked on, some form of
>> mentorship has proven essential in every first-time
>> contribution. Including projects that I started, and including Emacs
>> (thanks Stefan!).
>
> I also think that we have mentoring here, so I don't understand what
> exactly is this gripe about.  People ask questions, both here and on
> bug-gnu-emacs, and get helpful answers and guidance even when the
> questions are only tangentially related to Emacs (or even not at
> all).  What exactly is missing?

As you pointed out, mentorship happens on emacs-devel and on
bug-gnu-emacs. But also as you pointed out, a lot of effort goes into
questions only tangentially related to Emacs.

The proposed mentoring would be targeted at first time code
contributions only and administered by anyone with a reasonably solid
grasp of Emacs's and GNU's red tape.

From my (limited) perspective this is frequently channeled to Stefan,
who is really good at it, but is possibly overloaded.

So what is being proposed, or what at least what I understood from
Phillip's message, is that a new broad guideline is added to the top of
the contribution guide [1] reading something like:

  "If this is your first time contributing to Emacs, ask for a mentor on
  emacs-devel first. A mentor can be anyone who has contributed to Emacs
  at least once, and will guide you through the instructions [linked]
  below, as well as any extra documentation. He/she can also answer
  specific questions about copyright assignment, version control,
  changelogs, coding style, etc."

The phrasing could be improved of course, I'm not a native
speaker. Also, perhaps the ideas of "friendliness" and "tolerance" could
be made explicit there, though "mentorship" should imply them.

Note that I'm *not* saying that having a mentor guarantees code quality
or pertinence (indeed, ideally, the mentor should be reasonably agnostic
about the contribution's pertinence, unless it really *is* a waste of
time :-) ). This is to say that reviews and discussion still take place,
but at the very least the boring bits will be taken care of, and more
frequently the first-time contributor will be on the right track.

> Or maybe I don't understand what "mentoring" is being alluded to here.

Your idea of mentoring described earlier is pretty much the same as
mine.

João

[1]: either
https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
or in the linked etc/CONTRIBUTE file

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Date: Fri, 05 Dec 2014 10:27:49 +0000
> Cc: esr@thyrsus.com, phillip.lord@newcastle.ac.uk, emacs-devel@gnu.org
> 
> As you pointed out, mentorship happens on emacs-devel and on
> bug-gnu-emacs. But also as you pointed out, a lot of effort goes into
> questions only tangentially related to Emacs.
> 
> The proposed mentoring would be targeted at first time code
> contributions only and administered by anyone with a reasonably solid
> grasp of Emacs's and GNU's red tape.
> 
> >From my (limited) perspective this is frequently channeled to Stefan,
> who is really good at it, but is possibly overloaded.
> 
> So what is being proposed, or what at least what I understood from
> Phillip's message, is that a new broad guideline is added to the top of
> the contribution guide [1] reading something like:
> 
>   "If this is your first time contributing to Emacs, ask for a mentor on
>   emacs-devel first. A mentor can be anyone who has contributed to Emacs
>   at least once, and will guide you through the instructions [linked]
>   below, as well as any extra documentation. He/she can also answer
>   specific questions about copyright assignment, version control,
>   changelogs, coding style, etc."

OK, so how would this mentoring be different from what we have now?
Does it happen in private email instead of on the list?  If it's still
on the list, do we formally tell people stay out of the
mentor/mentoree dialog and let the mentor alone handle that?  Or is
the only difference that a specific person will step forward and say
he/she will be the mentor for a particular J.R. Hacker, and all the
rest should stay as it is today?

IOW, I have a difficulty translating the above principles (with which
I agree) into practical steps that need to be made, to make the
procedure different from what it is now.  Can you please clarify?

Thanks.

Re: Metaproblem, part 3

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>>   "If this is your first time contributing to Emacs, ask for a mentor on
>>   emacs-devel first. A mentor can be anyone who has contributed to Emacs
>>   at least once, and will guide you through the instructions [linked]
>>   below, as well as any extra documentation. He/she can also answer
>>   specific questions about copyright assignment, version control,
>>   changelogs, coding style, etc."
>
> OK, so how would this mentoring be different from what we have now?

Right, the devil in is the details. So let me make a concrete
example. JR Well-Behaved Hacker reads the above guideline writes to
emacs-devel:

   Hi, I started working on some code/have an idea to add/modify a
   frankinbogen-mode to Emacs. It's my first time contributing, and I
   have no idea:

     * if it should go into Emacs or Elpa,
     * if I have to assign copyright
     * if I need commit rights or, make a branch in my clone or, send some patches
     * how to write those curious ChangeLogs/format commit messages
     * how to organize code in files
     * etc etc etc (any more?)
     
   Can anyone mentor me off-list so that my contribution can be
   evaluated?

The "I have no idea" bit could also be "I have no idea about anything"
:-D

> Does it happen in private email instead of on the list?

I would say off-list, yes

> If it's still on the list, do we formally tell people stay out of the
> mentor/mentoree dialog and let the mentor alone handle that?

It can happen on list, and we would advise people to stay out of the dialog.

> the only difference that a specific person will step forward and say
> he/she will be the mentor for a particular J.R. Hacker, and all the
> rest should stay as it is today?

Imagine that this is working already. The idea is that the next email
from JR Well-Behaved Hacker would be.

  So, I have cleaned up my frankinbogen-mode with the help of my mentor
  JR Mentor.

  The code lives at a feature branch on blabla, and even though JR
  Mentor thinks it is not very useful for him personally, he thinks that
  we can discuss it here. Would the maintainers have a look?

> IOW, I have a difficulty translating the above principles (with which
> I agree) into practical steps that need to be made, to make the
> procedure different from what it is now.  Can you please clarify?

I agree it is not *very* different from what we have now, and indeed if
it's not going to be concise and clearly different and effective, it's
best not to add the additional overhead. Which is not a lot, I think,
but it's too early to be estimating that.

I hope I did clarify a bit, but ideally others can pitch in. I think
simulating a hypothetic platonic dialog between "JR Hacker" and "JR
Mentor" would be a good format to pitch in. Phillip, what would be the
ideal dialog between mentor and mentoree be?

João

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Cc: esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
> Date: Fri, 05 Dec 2014 11:21:29 +0000
> 
> > Does it happen in private email instead of on the list?
> 
> I would say off-list, yes

If that would help newcomers, it's easy to do.  OTOH, doing that on
the list has the advantage that others can chime in and make
alternative suggestions or draw attention to details that evaded the
"main mentor".

Re: Metaproblem, part 3

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joaotavora@gmail.com (João Távora)
>> Cc: esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
>> Date: Fri, 05 Dec 2014 11:21:29 +0000
>> 
>> > Does it happen in private email instead of on the list?
>> 
>> I would say off-list, yes
>
> If that would help newcomers, it's easy to do.  OTOH, doing that on
> the list has the advantage that others can chime in and make
> alternative suggestions or draw attention to details that evaded the
> "main mentor".

An idea would be to prefix the subject line in the on-list dialog with
"[mentoring]" so people know that a newcomer is being tutored and so can
avoid contributing tangential matters or topics too advanced that will
confuse the effort. Ideally, only a maintainer or someone who is quite
sure of what he is about to say would pitch in with something like this:

    This 20-line contribution doesn't need a copyright assignment

    Don't make a feature branch for this particular one, share a link
    to you github/gitorious fork instead.

    Remember that the first line of the commit message should be in the
     XYZ format

    This contribution should be targeting ELPA, not Emacs.

These are all in the scope of red tape, and not exactly code review or
pertinence evaluation. Though in practice, and especially on-list, I
think it will be almost impossible to separate the two. I think it is
also not so desirable, so the mentor and maintainers alike should be
able to say things about code quality like from simple stuff like

    Remember to provide a docstring for this functions

to

    This has to be made to work with foo-mode and all the bar-related
    modes, that bit has to be redesigned. Have you tried using defbaz?

but everyone that sees a "[mentoring]" tag should generally avoid

    You could write a macro for that.

    Even though I'm not going to work with it, this is going to break my
    super-special use-case.

    This raises the greater question of the usefulness of quux-mode in
    general. Shouldn't we be trying to deprecate them instead using the
    zglorb-mode.?

We can leave those objections for the second phase, where perhaps the
subject like would read "[mentored]".

João

Re: Metaproblem, part 3

[Kelvin White]

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

Hello,

I am a new maintainer here, and just wanted to chime in as I've experienced
the process of getting acclimated to the common procedures and such, as a
new dev. First of all I want to say thanks to Stefan for taking the time to
help
me get started, and for his patience with my ignorance. Also, I wanted to
make
a point that the "mentorship" here on emacs-devel is great. I have asked any
question to the list I may have had and gotten prompt, helpful guidance
from
many. I also think that any change to make "mentorship" some process with
more policies to remember would not only be counter intuitive but it would
take away from the camaraderie we have here and make it seem too corporate
I think. Some things you just need to leave natural and not try to
automate,
and streamline, even though it's against our nature.

Thanks again!

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

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Cc: esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
> Date: Fri, 05 Dec 2014 12:20:47 +0000
> 
> An idea would be to prefix the subject line in the on-list dialog with
> "[mentoring]" so people know that a newcomer is being tutored and so can
> avoid contributing tangential matters or topics too advanced that will
> confuse the effort.

We can certainly try that, and see if it helps.

Re: Metaproblem, part 3

[Stephen J. Turnbull]

Eli Zaretskii writes:
 > > From: joaotavora@gmail.com (João Távora)
 > > Cc: esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
 > > Date: Fri, 05 Dec 2014 12:20:47 +0000
 > > 
 > > An idea would be to prefix the subject line in the on-list dialog with
 > > "[mentoring]" so people know that a newcomer is being tutored and so can
 > > avoid contributing tangential matters or topics too advanced that will
 > > confuse the effort.
 > 
 > We can certainly try that, and see if it helps.

You could try it, but in my experience with communities that have
evident mentoring efforts suggests that "tangential matters or topics
too advanced" are not that big a problem.  Newcomers generally detect
and ignore 2/3 or more of those posts.  If newcomers get confused by
those, they should go off-list.  If mentors detect that a newcomer is
getting confused, *they* should go off-list.

The bigger problem is the level of list traffic itself, which is
intimidating to newcomers, who often don't even want to subscribe.  If
there are people who have demonstrated interest in mentoring, a
separate list is a good idea.

Which reminds me: better than an ANNOUNCE tag in the subject line is a
separate -announce list which feeds into the main -devel list among
others.  If announcements of freezes etc double the number of
announcements (vs releases and major security events), I doubt anybody
will complain.

Re: Metaproblem, part 3

[João Távora]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

>  > We can certainly try that, and see if it helps.
>
> You could try it, but in my experience with communities that have
> evident mentoring efforts suggests that "tangential matters or topics
> too advanced" are not that big a problem.  Newcomers generally detect
> and ignore 2/3 or more of those posts.  If newcomers get confused by
> those, they should go off-list.  If mentors detect that a newcomer is
> getting confused, *they* should go off-list.

Yes, going off-list is useful. the [mentoring] tag is useful when the
effort decides to stay on-list, for some reason. IMO the benefit of
going off-list isn't avoiding distraction anyway, it's that intimacy
promotes confidence. 

The remaining things I said apply for both on-list and off-list dialog
anyway. It's those that I am unsure about, so wonder if you'd like to
comment.

> The bigger problem is the level of list traffic itself, which is
> intimidating to newcomers, who often don't even want to subscribe.  If
> there are people who have demonstrated interest in mentoring, a
> separate list is a good idea.

That should work too, but perhaps at a later phase. Right now, the
following can be done with relatively low overhead:

* Announce the mentoring idea to this list and/or to the contribution
  guide (advise newcomers to ask for a mentor on this list before
  posting code or starting a discussion).

* Detail mentor's role with some do's and don'ts. Detail non-mentor's
  role.
  
* Mentoring should be strictly on list and use [mentoring] tags?
  Off-list? Up to them?

To test the process, I can volunteer to submit a couple of reasonably
small ideas, between 100 and 300 LOC, that need a mentor (*). I have
contributed to emacs before, but got lost in the git transition and
recent discussion so I have a lot of doubts, from how to clone the
official repo, ELPA/Emacs decision, etc. The process should obviously be
Stefanless, i.e. someone should volunteer to mentor, otherwise there
will be two orphan "[mentor-request]" emails in the list, which will
also say something of the usefulness of the idea :-)

João

* I also have a bigger idea on yasnippet that is being mentored by
Stefan off-list, but that's too complex for an experiment right now.

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: joaotavora@gmail.com (João Távora)
> Cc: Eli Zaretskii <eliz@gnu.org>,  esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
> Date: Sat, 06 Dec 2014 07:07:21 +0000
> 
> To test the process, I can volunteer to submit a couple of reasonably
> small ideas, between 100 and 300 LOC, that need a mentor (*).

Please go ahead, and thanks.

Of course, to be practical, there's a need for a mentoree for each
such idea, but if that's you, then that issue is solved.

[mentor-request] a darkroom/writeroom mode for Emacs

[João Távora]

   [ This message is a "mentor request" and part of an experiment
     described in this thread:
     
          https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00541.html

     A mentor is any frequent Emacs contributor who directs newcomers to
     documentation and helps them polish code contributions, easing them
     through Emacs' specific procedures, aiming to lower the entry
     barrier to Emacs development. If possible, mentors should try to be
     reasonably agnostic to the proposal's pertinence or particular
     implementation - that can be discussed later. Discussion can happen
     in or off-list. If on-list, use a "[mentoring]" prefix to the
     subject line, so that other users can keep all but essential
     comments to a minimum. ]

Hi, I'm looking for a mentor who would help me clean up the code I have
in

   https://github.com/capitaomorte/darkroom-mode

This is my implementation of the popular "darkroom/writeroom" hack, of
which multiple versions can be found around the web. I believe mine can
be polished to make it into Emacs.

I'm looking for pointers on how to clone the Emacs repository after the
recent Git transition, whether to use Emacs or ELPA for it, plus any
other tips that increase my chances.

Waiting to hear from a mentor, or from any newcomer who wants to take
over the mentoree part of this project.

Thanks,
João

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joaotavora@gmail.com (João Távora)
>> Cc: Eli Zaretskii <eliz@gnu.org>,  esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
>> Date: Sat, 06 Dec 2014 07:07:21 +0000
>> 
>> To test the process, I can volunteer to submit a couple of reasonably
>> small ideas, between 100 and 300 LOC, that need a mentor (*).
>
> Please go ahead, and thanks.
> Of course, to be practical, there's a need for a mentoree for each
> such idea, but if that's you, then that issue is solved.

Re: [mentor-request] a darkroom/writeroom mode for Emacs

[joakim]

joaotavora@gmail.com (João Távora) writes:

>    [ This message is a "mentor request" and part of an experiment
>      described in this thread:
>      
>           https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00541.html
>
>      A mentor is any frequent Emacs contributor who directs newcomers to
>      documentation and helps them polish code contributions, easing them
>      through Emacs' specific procedures, aiming to lower the entry
>      barrier to Emacs development. If possible, mentors should try to be
>      reasonably agnostic to the proposal's pertinence or particular
>      implementation - that can be discussed later. Discussion can happen
>      in or off-list. If on-list, use a "[mentoring]" prefix to the
>      subject line, so that other users can keep all but essential
>      comments to a minimum. ]
>
> Hi, I'm looking for a mentor who would help me clean up the code I have
> in
>
>    https://github.com/capitaomorte/darkroom-mode

- Did you get a copyright  assignment yet? Your code needs to be
  assigned to FSF. See http://www.gnu.org/software/emacs/CONTRIBUTE,
  copyright assignment section.

- I think your packages will live a happy life in ELPA. Heres a pointer:
http://www.emacswiki.org/emacs/ELPA#toc2

>
> This is my implementation of the popular "darkroom/writeroom" hack, of
> which multiple versions can be found around the web. I believe mine can
> be polished to make it into Emacs.
>
> I'm looking for pointers on how to clone the Emacs repository after the
> recent Git transition, whether to use Emacs or ELPA for it, plus any
> other tips that increase my chances.
>
> Waiting to hear from a mentor, or from any newcomer who wants to take
> over the mentoree part of this project.
>
> Thanks,
> João
>
> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> From: joaotavora@gmail.com (João Távora)
>>> Cc: Eli Zaretskii <eliz@gnu.org>,  esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
>>> Date: Sat, 06 Dec 2014 07:07:21 +0000
>>> 
>>> To test the process, I can volunteer to submit a couple of reasonably
>>> small ideas, between 100 and 300 LOC, that need a mentor (*).
>>
>> Please go ahead, and thanks.
>> Of course, to be practical, there's a need for a mentoree for each
>> such idea, but if that's you, then that issue is solved.
>

-- 
Joakim Verona

Re: [mentor-request] a darkroom/writeroom mode for Emacs

[João Távora]

joakim@verona.se writes:
>> Hi, I'm looking for a mentor who would help me clean up the code I have
>> in
>>
>>    https://github.com/capitaomorte/darkroom-mode
>
> - Did you get a copyright  assignment yet? Your code needs to be
>   assigned to FSF. See http://www.gnu.org/software/emacs/CONTRIBUTE,
>   copyright assignment section.
>
> - I think your packages will live a happy life in ELPA. Heres a pointer:
> http://www.emacswiki.org/emacs/ELPA#toc2

Hi Joakim,

The goal of this "mentoring" experiment is that an experienced
contributor/maintainer makes a short-term commitment to help a new
contributor clean up his code for inclusion. (I volunteered to test the
process with two half-baked extensions I had lying around.)

Was that your idea as well when replying? If so, I think explicitly
stating "I'll mentor this" is a good idea. Anyway, Rasmus is also on
this, so maybe you'll want to take a look at the second "ecco"
extension?

Anyway:

* Your first pointer is useful for copyrights, but then it makes
  absolutely no mention of Git, it still mentions Bazaar. 

* Your second pointer is much better.

I wonder why these these two aren't integrated... (I guess this was
discussed to death already.)

João

Re: [mentor-request] a darkroom/writeroom mode for Emacs

[joakim]

joaotavora@gmail.com (João Távora) writes:

> joakim@verona.se writes:
>>> Hi, I'm looking for a mentor who would help me clean up the code I have
>>> in
>>>
>>>    https://github.com/capitaomorte/darkroom-mode>
>> - Did you get a copyright  assignment yet? Your code needs to be
>>   assigned to FSF. See http://www.gnu.org/software/emacs/CONTRIBUTE,>   copyright assignment section.
>>
>> - I think your packages will live a happy life in ELPA. Heres a pointer:
>> http://www.emacswiki.org/emacs/ELPA#toc2
>
> Hi Joakim,
>
> The goal of this "mentoring" experiment is that an experienced
> contributor/maintainer makes a short-term commitment to help a new
> contributor clean up his code for inclusion. (I volunteered to test the
> process with two half-baked extensions I had lying around.)
>
> Was that your idea as well when replying? If so, I think explicitly
> stating "I'll mentor this" is a good idea. Anyway, Rasmus is also on
> this, so maybe you'll want to take a look at the second "ecco"
> extension?

My idea in replying was to practice to become a better emacs mentor.
So your feedback is very welcome!

>
> Anyway:
>
> * Your first pointer is useful for copyrights, but then it makes
>   absolutely no mention of Git, it still mentions Bazaar. 
>
> * Your second pointer is much better.
>
> I wonder why these these two aren't integrated... (I guess this was
> discussed to death already.)
>
> João

-- 
Joakim Verona

Re: [mentor-request] a darkroom/writeroom mode for Emacs

[Stephen J. Turnbull]

João Távora writes:

 > Cc: esr@thyrsus.com,
 >     Eli Zaretskii <eliz@gnu.org>,
 >     phillip.lord@newcastle.ac.uk,
 >     "Stephen J. Turnbull" <turnbull@sk.tsukuba.ac.jp>

Please remove uninvolved 3rd parties from mentoring traffic.  You too,
Joakim.  Sheesh!  Mentors at least should know better.

I'm predicting an early demise of this experiment.

Re: [mentor-request] a darkroom/writeroom mode for Emacs

[Rasmus]

joaotavora@gmail.com (João Távora) writes:

> Hi, I'm looking for a mentor who would help me clean up the code I have
> in
>
>    https://github.com/capitaomorte/darkroom-mode
>
> This is my implementation of the popular "darkroom/writeroom" hack, of
> which multiple versions can be found around the web. I believe mine can
> be polished to make it into Emacs.

Why is your mode preferable?
Did you take care of the FSF paperwork?

> I'm looking for pointers on how to clone the Emacs repository after the
> recent Git transition, whether to use Emacs or ELPA for it, plus any
> other tips that increase my chances.

This is surely documented somewhere.

I guess it should go to ELPA, but you need to improve it.
BTW: I'm using writeroom.el for this.

Some quick comments follow.  Note, I'm not an expert, especially on the
Emacs display engine.  I'm not sure if this is the intended format of
[mentor-request] emails.


You need to start with a proper head of the file, including the commentary
section.  Further, for ELPA dependencies, version etc. should be listed (I
guess none).  See the top of any file in your ~/.emacs.d/elpa/ folder.

> (defvar darkroom-margins 0.15

This is a defcusom.  See (info "(elisp) Variable Definitions")


> (defvar darkroom-turns-on-visual-line-mode t

See above.  I think providing a hook is better.  People can add this
themselves if they want something different from the global value.
(info "(elisp) Hooks")


> (defvar darkroom-fringes-outside-margins t

defcustom 

> (defun darkroom-margins ()

IMO you should document every defun.


> (defun darkroom-float-to-columns (f)

As above.


> (defun darkroom-increase-margins ()
docstring 

>   (interactive)
>   (when (floatp darkroom-margins)
>     (setq darkroom-margins (+ 0.05 darkroom-margins))

0.05 should at the very least be a defconst but better a defcustom or from
some global variable.
Also, you provide three ways of setting margins. 

> (defun darkroom-decrease-margins ()
>   (interactive)
>   (when (floatp darkroom-margins)
>     (setq darkroom-margins (- darkroom-margins 0.05))
>     (darkroom-set-margins)))

> (defun darkroom-fill-paragraph-maybe (really)
>   (interactive "P")
>   (cond (visual-line-mode
>          (if (not really)
>              (message "not filling paragraph")
>            (call-interactively 'fill-paragraph)
>            (message "filled paragraph even in visual-line-mode")))
>         (t
>          (call-interactively 'fill-paragraph))))

This seems quite opinionated.  Why the need to deviate from ordinary Emacs
behavior?  You need to document these features an explain why they make
sense in the docstring and preferably in the commentary as well.

> (defvar darkroom-mode-map (let ((map (make-sparse-keymap)))
>                                   (define-key map (kbd "C-M-+") 'darkroom-increase-margins)
>                                   (define-key map (kbd "C-M--") 'darkroom-decrease-margins)
>                                   (define-key map (kbd "M-q") 'darkroom-fill-paragraph-maybe)
>                                   map))

> (defvar darkroom-saved-mode-line-format nil)
> (defvar darkroom-saved-header-line-format nil)
> (defvar darkroom-saved-visual-line-mode nil)

Please add docstring, last argument.

> (make-variable-buffer-local 'darkroom-saved-mode-line-format)
> (make-variable-buffer-local 'darkroom-saved-header-line-format)
> (make-variable-buffer-local 'darkroom-saved-visual-line-mode)

> (defun darkroom-visual-mode-maybe-enable ()
>   (when darkroom-turns-on-visual-line-mode
>     (cond (darkroom-mode
>            (setq darkroom-saved-visual-mode visual-line-mode)
>            (visual-line-mode 1))
>           (t
>            (unless darkroom-saved-visual-line-mode
>              (visual-line-mode -1))))))

Docstring.  I don't understand the need of this feature.

> (define-minor-mode darkroom-mode
>   "Minor mode emulating the darkroom editor that I never used."

This is a bad docstring since it contains uselsess info and I need to know
what darkroom is.

>   nil nil nil
>   (cond (darkroom-mode
>          (setq darkroom-saved-mode-line-format mode-line-format
>                mode-line-format nil
>                darkroom-saved-header-line-format header-line-format
>                header-line-format nil)
>          (darkroom-set-margins)
>          (darkroom-visual-mode-maybe-enable)
>          (text-scale-increase 2)

Should be a defcustom.

>          (add-hook 'window-configuration-change-hook 'darkroom-set-margins nil t))
>         (t
>          (setq mode-line-format darkroom-saved-mode-line-format
>                header-line-format darkroom-saved-header-line-format)
>          (text-scale-decrease 2)
>          (darkroom-set-margins '(0 . 0))

I guess my old margin should be recorded.

>          (darkroom-visual-mode-maybe-enable)
>          (remove-hook 'window-configuration-change-hook 'darkroom-set-margins t))))

> (defun darkroom-maybe-enable ()

Docstring. 

>   (cond ((and (not darkroom-mode) (= (count-windows) 1))

why count-windows?  Why would it not just use the buffer in focus?

>          (darkroom-mode 1)) 
>         ((and darkroom-mode (> (count-windows) 1))
>          (darkroom-mode -1))
>         (t
>          (message "Hmm buffer: %s windows: %s darkroom-mode: %s"
what does "hmm buffer" mean?
>                   (current-buffer)
>                   (count-windows)
>                   darkroom-mode))))


> (define-minor-mode darkroom-tentative-mode
>   "Minor mode that enters `darkroom-mode' when all windws are deleted"
>   nil "D" nil
>   (cond (darkroom-tentative-mode
>          (add-hook 'window-configuration-change-hook 'darkroom-maybe-enable nil t)
>          (darkroom-maybe-enable))
>         (t
>          (if darkroom-mode (darkroom-mode -1))
>          (remove-hook 'window-configuration-change-hook 'darkroom-maybe-enable t))))

Again, this seems like a feature and I have no idea about it cause you
never explain the intended design.

Hope it helps,
Rasmus

-- 
Enough with the bla bla!

Re: [mentoring] a darkroom/writeroom mode for Emacs

[João Távora]

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


   [ Hi Rasmus, I took it from your thorough review of the code that you
   accept to mentor this, in the framework discussed earlier. In the
   future, perhaps change the subject line to "mentoring".

   The code was indeed sketchy, a bit on purpose, and I've integrated
   almost all your suggestions, but read on.

   I'll be using these double-personality comments throughout my reply
   to comment on the mentoring meta-process :-)]

Rasmus <rasmus@gmx.us> writes:
> Why is your mode preferable?

    [ How convincing must the would-be-contributor be at this stage?
    Won't opening with this question intimidate him/her? ]

I haven't done a thorough survey of other extensions, but I remember
trying some that don't deal well with the margins, and none provide
something like `darkroom-tentative-mode'.

> Did you take care of the FSF paperwork?
    [ I've contributed to Emacs earlier, so yes. Again should this
      question be on top?]

Yes.

>> I'm looking for pointers on how to clone the Emacs repository after the
>> recent Git transition, whether to use Emacs or ELPA for it, plus any
>> other tips that increase my chances.
> This is surely documented somewhere.

   [ Either provide a pointer better than "somewhere", or defer to the
   future if you can't.]

Where?

> I guess it should go to ELPA, but you need to improve it.

OK, I'll improve it. Once it's in ELPA, how do I maintain it? Can I keep
using github for the upstream since I'm so familiar with it?

> Some quick comments follow.  Note, I'm not an expert, especially on the
> Emacs display engine.  I'm not sure if this is the intended format of
> [mentor-request] emails.

   [ There is no format, we're trying to figure it out. Yours is
   close enough.]

> You need to start with a proper head of the file, including the commentary
> section.  Further, for ELPA dependencies, version etc. should be listed (I
> guess none).  See the top of any file in your ~/.emacs.d/elpa/ folder.

Done. [ I used the badly named M-x auto-insert, but yours was a good
suggestion ]

>> (defvar darkroom-margins 0.15
>
> This is a defcusom.  See (info "(elisp) Variable Definitions")

Done.

>> (defvar darkroom-turns-on-visual-line-mode t
> See above.  I think providing a hook is better.  People can add this
> themselves 

Yes, I got rid of it. 

>> (defvar darkroom-fringes-outside-margins t
> defcustom

Done

>> (defun darkroom-margins ()
> IMO you should document every defun.

I've renamed this function `darkroom-compute-margins' and added a
minimal docstring.

>> (defun darkroom-float-to-columns (f)
> As above.

Will do in the future. [ Is this essential? ]

>> (defun darkroom-increase-margins ()
> docstring

Done. [ Interactive functions should indeed have a docstring. ]

>>     (setq darkroom-margins (+ 0.05 darkroom-margins))
> 0.05 should at the very least be a defconst but better a defcustom or from
> some global variable.

Done.

> Also, you provide three ways of setting margins.

This was redesigned. It should be better now. `darkroom-compute-margins'
is used only when entering `darkroom-mode', then the user can use
`darkroom-increase/decrease-margins' to tweak its decision.

>> (defun darkroom-fill-paragraph-maybe (really)
> This seems quite opinionated.  Why the need to deviate from ordinary Emacs
> behavior?  You need to document these features an explain why they make
> sense in the docstring and preferably in the commentary as well.

Yes, it's opinionated and not very useful. I've removed it.

>> (defvar darkroom-saved-mode-line-format nil)
>> (defvar darkroom-saved-header-line-format nil)
>> (defvar darkroom-saved-visual-line-mode nil)
> Please add docstring, last argument.

I made these internal variables (used the "--"), do I still need a
docstring?

>> (defun darkroom-visual-mode-maybe-enable ()
> Docstring.  I don't understand the need of this feature.

I've removed it, since it didn't work very well, but the idea is that a
buffer in visual-line-mode (with soft wrapping of long lines), will
always enter darkroom-mode with nice margins that perfectly center the
text on the screen. A buffer with hard linebreaks (like this message) is
not perfect for darkroom-mode, since the margins won't center it.

But I've added a utility function `darkroom-guess-margins' that can be
set as the value for `darkroom-margins' and attempts to guess that. In
the writing of this message, for example, where I `fill-pargraph' all
the time, it has guessed the "correct" margins (see screenshot). In
code, it normally defaults to 15% margins.

It's not perfect, and could be improved. Unfortunately, and more
seriously, it doesn't work when the text scale is increase with
`darkroom-text-scale-increase' set to anything but 0, because
`window-width' doesn't know about text scaling
apparently. `window-width' can return pixels, but then how can I know
the pixel width of the current buffer's font? `frame-char-width' was
promising, but also always returns a constant value.

>> (define-minor-mode darkroom-mode
>>   "Minor mode emulating the darkroom editor that I never used."
> This is a bad docstring since it contains uselsess info and I need to know
> what darkroom is.

   [ Lol. ]

Sorry, I fixed it.

>>          (text-scale-increase 2)
> Should be a defcustom.

Done.

>>          (darkroom-set-margins '(0 . 0))
> I guess my old margin should be recorded.

Done.

>> (defun darkroom-maybe-enable ()
> Docstring.

It's internal now.

>>   (cond ((and (not darkroom-mode) (= (count-windows) 1))
> why count-windows?  Why would it not just use the buffer in focus?

The idea in `darkroom-tentative-mode' here is that `darkroom-mode' is
entered if and only if all but one window on the frame are deleted.

>>          (message "Hmm buffer: %s windows: %s darkroom-mode: %s"
> what does "hmm buffer" mean?

It's debug code. I commented it out.

>> (define-minor-mode darkroom-tentative-mode
>>   "Minor mode that enters `darkroom-mode' when all windws are deleted"
> Again, this seems like a feature and I have no idea about it cause you
> never explain the intended design.

Well, minus typo I did very briefly. But it should be clearer now from
the commits I did.

> Hope it helps,

It did. [ It did. ]


[-- Attachment #2: darkroom-margins.png --]
[-- Type: image/png, Size: 258011 bytes --]

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Rasmus]

joaotavora@gmail.com (João Távora) writes:

>    [ Hi Rasmus, I took it from your thorough review of the code that you
>    accept to mentor this, in the framework discussed earlier. In the
>    future, perhaps change the subject line to "mentoring".

I hit F, write the message and then click C-c C-c.  Did you not include
the [mentoring] line to begin with?

> Rasmus <rasmus@gmx.us> writes:
>> Why is your mode preferable?
>
>     [ How convincing must the would-be-contributor be at this stage?
>     Won't opening with this question intimidate him/her? ]

Maybe.  This is the question my supervisor asks me every time I come up
with a new idea.  Indeed, it's a very unpleasant question, but one that
you need to consider no matter if you do code or try to write a thesis.

> I haven't done a thorough survey of other extensions, but I remember
> trying some that don't deal well with the margins, and none provide
> something like `darkroom-tentative-mode'.
>
>> Did you take care of the FSF paperwork?
>     [ I've contributed to Emacs earlier, so yes. Again should this
>       question be on top?]

Yeah, 'cause it takes time.  So the earlier the process the better.  If
you have not signed papers and do not intend to, I won't read your patch.


>>> I'm looking for pointers on how to clone the Emacs repository after the
>>> recent Git transition, whether to use Emacs or ELPA for it, plus any
>>> other tips that increase my chances.
>> This is surely documented somewhere.
>
>    [ Either provide a pointer better than "somewhere", or defer to the
>    future if you can't.]

OK.

> Where?

Check: http://www.emacswiki.org/emacs/ELPA#toc2

>> I guess it should go to ELPA, but you need to improve it.
>
> OK, I'll improve it. Once it's in ELPA, how do I maintain it? Can I keep
> using github for the upstream since I'm so familiar with it?

I guess, but it would require more work as you'd need to manually push it.
Perhaps Dmitry (of Company) could explain how he handles it.


>> (defvar darkroom-turns-on-visual-line-mode t
> See above.  I think providing a hook is better.  People can add this
> themselves 

Yes, I got rid of it.  You probably also need a hook when exiting.  Or the
functions in the hook are called with different argument when entering and
exiting the minor-mode.  (I did not reread your code).

>>> (defun darkroom-float-to-columns (f)
>> As above [docstring].
>
> Will do in the future. [ Is this essential? ]

Well, I'm going through your code.  Since my time is scare, I would rather
get a quick hint about what the function is doing.  I won't have to guess
everything then.

Take org-mode.  We have a bunch of weird little functions.  I do C-h f on
them.  If they have no docstring, I have to go a read the source (which I
probably don't care about).

>> Please add docstring, last argument.
>
> I made these internal variables (used the "--"), do I still need a
> docstring?

IMO: Yes.  I don't know if there's an establish consensus.

>>> (defun darkroom-visual-mode-maybe-enable ()
>> Docstring.  I don't understand the need of this feature.
>
> I've removed it, since it didn't work very well, but the idea is that a
> buffer in visual-line-mode (with soft wrapping of long lines), will
> always enter darkroom-mode with nice margins that perfectly center the
> text on the screen. A buffer with hard linebreaks (like this message) is
> not perfect for darkroom-mode, since the margins won't center it.

I agree.  Indeed if you can solve this issue it would be pretty cool.

> But I've added a utility function `darkroom-guess-margins' that can be
> set as the value for `darkroom-margins' and attempts to guess that. In
> the writing of this message, for example, where I `fill-pargraph' all
> the time, it has guessed the "correct" margins (see screenshot). In
> code, it normally defaults to 15% margins.

The screenshot looks nice.

> It's not perfect, and could be improved. Unfortunately, and more
> seriously, it doesn't work when the text scale is increase with
> `darkroom-text-scale-increase' set to anything but 0, because
> `window-width' doesn't know about text scaling
> apparently. `window-width' can return pixels, but then how can I know
> the pixel width of the current buffer's font? `frame-char-width' was
> promising, but also always returns a constant value.

To me, larger font would be essential.  And indeed, a problem is the
combination of auto-fill and larger font.  ATM I don't have a good idea on
how to solve this.

>>>   (cond ((and (not darkroom-mode) (= (count-windows) 1))
>> why count-windows?  Why would it not just use the buffer in focus?
>
> The idea in `darkroom-tentative-mode' here is that `darkroom-mode' is
> entered if and only if all but one window on the frame are deleted.
> 
>>> (define-minor-mode darkroom-tentative-mode
>>>   "Minor mode that enters `darkroom-mode' when all windws are deleted"
>> Again, this seems like a feature and I have no idea about it cause you
>> never explain the intended design.
>
> Well, minus typo I did very briefly. But it should be clearer now from
> the commits I did.

OK, as long as your document it, it's fine.

>> Hope it helps,
>
> It did. [ It did. ]
both of you are happy, that's good! 

—Rasmus

-- 
A page of history is worth a volume of logic

Re: [mentoring] a darkroom/writeroom mode for Emacs

[João Távora]

Rasmus <rasmus@gmx.us> writes:
> joaotavora@gmail.com (João Távora) writes:
>
>>    [ Hi Rasmus, I took it from your thorough review of the code that you
>>    accept to mentor this, in the framework discussed earlier. In the
>>    future, perhaps change the subject line to "mentoring".
> I hit F, write the message and then click C-c C-c.  Did you not include
> the [mentoring] line to begin with?

No, I didn't. I used "[mentor-request]" hoping that a mentor would reply
with "[mentoring]" to make the commitment. After a few "Re: [mentoring]"
iterations, when it's done, change the subject again to "[mentored]". I
state that you mentored it and ask for final comments or stuff you
couldn't help with. If no blockers appear then, I or someone else
commits it. We can document this somewhere later if we find it warrants
it. Maybe it is too complicated, but think it's useful.

By the way I dropped the [] comments this time around.

>> Rasmus <rasmus@gmx.us> writes:
>>     [ How convincing must the would-be-contributor be at this stage?
>>     Won't opening with this question intimidate him/her? ]
> Maybe.  This is the question my supervisor asks me every time I come up
> with a new idea.  Indeed, it's a very unpleasant question, but one that
> you need to consider no matter if you do code or try to write a thesis.

OK. But he/she shouldn't be forced to make a bullet-proof case at this
point, the main goal is to cleanup the contribution of blockers. After
that its pertinence can be reevaluated. Of course, an objection would
be: "why do all the mentoring work then?". I don't have an answer, but I
still think its useful.

>>> Did you take care of the FSF paperwork?
>>     [ I've contributed to Emacs earlier, so yes. Again should this
>>       question be on top?]
> Yeah, 'cause it takes time.  So the earlier the process the better.  If
> you have not signed papers and do not intend to, I won't read your
> patch.

OK. Clearly, discovering if the author does not intend to do it is very
important. But if he doesn't object, reading the patch is probably still
useful in the meantime.

>> Where?
> Check: http://www.emacswiki.org/emacs/ELPA#toc2

Looks good indeed, though it states simply "Now you can push to the
repo". A look at the linked "Making Packages" should tell where to place
the file, for example, it doesn't. Perhaps I just need to mimic what
other packages do there in the repo. Anyway I think those intructions
could be improved, and made into a tutorial on how to add foo-mode.el to
the ELPA repo.

>>> I guess it should go to ELPA, but you need to improve it.
>> OK, I'll improve it. Once it's in ELPA, how do I maintain it? Can I keep
>> using github for the upstream since I'm so familiar with it?
> I guess, but it would require more work as you'd need to manually push it.
> Perhaps Dmitry (of Company) could explain how he handles it.

Yes, good idea. We can ask him after this mentoring phase: that's not a
blocker.

>>> (defvar darkroom-turns-on-visual-line-mode t
>> See above.  I think providing a hook is better.  People can add this
>> themselves 
> Yes, I got rid of it.  You probably also need a hook when exiting.  Or the
> functions in the hook are called with different argument when entering and
> exiting the minor-mode.

I didn't provide the hook. There is the minor mode hook that is normally
provided. Do you think any more are needed?

> (I did not reread your code).

I more or less expected you to, at least the diffs, or at least the new
"Commentary" header at the top, which explains the main functionality
that wasn't clear to you.

> Well, I'm going through your code.  Since my time is scare, I would rather
> get a quick hint about what the function is doing.  I won't have to guess
> everything then.

OK. Though, I would say understanding every little detail of the code is
unimportant at this step if you capture the overall functionality. You
didn't capture it, because I didn't describe it. Hence your other
questions, which I find more pertinent than this one at this stage.

>> I've removed it, since it didn't work very well, but the idea is that a
>> buffer in visual-line-mode (with soft wrapping of long lines), will
>> always enter darkroom-mode with nice margins that perfectly center the
>> text on the screen. A buffer with hard linebreaks (like this message) is
>> not perfect for darkroom-mode, since the margins won't center it.
> I agree.  Indeed if you can solve this issue it would be pretty cool.
>  [...]
> To me, larger font would be essential.  And indeed, a problem is the
> combination of auto-fill and larger font.  ATM I don't have a good idea on
> how to solve this.

We can ask here for solutions after this mentoring step is done: I'm
sure someone can come up with a solution.

>> Well, minus typo I did very briefly. But it should be clearer now from
>> the commits I did.
> OK, as long as your document it, it's fine.

I did. Hopefully well enough. But if you had a final quick look it would
be good. Then I can send another message to the list with the subject
line prefixed "[mentored]", with the final questions about the
outstanding problems and push it. (I should have write access to the
repo.).

>> It did. [ It did. ]
> both of you are happy, that's good!
We are all one now muahaha

João

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Rasmus]

First things first.

joaotavora@gmail.com (João Távora) writes:

>> (I did not reread your code).
>
> I more or less expected you to, at least the diffs, or at least the new
> "Commentary" header at the top, which explains the main functionality
> that wasn't clear to you.

OK, I will check this later.  ATM I need to work towards a deadline.

> Rasmus <rasmus@gmx.us> writes:
>> joaotavora@gmail.com (João Távora) writes:
>>
>>>    [ Hi Rasmus, I took it from your thorough review of the code that you
>>>    accept to mentor this, in the framework discussed earlier. In the
>>>    future, perhaps change the subject line to "mentoring".
>> I hit F, write the message and then click C-c C-c.  Did you not include
>> the [mentoring] line to begin with?
>
> No, I didn't. I used "[mentor-request]" hoping that a mentor would reply
> with "[mentoring]" to make the commitment. After a few "Re: [mentoring]"
> iterations, when it's done, change the subject again to "[mentored]". I
> state that you mentored it and ask for final comments or stuff you
> couldn't help with. If no blockers appear then, I or someone else
> commits it. We can document this somewhere later if we find it warrants
> it. Maybe it is too complicated, but think it's useful.

I guess it's nice, but it might be a bit to optimistic!

>>> Rasmus <rasmus@gmx.us> writes:
>>>     [ How convincing must the would-be-contributor be at this stage?
>>>     Won't opening with this question intimidate him/her? ]
>> Maybe.  This is the question my supervisor asks me every time I come up
>> with a new idea.  Indeed, it's a very unpleasant question, but one that
>> you need to consider no matter if you do code or try to write a thesis.
>
> OK. But he/she shouldn't be forced to make a bullet-proof case at this
> point, the main goal is to cleanup the contribution of blockers. After
> that its pertinence can be reevaluated. Of course, an objection would
> be: "why do all the mentoring work then?". I don't have an answer, but I
> still think its useful.

Nobody talks about bulletproof.  Here's a reason for your project: "the
current implementations do not center the contents and works poorly with
auto-fill-mode".  The idea is the first step, IMO.  Implementation can
then follow.  This is also why the commentary section is important.

>>>> Did you take care of the FSF paperwork?
>>>     [ I've contributed to Emacs earlier, so yes. Again should this
>>>       question be on top?]
>> Yeah, 'cause it takes time.  So the earlier the process the better.  If
>> you have not signed papers and do not intend to, I won't read your
>> patch.
>
> OK. Clearly, discovering if the author does not intend to do it is very
> important. But if he doesn't object, reading the patch is probably still
> useful in the meantime.

Sure.  The key is: "... have not signed papers *and do not intend to*".

>>> Where?
>> Check: http://www.emacswiki.org/emacs/ELPA#toc2
>
> Looks good indeed, though it states simply "Now you can push to the
> repo". A look at the linked "Making Packages" should tell where to place
> the file, for example, it doesn't. Perhaps I just need to mimic what
> other packages do there in the repo. Anyway I think those intructions
> could be improved, and made into a tutorial on how to add foo-mode.el to
> the ELPA repo.

OK.  I don't know the details (I don't have any ELPA-stuff), but the gist
is probably along:
     - You get access to the ELPA repo.
     - git clone <membername>@git.sv.gnu.org:/srv/git/emacs/elpa.git
     - make sure to read
       http://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README
     - do your work and push it.  I think pixies rebuild packages
       automatically, but check the README.

>> Yes, I got rid of it.  You probably also need a hook when exiting.  Or the
>> functions in the hook are called with different argument when entering and
>> exiting the minor-mode.
>
> I didn't provide the hook. There is the minor mode hook that is normally
> provided. Do you think any more are needed?

IMO: Yes.  Cdlatex-org-mode is also a minor mode.  So is paredit.  I'm not
sure we want to use the same functions for these three projects.
E.g. visual-line-mode may be of interest to your mode, but not to paredit.
See `run-hook-with-args' and `run-hooks' and the like.

>> Well, I'm going through your code.  Since my time is scare, I would rather
>> get a quick hint about what the function is doing.  I won't have to guess
>> everything then.
>
> OK. Though, I would say understanding every little detail of the code is
> unimportant at this step if you capture the overall functionality. You
> didn't capture it, because I didn't describe it. Hence your other
> questions, which I find more pertinent than this one at this stage.

"I" could be your future self.  You just wrote 3 sentences about this
issue.  It's an opinion thing.  Gnus and Org has bunch of undocumented
functions, but it's nicer is there's one sentence on each function.

>>> I've removed it, since it didn't work very well, but the idea is that a
>>> buffer in visual-line-mode (with soft wrapping of long lines), will
>>> always enter darkroom-mode with nice margins that perfectly center the
>>> text on the screen. A buffer with hard linebreaks (like this message) is
>>> not perfect for darkroom-mode, since the margins won't center it.
>> I agree.  Indeed if you can solve this issue it would be pretty cool.
>>  [...]
>> To me, larger font would be essential.  And indeed, a problem is the
>> combination of auto-fill and larger font.  ATM I don't have a good idea on
>> how to solve this.
>
> We can ask here for solutions after this mentoring step is done: I'm
> sure someone can come up with a solution.

I will see if I can find a way to think about the centering display issue.
I do wonder if the window-width independence of font-size is a bug.  Note:
you might be able to estimate the actual width using `string-width` and
`{beginning, end}-of-visual-line'.

BTW: I remember having seen issues with auto-fill and large fonts.  Do you
have a reproducible example at hand?

> I did. Hopefully well enough. But if you had a final quick look it would
> be good. Then I can send another message to the list with the subject
> line prefixed "[mentored]", with the final questions about the
> outstanding problems and push it. (I should have write access to the
> repo.).

You are very keen on changing subject lines.  I will try to check your
code tonight.

—Rasmus

-- 
. . . It begins of course with The Internet.  A Net of Peers

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Stefan Monnier]

>>> Yes, I got rid of it.  You probably also need a hook when exiting.  Or the
>>> functions in the hook are called with different argument when entering and
>>> exiting the minor-mode.
>> I didn't provide the hook. There is the minor mode hook that is normally
>> provided. Do you think any more are needed?
> IMO: Yes.  Cdlatex-org-mode is also a minor mode.  So is paredit.  I'm not
> sure we want to use the same functions for these three projects.
> E.g. visual-line-mode may be of interest to your mode, but not to paredit.
> See `run-hook-with-args' and `run-hooks' and the like.

I think João got it right here: define-minor-mode already defines a hook
for that particular minor mode and there shouldn't be a need to define
any extra one.


        Stefan

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Rasmus]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>>> exiting the minor-mode.
>>> I didn't provide the hook. There is the minor mode hook that is normally
>>> provided. Do you think any more are needed?
>> IMO: Yes.  Cdlatex-org-mode is also a minor mode.  So is paredit.  I'm not
>> sure we want to use the same functions for these three projects.
>> E.g. visual-line-mode may be of interest to your mode, but not to paredit.
>> See `run-hook-with-args' and `run-hooks' and the like.
>
> I think João got it right here: define-minor-mode already defines a hook
> for that particular minor mode and there shouldn't be a need to define
> any extra one.

Right. . .  Now I understand; Outsmarted by Emacs again.
Thanks!

—Rasmus

-- 
May contains speling mistake

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Rasmus]

joaotavora@gmail.com (João Távora) writes:

Some comments follow.  I did it quickly (as you may notice), but it still
took 1½ South Park episodes.

> ;;; darkroom.el --- Remove visual distractions and focus on writing  -*- lexical-binding: t; -*-

> ;; Copyright (C) 2014  João Távora

There's usually a clause somewhere about whether it's part of Emacs.  It's
probably not important.

> ;;; Commentary:

> ;; The main entrypoints to this extension are two minor modes

Colon IMO

> ;;
> ;;    M-x darkroom-mode
> ;;    M-x darkroom-tentative-mode
> ;;
> ;; The first makes current buffer to enter `darkroom-mode'
> ;; immediately: keeping the window configuration untouched, text is
> ;; enlarged, centered on the window with margins, and the modeline is
> ;; elided.

This paragraph is not clear and potentially tautologous.


> (defcustom darkroom-margins 0.15
>   "Margins to use in `darkroom-mode'.

> Its value can be:

> - a floating point value betweeen 0 and 1, specifies percentage of
>   window width in columns to use as a margin.

> - a cons cell (LEFT RIGHT) specifying the left and right margins
>   in columns.

> - a function of no arguments that returns a cons cell interpreted
>   like the previous option.

You might want to mention the function you wrote below.  Maybe it should
be default if you can sort out the FIXME  

> Value is effective when `darkroom-mode' is toggled, when
> changing window or by calling `darkroom-set-margins'"
>   :type 'float
>   :group 'darkroom)

So, there's both a function to calculate margins the possibility of
specifying it manually?  What takes priority?

> (defun darkroom-guess-margins ()
>   "Guess suitable margins for `darkroom-margins'.

I think there should be a blank line here.

> Collects some statistics about the buffer's line lengths, and
> apply a heuristic to figure out how wide to set the margins. If
> the buffer's paragraphs are mostly filled to `fill-column',
> margins should center it on the window, otherwise, margins of
> 0.15 percent are used."

Why the need for hardcoding?

>   ;;; FIXME: broken when darkroom-text-scale-increase is anything but
>   ;;; 0, since window-width ignores text scaling. Otherwise, a
>   ;;; suitable default to put in `darkroom-margins', I guess.

You can estimate the realized width rolling over some lines and measure.
Probably there's a more appropriate way of doing it.  

(save-excursion (- (progn (end-of-visual-line) (point))
                   (progn (beginning-of-visual-line) (point))))

Note, for understanding this you might get some insights from studying
`line-move' and `line-move-visual' (I don't know).

>   (if visual-line-mode
>       0.15
>     (let* ((window-width (window-width))
>            (line-widths (save-excursion
>                           (goto-char (point-min))
>                           (cl-loop for start = (point)
>                                    while (search-forward "\n"
>                                                          20000
>                                                          'no-error)
>                                    for width = (- (point) start 1)

I'm not sure this does what you want.  A quick test suggests it will find
the end of the line, not the "visual" end of the line.

You do you need to add this to the top of your file?

    (eval-when-compile (require 'cl))


>                                    unless (zerop width)
>                                    collect width)))
>            (_longest-width (cl-reduce #'max line-widths :initial-value 0))
>            (top-quartile-avg (cl-loop with n = (/ (length line-widths)
>                                                   4)
>                                       for width in (copy-sequence
>                                                     (sort line-widths #'>))
>                                       for i from 1 upto n
>                                       sum width into total
>                                       finally (return (/ total n 1.0)))))

This seems like overenginering.  What about something like this (not
tested, check that it works out with the floats).

(let ((n4 (/ (length n) 4)))
     (/ (apply '+ (subseq (sort line-width '>) 0 n4)) n4))

>       (cond
>        ((> top-quartile-avg
>            window-width)
>         (when (y-or-n-p
>                (format
>                 (mapconcat
>                  #'identity
>                  '("Long lines detected!"
>                    "(top 25%% average %s chars and window-width is %s)"
>                    "Perhaps turn on visual-line-mode for a better darkroom?")
>                  "\n")

Here you can use concat and format. . .  In general this functionally
seems a bit obstructive.  "Dont's ask me stuff..."

>                 top-quartile-avg window-width))
>           (visual-line-mode 1))
>         0.15)
>        ((> top-quartile-avg (* 0.9 fill-column))
>         (let ((margin (round (/ (- window-width top-quartile-avg) 2))))
>           (cons margin margin)))
>        (t
>         0.15)))))

I think you can simplify this and you should not hardcode .15.

> (defun darkroom-compute-margins ()
docstring, please.  What's the *idea* of this function. 

>   (let ((darkroom-margins
>          (if (functionp darkroom-margins)
>              (funcall darkroom-margins)
>            darkroom-margins)))
>     (cond ((consp darkroom-margins)
>            darkroom-margins)
>           ((and (floatp darkroom-margins)
>                 (< darkroom-margins 1))
>            (let ((delta (darkroom-float-to-columns darkroom-margins)))
>              (cons delta delta)))
>           (t
>            (error "Illegal value in `darkroom-margins'")))))



> (defun darkroom-float-to-columns (f)
>   (ceiling (* (let ((edges (window-edges)))
>                 (- (nth 2 edges) (nth 0 edges)))
>               f)))

(- (line-end-position) (line-beginning-position))

But you probably need to account for visual lines.

> (defvar darkroom-buffer-margins nil
>   "Buffer-local version of `darkroom-margins' defcustom.
> Set by `darkroom-set-margins'")

I think these should all be at the top of the file.

> (defun darkroom-set-margins (&optional margins)
>   "Set margins from MARGINS or `darkroom-buffer-margins'."
>   (let* ((window-configuration-change-hook nil))
>     (when margins
>       (when (null (car margins)) (setcar margins 0))
>       (when (null (cdr margins)) (setcdr margins 0)))
>     (set (make-local-variable 'darkroom-buffer-margins)
>          (or margins darkroom-buffer-margins))
>     (walk-windows #'(lambda (w)
>                       (when (eq (window-buffer w) (current-buffer))
>                         (setq fringes-outside-margins
>                               darkroom-fringes-outside-margins)
>                         ;; See description of
>                         ;; `fringes-outside-margins' for the reason
>                         ;; for this apparent noop
>                         (set-window-buffer w (current-buffer))
>                         (set-window-margins w (car darkroom-buffer-margins)
>                                             (cdr darkroom-buffer-margins))))
>                   nil
>                   'all-frames)))

Can't you use with-current-buffer?  The walk-windows seems excessive.  

You should test this when resizing windows and increasing fonts. . .

> (defun darkroom-increase-margins (increment)
>   (interactive (list darkroom-margin-increment))
>   (unless (and (consp darkroom-buffer-margins)
>                (numberp (car darkroom-buffer-margins))
>                (numberp (cdr darkroom-buffer-margins)))
>     (error "`darkroom-buffer-margins' corrupted. Must be a cons of numbers."))
>   (setcar darkroom-buffer-margins
>           (round (* (+ 1 increment) (car darkroom-buffer-margins))))
>   (setcdr darkroom-buffer-margins
>           (round (* (+ 1 increment) (cdr darkroom-buffer-margins))))

      (setq  darkroom-buffer-margins (cons · ·))

>   (darkroom-set-margins darkroom-buffer-margins))

> (defun darkroom-decrease-margins (decrement)

docstring

>   (interactive (list darkroom-margin-increment))
>   (darkroom-increase-margins (- decrement)))

> (defvar darkroom-mode-map

Top of file

>   (let ((map (make-sparse-keymap)))
>     (define-key map (kbd "C-M-+") 'darkroom-increase-margins)
>     (define-key map (kbd "C-M--") 'darkroom-decrease-margins)
>     map))

Ideally this should be unnecessary.  Maybe it should be called after
changing the font size or whatnot.

> (defvar darkroom-saved-mode-line-format nil)
> (defvar darkroom-saved-header-line-format nil)
> (defvar darkroom-saved-margins nil)

Top of file.  And docstring.

> (define-minor-mode darkroom-mode
>   "Remove visual distractions and focus on writing. When this
> mode is active, everything but the buffer's text is elided from
> view. The buffer margins are set so that text is centered on
> screen. Text size is increased (display engine allowing) by
> `darkroom-text-scale-increase'." nil nil nil
>   (cond (darkroom-mode
>          (set (make-local-variable 'darkroom-saved-margins) (window-margins))
>          (set (make-local-variable 'darkroom-saved-mode-line-format)
>               mode-line-format)
>          (set (make-local-variable 'darkroom-saved-header-line-format)
>               header-line-format)
>          (setq mode-line-format nil)
>          (setq header-line-format nil)
>          (text-scale-increase darkroom-text-scale-increase)
>          (darkroom-set-margins (darkroom-compute-margins))
>          (add-hook 'window-configuration-change-hook 'darkroom-set-margins
>                    nil t))
>         (t
>          (setq mode-line-format darkroom-saved-mode-line-format
>                header-line-format darkroom-saved-header-line-format)
>          (text-scale-decrease darkroom-text-scale-increase)

You need to actually record the size used before the mode is entered.  I
could increase the width after I enter darkroom. 

>          (let (darkroom-buffer-margins)
>            (darkroom-set-margins darkroom-saved-margins))
>          (remove-hook 'window-configuration-change-hook 'darkroom-set-margins
>                       t))))

> (defun darkroom-maybe-enable ()
>   (cond ((and (not darkroom-mode) (= (count-windows) 1))
>          (darkroom-mode 1))
>         ((and darkroom-mode (> (count-windows) 1))
>          (darkroom-mode -1))
>         (t
>          ;; (message "debug: buffer: %s windows: %s darkroom-mode: %s"
>          ;;          (current-buffer) (count-windows) darkroom-mode)
>          )))

You don't need the last clause.  Also, do you want to test if
(eq major-mode 'darkroom-mode) ?

Again, hope it helps.

—Rasmus

-- 
I feel emotional landscapes they puzzle me

Re: [mentoring] a darkroom/writeroom mode for Emacs

[João Távora]

Rasmus <rasmus@gmx.us> writes:

>> ;; Copyright (C) 2014  João Távora
> There's usually a clause somewhere about whether it's part of Emacs.  It's
> probably not important.

That's what M-x auto-insert gave me. I should assign it to the FSF
though.

> This paragraph is not clear and potentially tautologous.

The opening tautology is necessary to diffentiate it from
`darkroom-tentative-mode'. I wonder what else is not clear, but I have
rewritten it.

> You might want to mention the function you wrote below.  Maybe it should
> be default if you can sort out the FIXME

Yes, I had that in mind.

>> Value is effective when `darkroom-mode' is toggled, when
>> changing window or by calling `darkroom-set-margins'"
>>   :type 'float
>>   :group 'darkroom)
> So, there's both a function to calculate margins the possibility of
> specifying it manually?  What takes priority?

You found a bug, that second part of the docstring no longer applies.

>> (defun darkroom-guess-margins ()
>>   "Guess suitable margins for `darkroom-margins'.
> I think there should be a blank line here.

I don't think Emacs uses that particular blank, but OK.

>> Collects some statistics about the buffer's line lengths, and
>> apply a heuristic to figure out how wide to set the margins. If
>> the buffer's paragraphs are mostly filled to `fill-column',
>> margins should center it on the window, otherwise, margins of
>> 0.15 percent are used."

> Why the need for hardcoding?

To make time for southpark. Also it's cold, typing hurts and naming
variables is hard. I've fixed it.

>>   ;;; FIXME: broken when darkroom-text-scale-increase is anything but
>>   ;;; 0, since window-width ignores text scaling. Otherwise, a
>>   ;;; suitable default to put in `darkroom-margins', I guess.
>
> You can estimate the realized width rolling over some lines and measure.
> Probably there's a more appropriate way of doing it.  
>
> (save-excursion (- (progn (end-of-visual-line) (point))
>                    (progn (beginning-of-visual-line) (point))))
>
> Note, for understanding this you might get some insights from studying
> `line-move' and `line-move-visual' (I don't know).

It helped. I dealt with the FIXME with the ultra-horrible
`darkroom--real-window-width'. It fixes `window-width' basically. Seems
to work. The above won't work because I need to know about window
geometry, not line geometry. Unless there's a very big line. And that's
how `darkroom--real-window-width' hacks it.

>>     (let* ((window-width (window-width))
>>            (line-widths (save-excursion
> I'm not sure this does what you want.  A quick test suggests it will find
> the end of the line, not the "visual" end of the line.

Yes, but I want to collect actual line widths here. 

> You do you need to add this to the top of your file?
>
>     (eval-when-compile (require 'cl))

I don't think I need it. I use no compile-time cl-functions.

> This seems like overenginering.  What about something like this (not
> tested, check that it works out with the floats).

> (let ((n4 (/ (length n) 4)))
>      (/ (apply '+ (subseq (sort line-width '>) 0 n4)) n4))

Cleaner, needs cl-subseq..

>>                    "Perhaps turn on visual-line-mode for a better darkroom?")
>>                  "\n")
> Here you can use concat and format. . .  In general this functionally
> seems a bit obstructive.  "Dont's ask me stuff..."

OK removed it and replaced with a message.

>
>>                 top-quartile-avg window-width))
>>           (visual-line-mode 1))
>>         0.15)
>>        ((> top-quartile-avg (* 0.9 fill-column))
>>         (let ((margin (round (/ (- window-width top-quartile-avg) 2))))
>>           (cons margin margin)))
>>        (t
>>         0.15)))))
>
> I think you can simplify this and you should not hardcode .15.

Ideas welcome, I didn't think much about the heuristic, this one worked
ok. I fixed the hardcoding.

>> (defun darkroom-compute-margins ()
> docstring, please.  What's the *idea* of this function.

It's an internal function (what version of code were you looking
at). It, well, computes margins. This is a big discusison, but while I
very much sympathise with your thoroughness in documentation, docstrings
should explain the "what" carefully avoiding the "how", so you can
change that later. For internal functions, it might be a good idea to
leave them out, rather than risk them getting out of date, or hindering
others from redesigning your code. I know this from experience. Anyway,
to please my mentor, I added a docstring :-)

>> (defun darkroom-float-to-columns (f)
>>   (ceiling (* (let ((edges (window-edges)))
>>                 (- (nth 2 edges) (nth 0 edges)))
>>               f)))
>
> (- (line-end-position) (line-beginning-position))

No. Here I'm concerned with the window geometry, not the current line's
geometry.

>> (defvar darkroom-buffer-margins nil
>>   "Buffer-local version of `darkroom-margins' defcustom.
>> Set by `darkroom-set-margins'")
>
> I think these should all be at the top of the file.

I prefer nearer the users. Unless the file gets big and demands a
particular structure, in which case I try to first separate by
functionality, not programming construct.

>>     (walk-windows #'(lambda (w)
>>                       (when (eq (window-buffer w) (current-buffer))
>>                   'all-frames)))
>
> Can't you use with-current-buffer?  The walk-windows seems excessive.

Keep in mind I need to affect all windows that display that buffer. There
might be several.

> You should test this when resizing windows and increasing fonts. . .

You're right. I'll do that before I submit. Did you test it?

>>   (setcdr darkroom-buffer-margins
>>           (round (* (+ 1 increment) (cdr darkroom-buffer-margins))))
>       (setq  darkroom-buffer-margins (cons · ·))

I could, but there's no big benefit and this also make the consness
explicit.

>> (defun darkroom-decrease-margins (decrement)
> docstring

You either weren't looking at the latest version, or I didn't push it.

>>   (let ((map (make-sparse-keymap)))
>>     (define-key map (kbd "C-M-+") 'darkroom-increase-margins)
>>     (define-key map (kbd "C-M--") 'darkroom-decrease-margins)
>>     map))
>
> Ideally this should be unnecessary.  Maybe it should be called after
> changing the font size or whatnot.

Well, the user might want to tweak it for some reason. But yes,
`darkroom--set-margins' should be called from more hooks.

>> (defvar darkroom-saved-mode-line-format nil)
>> (defvar darkroom-saved-header-line-format nil)
>> (defvar darkroom-saved-margins nil)
>
> Top of file.  And docstring.

Docstring done.

>>         (t
>>          (setq mode-line-format darkroom-saved-mode-line-format
>>                header-line-format darkroom-saved-header-line-format)
>>          (text-scale-decrease darkroom-text-scale-increase)
>
> You need to actually record the size used before the mode is entered.  I
> could increase the width after I enter darkroom.

I started to implement this, then realized, maybe it needn't be so,
because it works by increments. Did you try it?

>>         (t
>>          ;; (message "debug: buffer: %s windows: %s darkroom-mode: %s"
>>          ;;          (current-buffer) (count-windows) darkroom-mode)
>>          )))
>
> You don't need the last clause.  Also, do you want to test if
> (eq major-mode 'darkroom-mode) ?

Keep it there for future debugging. I don't understand. `darkroom-mode'
is a minor mode.

> Some comments follow.  I did it quickly (as you may notice), but it still
> took 1½ South Park episodes.

Which ones are you watching?

João

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Stefan Monnier]

>>> (walk-windows #'(lambda (w)
>>> (when (eq (window-buffer w) (current-buffer))
>>> 'all-frames)))
>> Can't you use with-current-buffer?  The walk-windows seems excessive.
> Keep in mind I need to affect all windows that display that buffer. There
> might be several.

[ Haven't really read all the message, but this just jumped at me.  ]

Why not get-buffer-window-list?


        Stefan

Re: [mentoring] a darkroom/writeroom mode for Emacs

[João Távora]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Why not get-buffer-window-list?

Probably because I didn't know it existed, thanks.

João

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Rasmus]

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

joaotavora@gmail.com (João Távora) writes:

>> This paragraph is not clear and potentially tautologous.
>
> The opening tautology is necessary to diffentiate it from
> `darkroom-tentative-mode'. I wonder what else is not clear, but I have
> rewritten it.

It's better now.

This is how I use it BTW:

(autoload 'darkroom-mode "darkroom" nil t)
(when (fboundp 'darkroom-mode) (global-set-key [f6] 'darkroom-mode))

(with-eval-after-load 'darkroom
  (setq darkroom-text-scale-increase 3)
  (add-hook 'darkroom-mode-hook 'variable-pitch-mode))

This also shows the problem with the hook that I spoke of earlier.  If I
for some reason have variable-pitch-mode enabled I will get disabled.  Of
course, I could just make a more sophisticated λ testing the value of
darkroom-mode.  So probably just stick with the default hook.

Changing theme could be another possibility, though I'm not sure one can
load a theme for single buffer...

>>>   ;;; FIXME: broken when darkroom-text-scale-increase is anything but
>>>   ;;; 0, since window-width ignores text scaling. Otherwise, a
>>>   ;;; suitable default to put in `darkroom-margins', I guess.
>>
>> You can estimate the realized width rolling over some lines and measure.
>> Probably there's a more appropriate way of doing it.  
>>
>> (save-excursion (- (progn (end-of-visual-line) (point))
>>                    (progn (beginning-of-visual-line) (point))))
>>
>> Note, for understanding this you might get some insights from studying
>> `line-move' and `line-move-visual' (I don't know).
>
> It helped. I dealt with the FIXME with the ultra-horrible
> `darkroom--real-window-width'. It fixes `window-width' basically. Seems
> to work. The above won't work because I need to know about window
> geometry, not line geometry. Unless there's a very big line. And that's
> how `darkroom--real-window-width' hacks it.

OK.  I must have mixed up the intention of this logic.  I will recheck
this at the moment.


Dogfooding you code, I find that the margin adjustment (still?) does not
work well on small screens when font-size is increased.  And font-size
increase is pretty central, IMO.


[-- Attachment #2: Screenshot from 2014-12-11 18:58:51.png --]
[-- Type: image/png, Size: 33062 bytes --]

[-- Attachment #3: Type: text/plain, Size: 5019 bytes --]


In the screenshot I have Emacs take up half of my screen (1440x900).  As
you can see, for this setting the margin is way to big.  This is using the
standard setting.  So the heuristic is not very good.  You write

    "If the buffer's paragraphs are mostly filled to `fill-column',
     margins should center it on the window, otherwise, margins of 0.15 percent
     are used."

When you have at least auto-fill, the objective should be something like
this I guess (I didn't think carefully about it):

(*)  Margin* = argmin  abs{real-line-with - shown-line-width(margin; font-size)}

where ";" reads "given" or "for fixed".  Maybe with some weight on margin
itself as well for aesthetic reasons (so + λ f(margin)).  In the
screenshot the margins are definitely too wide as it hinders a good
writing environment contrary to the objective.

I guess this is why I talk about the width of virtual lines (which are
functions of font-size and actual width).  Of course, the easiest way to
solve (*) is recursively.  I don't know if that works well with the
display engine, though.

I will go through `darkroom-guess-margins' again later.  I havne't got the
time right now.

>>>                 top-quartile-avg window-width))
>>>           (visual-line-mode 1))
>>>         0.15)
>>>        ((> top-quartile-avg (* 0.9 fill-column))
>>>         (let ((margin (round (/ (- window-width top-quartile-avg) 2))))
>>>           (cons margin margin)))
>>>        (t
>>>         0.15)))))
>>
>> I think you can simplify this and you should not hardcode .15.
>
> Ideas welcome, I didn't think much about the heuristic, this one worked
> ok. I fixed the hardcoding.

See discussion above.  IMO, this is not working well (but probably *also*
*not worse* than other packages with the same objective!).

>>> (defun darkroom-compute-margins ()
>> docstring, please.  What's the *idea* of this function.
>
> It's an internal function (what version of code were you looking
> at). It, well, computes margins. This is a big discusison, but while I
> very much sympathise with your thoroughness in documentation, docstrings
> should explain the "what" carefully avoiding the "how", so you can
> change that later. For internal functions, it might be a good idea to
> leave them out, rather than risk them getting out of date, or hindering
> others from redesigning your code. I know this from experience. Anyway,

What is what I call *idea*.  It's easier for me to read the current
*implementation* when I know what the *purpose/expected outcome*
of the function is.  We are arguing for the same thing, I think. 

>>> (defun darkroom-float-to-columns (f)
>>>   (ceiling (* (let ((edges (window-edges)))
>>>                 (- (nth 2 edges) (nth 0 edges)))
>>>               f)))
>>
>> (- (line-end-position) (line-beginning-position))
>
> No. Here I'm concerned with the window geometry, not the current line's
> geometry.

OK, I have to go back and understand why you care about window geometry.
I'm clearly missing part of the idea.

>>>   (let ((map (make-sparse-keymap)))
>>>     (define-key map (kbd "C-M-+") 'darkroom-increase-margins)
>>>     (define-key map (kbd "C-M--") 'darkroom-decrease-margins)
>>>     map))
>>
>> Ideally this should be unnecessary.  Maybe it should be called after
>> changing the font size or whatnot.
>
> Well, the user might want to tweak it for some reason. But yes,
> `darkroom--set-margins' should be called from more hooks.



>>>         (t
>>>          (setq mode-line-format darkroom-saved-mode-line-format
>>>                header-line-format darkroom-saved-header-line-format)
>>>          (text-scale-decrease darkroom-text-scale-increase)
>>
>> You need to actually record the size used before the mode is entered.  I
>> could increase the width after I enter darkroom.
>
> I started to implement this, then realized, maybe it needn't be so,
> because it works by increments. Did you try it?

It's a taste question then.  Enter darkroom increase font size n times.
Leave darkroom.  Now the font size is increased by n compared to when I
entered darkroom.  It could be a feature.  Another feature could "be what
happens in the dark room stays in the dark room".


I will comment more later.

—Rasmus

PS: 
>> Some comments follow.  I did it quickly (as you may notice), but it still
>> took 1½ South Park episodes.
>
> Which ones are you watching?

The two latest episodes.

>> Why the need for hardcoding?
>
> To make time for southpark. Also it's cold, typing hurts and naming
> variables is hard. I've fixed it.

It's getting colder, yes, and it's flabbergasting how Iberian[or at least
Catalonian(?)] houses do not have heating!

> to please my mentor, I added a docstring :-)

I find the title uncomfortable as it suggests I'd have greater insights,
which is probably (as in →ₐₛ) not the case; rather it's peer reviewing.

—Rasmus

-- 
Bang bang

Re: [mentoring] a darkroom/writeroom mode for Emacs

[João Távora]

Rasmus <rasmus@gmx.us> writes:

> This also shows the problem with the hook that I spoke of earlier.  If I
> for some reason have variable-pitch-mode enabled I will get disabled.

I going to say this is a bug in `variable-pitch-mode', since I read
somewhere (Stefan?) that a minor mode should always turn itself *on* when
called with a nil argument, precisely to support use cases such as
yours.

> Changing theme could be another possibility, though I'm not sure one can
> load a theme for single buffer...

I don't think one can, at least with "custom themes". I think "color
themes" used to provide that possibility, so the needed functionality
should be in Emacs. Perhaps someone wants to open that can of worms.

> Dogfooding you code, I find that the margin adjustment (still?) does not
> work well on small screens when font-size is increased.  And font-size
> increase is pretty central, IMO.

Can you provide a specific example?

> In the screenshot I have Emacs take up half of my screen (1440x900).  As
> you can see, for this setting the margin is way to big.  This is using the
> standard setting.  So the heuristic is not very good.  You write

Is the image provided in the screenshot resized? What did you expect the
image to be?

>     "If the buffer's paragraphs are mostly filled to `fill-column',
>      margins should center it on the window, otherwise, margins of 0.15 percent
>      are used."
>
> When you have at least auto-fill, the objective should be something like
> this I guess (I didn't think carefully about it):

We may be miscommunicating. I'm not checking for `auto-fill-mode'
anywhere. In `darkroom-guess-margins', I'm looking at statistics for the
real line lengths and estimating if the paragraphs are (mostly) filled
to `fill-column', be it with manual `fill-paragraph' or `auto-fill-mode'
maybe.

The intent of `darkroom-guess-margins' is then to choose suitable
margins to center on the window (not necessarily the "screen" or the
"frame"), without truncation, what it thinks are the main parts of your
text, possibly truncating (or adding "continuation lines") on any
spurious or exceptionally long lines.

This it does iff visual-line-mode is inactive. If it is active, it just
assumes that you want 0.15 (or `darkroom-margins-if-failed-guess'). It
also uses 0.15 if the guessing somehow "fails".

> (*)  Margin* = argmin  abs{real-line-with - shown-line-width(margin; font-size)}
>
> where ";" reads "given" or "for fixed".  Maybe with some weight on margin
> itself as well for aesthetic reasons (so + λ f(margin)).  In the
> screenshot the margins are definitely too wide as it hinders a good
> writing environment contrary to the objective.
>
> I guess this is why I talk about the width of virtual lines (which are
> functions of font-size and actual width).  Of course, the easiest way to
> solve (*) is recursively.  I don't know if that works well with the
> display engine, though.
>
> I will go through `darkroom-guess-margins' again later.  I havne't got the
> time right now.

Well, I'm not following your algorithm (though I admit I didn't try
super hard). Best would be to create fixture files that we know should
produce a certain correct behaviour. So, if I send you this very
paragraph, and run `darkroom-guess-margins' in a window that is 100
columns long (assuming `window-width' now knows afound font size), I
should (at least I want to) get left and right margins of 15 columns
each. So I could place this text in a file called
"darkroom-fixture-a-100-15-15.txt" and use that in an automated
test. Can you provide me with
"darkroom-fixture-<b-z>-<window-width>-<lmargin>-<rmargin>.txt" so I can
understand what kind of margin calculations you are talking about?

I can then create automated tests from this with ert-deftest.

> See discussion above.  IMO, this is not working well (but probably *also*
> *not worse* than other packages with the same objective!).

If we later find that we disagree in the heuristic, we can provide two
and let the user decide which one he wants.

Anyway I have a big thinko in darkroom.el. Window margins must be
calculated by window, not by buffer, because they're a property of
windows. I'm fixing that first.

>> To make time for southpark. Also it's cold, typing hurts and naming
>> variables is hard. I've fixed it.
> It's getting colder, yes, and it's flabbergasting how Iberian[or at least
> Catalonian(?)] houses do not have heating!

Iberian peninsula is big and has many weather types. The coldest it gets
in portugal is about +5c for about a month, so unless you're rich and
enjoy tshirting in the winter and think global warming is a cool new
club, you don't have heating and pine for the summer. I'm just lazy to
get a blanket.

>> to please my mentor, I added a docstring :-)
> I find the title uncomfortable as it suggests I'd have greater insights,
> which is probably (as in →ₐₛ) not the case; rather it's peer
> reviewing.

Sorry, but play along. Though I'll include this factor in the mentoring
conclusions, perhaps "[peer review]" would make a better tag.

Anyway this review (also tellingly) got very sidetracked into the
implementation details. Can I assume you are more or less happy with the
procedural and cosmetic aspects of darkroom.el that the "mentoring" part
is over? Then I might officially propose darkroom.el to elpa.git.n I've
already cloned the repo and have a reasonable idea how to commit
it. Then others that others can chime in about the implementation
(Stefan has already been doing so).

J

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Rasmus]

Hi,

joaotavora@gmail.com (João Távora) writes:
>> This also shows the problem with the hook that I spoke of earlier.  If I
>> for some reason have variable-pitch-mode enabled I will get disabled.
>
> I going to say this is a bug in `variable-pitch-mode', since I read
> somewhere (Stefan?) that a minor mode should always turn itself *on* when
> called with a nil argument, precisely to support use cases such as
> yours.

Perhaps, the correct name would be `toggle-variable-pitch-mode'.  Which is
what is needed here.

>> In the screenshot I have Emacs take up half of my screen (1440x900).  As
>> you can see, for this setting the margin is way to big.  This is using the
>> standard setting.  So the heuristic is not very good.  You write
>
> Is the image provided in the screenshot resized? What did you expect the
> image to be?

Only cropped.  I expect the margins to be less wide.  Here's a comparison
between my normal view (right) and darkroom-view.  I use visual-line /and/
auto-fill.  When disabling visual-line-mode the margins are the same, but
I have to scroll left to see the whole line.

  http://i.imgur.com/ayvHqAW.png

The correct margin would (guesstimating) be somewhere between 0 and 2
characters here...

>>     "If the buffer's paragraphs are mostly filled to `fill-column',
>>      margins should center it on the window, otherwise, margins of 0.15 percent
>>      are used."
>>
>> When you have at least auto-fill, the objective should be something like
>> this I guess (I didn't think carefully about it):
>
> We may be miscommunicating. I'm not checking for `auto-fill-mode'
> anywhere. In `darkroom-guess-margins', I'm looking at statistics for the
> real line lengths and estimating if the paragraphs are (mostly) filled
> to `fill-column', be it with manual `fill-paragraph' or `auto-fill-mode'
> maybe.
>
> The intent of `darkroom-guess-margins' is then to choose suitable
> margins to center on the window (not necessarily the "screen" or the
> "frame"), without truncation, what it thinks are the main parts of your
> text, possibly truncating (or adding "continuation lines") on any
> spurious or exceptionally long lines.

OK.  Makes sense.  I think we have different problems in mind.  You are
talking of margin-width for centering-purposes, I'm talking of
margin-width to minimize annoyance (see below).

> This it does iff visual-line-mode is inactive. If it is active, it just
> assumes that you want 0.15 (or `darkroom-margins-if-failed-guess'). It
> also uses 0.15 if the guessing somehow "fails".

IMO this is wrong (but I guess what all other similar modes does as well).
It should choose margin so that the realized line with is approximately
the same as the real line width or so that the difference is as small as
possible.  This matters for small windows.  So, to center you need the
window geometry.  To choose the width, IMO, you need to look at the
difference between line width (be it visual or not) and realized width (in
the same of visual-line-mode).

> Well, I'm not following your algorithm (though I admit I didn't try
> super hard). Best would be to create fixture files that we know should
> produce a certain correct behaviour. So, if I send you this very
> paragraph, and run `darkroom-guess-margins' in a window that is 100
> columns long (assuming `window-width' now knows afound font size), I
> should (at least I want to) get left and right margins of 15 columns
> each. So I could place this text in a file called
> "darkroom-fixture-a-100-15-15.txt" and use that in an automated
> test. Can you provide me with
> "darkroom-fixture-<b-z>-<window-width>-<lmargin>-<rmargin>.txt" so I can
> understand what kind of margin calculations you are talking about?

As above, margin should /not/ be fixed a priori.  Rather, (and IMO) they
should be set to not be intrusive given the text.  Then centered.  what I
want is maybe too complicated, but I think it would be nice.

> Anyway this review (also tellingly) got very sidetracked into the
> implementation details. 

I don't understand the 'tellingly' here.

> Can I assume you are more or less happy with the procedural and cosmetic
> aspects of darkroom.el that the "mentoring" part is over? Then I might
> officially propose darkroom.el to elpa.git.n I'v already cloned the repo
> and have a reasonable idea how to commit it.

As you prefer.  Updates in ELPA are cheap.  Just change the version number
and push.

I have been working on a bug/patch for Org, but I'll look more into this
area of your code once I've tested that patch more.

I'll try to find time to go over it in the weekend and try to solve my
pet-grief as explained above (unless you bet me to it!).

> Then others that others can chime in about the implementation
> (Stefan has already been doing so).

I think they can already do so.  But everybody has got their own
constrains and issues to solve.  In general, I think the 'peer-review'
might be better in the sense that top-contributors may already have enough
on their plate as it is.

It also comes down to interest in the reviewed code.

However, the discussion aspect might be one place where GNU provides a
more compelling environment than the Github (I don't really use GH so I'm
guessing here).

—Rasmus

-- 
There are known knowns; there are things we know that we know

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[João Távora]

Hi List,

After some iterations with Rasmus, I have cleaned up darkroom.el library
of its most obvious problems and now consider it ready to push to
ELPA.git (as was suggested) if no-one objects.

The library lives in https://github.com/capitaomorte/darkroom if someone
is interesting in double checking or commenting.

The library still has an outstanding problem with "window-width", which
I have solved with an isolated hack. See the docstring for
`darkroom--real-window-width' for an explanation.

João

Rasmus <rasmus@gmx.us> writes:

>> I going to say this is a bug in `variable-pitch-mode', since I read
>> somewhere (Stefan?) that a minor mode should always turn itself *on* when
>> called with a nil argument, precisely to support use cases such as
>> yours.
> Perhaps, the correct name would be `toggle-variable-pitch-mode'.  Which is
> what is needed here.

I don't know if that would help you much, with just the minor-mode
hook. Saving the buffer's state and restoring is not trivial. Darkroom
implements it for the variables in the (internal)
`darkroom--saved-variables', but anything more complicated one has to
implement `darkroom-mode-hook' with some sophistication. This hook is
run when entering or leaving the minor mode.

> IMO this is wrong (but I guess what all other similar modes does as well).
> It should choose margin so that the realized line with is approximately
> the same as the real line width or so that the difference is as small as
> possible.  This matters for small windows.  So, to center you need the
> window geometry.  To choose the width, IMO, you need to look at the
> difference between line width (be it visual or not) and realized width (in
> the same of visual-line-mode).

> As above, margin should /not/ be fixed a priori.  Rather, (and IMO) they
> should be set to not be intrusive given the text.  Then centered.  what I
> want is maybe too complicated, but I think it would be nice.

I still don't understand, but I suspect it's related to your intent to
use variable pitch with darkroom-mode. In that scenario, indeed, the
concepts of "real line length" and "visual line length" start to make a
little sense to me, more or less. Also your idea of recursiveness. I'll
welcome an implementation for a "guess margins" function when you have
the time.

>> Anyway this review (also tellingly) got very sidetracked into the
>> implementation details. 
>
> I don't understand the 'tellingly' here.

In the context of the "mentoring" experiment, it's "telling" that this
discussion, initially supposed to be a relatively isolated, well-defined
and expedite step for cleaning up the proposed change in compliance with
Emacs procedures, quickly entered into the implementation details. It
"tells" me that maybe that separation may be too ambitious, at least
given the current awareness of the original "mentoring" intention. But
it's certainly not "your fault" or anything like that, it's just the way
it went.

>> Can I assume you are more or less happy with the procedural and cosmetic
>> aspects of darkroom.el that the "mentoring" part is over? Then I might
>> officially propose darkroom.el to elpa.git.n I'v already cloned the repo
>> and have a reasonable idea how to commit it.
>
> As you prefer.  Updates in ELPA are cheap.  Just change the version number
> and push.

As far as I understand it, this is the strategy to develop the upstream
on Github and publish to ELPA.git periodically. I will "git merge
--no-commit" my github repo into ELPA.git. Then issue whatever necessary
"git mv" I have to to place "darkroom.el" and any other files in the
correct place. Then commit with a suitable commit message. The following
updates also use "git merge --no commit".

> It also comes down to interest in the reviewed code.

Yes. I also suspected it, and I'll include this factor in my quick
debriefing of the "mentoring" experiment.

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[Dmitry Gutov]

joaotavora@gmail.com (João Távora) writes:

>> As you prefer.  Updates in ELPA are cheap.  Just change the version number
>> and push.
>
> As far as I understand it, this is the strategy to develop the upstream
> on Github and publish to ELPA.git periodically.

Not necessarily: the new version of the package is published when the
version header value is increased. So you can also push development
changes to GNU ELPA, then after some time increase the version number,
and only then the new version will be published.

> I will "git merge
> --no-commit" my github repo into ELPA.git. Then issue whatever necessary
> "git mv" I have to to place "darkroom.el" and any other files in the
> correct place. Then commit with a suitable commit message. The following
> updates also use "git merge --no commit".

Personally, I use `git subtree merge'. IIRC, Stefan usually does `git merge
--strategy=subtree` instead.

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[João Távora]

Dmitry Gutov <dgutov@yandex.ru> writes:

> joaotavora@gmail.com (João Távora) writes:
>
>>> As you prefer.  Updates in ELPA are cheap.  Just change the version number
>>> and push.
>>
>> As far as I understand it, this is the strategy to develop the upstream
>> on Github and publish to ELPA.git periodically.
>
> Not necessarily: the new version of the package is published when the
> version header value is increased. So you can also push development
> changes to GNU ELPA, then after some time increase the version number,
> and only then the new version will be published.

Thanks for the clarification. When I wrote "publish to ELPA.git" I meant
"synch to ELPA.git". I have little experience with GNU ELPA and
package.el, so please confirm this: Publishing is what makes the package
accessible to users as they "M-x package-install" that's strictly
related to increases in version numbers.

>> I will "git merge
>> --no-commit" my github repo into ELPA.git. Then issue whatever necessary
>> "git mv" I have to to place "darkroom.el" and any other files in the
>> correct place. Then commit with a suitable commit message. The following
>> updates also use "git merge --no commit".
>
> Personally, I use `git subtree merge'. IIRC, Stefan usually does `git merge
> --strategy=subtree` instead.

Can you explain if this fundamentally different from my strategy, or is
it just a convenience that would save me some "git mv" and conflict
resolution before adding the merge commit to the graph? I ask because
"--strategy=subtree" seems to hint at this last hypothesis.

Thanks,
João

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[Dmitry Gutov]

On 12/15/2014 03:20 PM, João Távora wrote:

> package.el, so please confirm this: Publishing is what makes the package
> accessible to users as they "M-x package-install" that's strictly
> related to increases in version numbers.

That's right. Check out the README: 
http://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README

> Can you explain if this fundamentally different from my strategy, or is
> it just a convenience that would save me some "git mv" and conflict
> resolution before adding the merge commit to the graph?

I think so, can't really say for sure if that's the only difference. I'm 
not clear on what your strategy will do under the covers.

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[João Távora]

Dmitry Gutov <dgutov@yandex.ru> writes:

> That's right. Check out the README:
> http://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README

Indeed this README thing you speak of is quite useful. :-)

> I think so, can't really say for sure if that's the only
> difference. I'm not clear on what your strategy will do under the
> covers.

Actually, I'd expect both your approaches to do more "under the covers",
(mine just uses the more common "merge" and "mv" primitives). That's why
I want to understand them. It's just a question of "git merge --help" or
inspecting the local result before pushing.

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[Stefan Monnier]

>> Personally, I use `git subtree merge'. IIRC, Stefan usually does `git merge
>> --strategy=subtree` instead.

Actually, nowadays, rather than --strategy=subtree I more often use an
explicit "-X subtree=packages/foo" so Git doesn't have to guess (this
is particularly important in the initial merge, where Git can't really
guess).

> Can you explain if this fundamentally different from my strategy, or is

My strategy is indeed the "same as yours", except that the "mv" are
performed by Git, but that makes a hell of a difference in terms of
conflict resolution.

IIUC the "git subtree merge" approach is somewhat similar except that
the merge metadata is thrown away and replaced by a "note" in the log
the remember which external revision was merged.


        Stefan

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[martin rudalics]

 > The library still has an outstanding problem with "window-width", which
 > I have solved with an isolated hack. See the docstring for
 > `darkroom--real-window-width' for an explanation.

I'm not sure whether I understand well enough what you want to do but if
the idea is to horizontally center some block of text in a window then I
would (1) get rid of margins, (2) get the width of the text to be
displayed via `window-text-pixel-size' and (3) if the text fits into the
window and there is some space left, distribute that space evenly among
the fringes of the window.  You'll be missing one pixel, at most.

I have no idea whether and when to recenter text while typing but this
seems to be unresolved in your original proposal too.

martin

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[João Távora]

martin rudalics <rudalics@gmx.at> writes:

>> The library still has an outstanding problem with "window-width", which
>> I have solved with an isolated hack. See the docstring for
>> `darkroom--real-window-width' for an explanation.
>
> I'm not sure whether I understand well enough what you want to do but if
> the idea is to horizontally center some block of text in a window then I
> would (1) get rid of margins, (2) get the width of the text to be
> displayed via `window-text-pixel-size' and (3) if the text fits into
> the

How would you code the condition in (3)? To test "if fits" don't you
need the width of the window? I can more or less see how it could be
done if I could find a character position that I am sure is at the
window edge, but that would just be a rehash of what the hack of
`darkroom--real-window-width' already does

> window and there is some space left, distribute that space evenly among
> the fringes of the window.

If I understand correctly, this is related to (1) and independent of the
implementation in (2,3). I chose to use the margins to center because
(1) the term "margins" made sense for this purpose (2) I consider the
fringes more still useful for continuation markers and other bitmaps.

> I have no idea whether and when to recenter text while typing but this
> seems to be unresolved in your original proposal too.

Indeed, this is not the intent of darkroom.el, at least in its current
state. I don't even understand what how such a feature would work or
feel like. Do you mean like "center paragraph", where a typing a word
alone on a line makes it occupy the horizontal center?

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[martin rudalics]

 > How would you code the condition in (3)? To test "if fits" don't you
 > need the width of the window? I can more or less see how it could be
 > done if I could find a character position that I am sure is at the
 > window edge, but that would just be a rehash of what the hack of
 > `darkroom--real-window-width' already does

The function `window-text-pixel-size' gives you the width of some block
of text in pixels. The function `window-width' when called with
PIXELWISE non-nil gives you the width of the window in pixels.  The
difference of the two gives you the pixel width you can distribute.

 >> window and there is some space left, distribute that space evenly among
 >> the fringes of the window.
 >
 > If I understand correctly, this is related to (1) and independent of the
 > implementation in (2,3). I chose to use the margins to center because
 > (1) the term "margins" made sense for this purpose (2) I consider the
 > fringes more still useful for continuation markers and other bitmaps.

Presently we cannot resize margins pixelwise.  But we can set fringe
sizes pixelwise.  If you prefer using the margins, you have to round the
difference calculated above (which means that the text might not get
centerd exactly by at most one frame character width minus one pixel).

 > Indeed, this is not the intent of darkroom.el, at least in its current
 > state. I don't even understand what how such a feature would work or
 > feel like. Do you mean like "center paragraph", where a typing a word
 > alone on a line makes it occupy the horizontal center?

If it's not the intent of darkroom then don't bother.

martin

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[João Távora]

martin rudalics <rudalics@gmx.at> writes:

> The function `window-text-pixel-size' gives you the width of some block
> of text in pixels. The function `window-width' when called with
> PIXELWISE non-nil gives you the width of the window in pixels.  The
> difference of the two gives you the pixel width you can distribute.

Yes I got it: I can collect pixelwise statistics about the line
lengths and then use window width. (with one problem I can circumvent:
window-width does not count *existing* margins).

But to do comparisons with column based variables like `fill-column', I
still need the character (assumed fixed) pixel width, which I need to
extract like this.

  (window-text-pixel-size (selected-window)
                          (point-min) (1+ (point-min)))

This fails for empty buffers, but that case is negligible anyway.

The code is much cleaner now, so thanks.

Anyway, its a bit confusing that `window-width' can't take the font size
in consideration, while `window-text-pixel-size' can. Though it probably
makes sense since a window can display chars of many widths. But then
using it without PIXELWISE should be deprecated.

> Presently we cannot resize margins pixelwise.  But we can set fringe
> sizes pixelwise.  If you prefer using the margins, you have to round the
> difference calculated above (which means that the text might not get
> centerd exactly by at most one frame character width minus one pixel).

That's OK in my book.

>> Indeed, this is not the intent of darkroom.el, at least in its current
>> state. I don't even understand what how such a feature would work or
>> feel like. Do you mean like "center paragraph", where a typing a word
>> alone on a line makes it occupy the horizontal center?
>
> If it's not the intent of darkroom then don't bother.

It might *become* its intent, if you wish to explain what you had in
mind.

J

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[martin rudalics]

 > Yes I got it: I can collect pixelwise statistics about the line
 > lengths and then use window width. (with one problem I can circumvent:
 > window-width does not count *existing* margins).

You can always get the margins of a window via (window-margins).
Multiply the result with (frame-char-width) and you get the pixels
(beware of a nil return value).

 > But to do comparisons with column based variables like `fill-column',

`fill-column' might be a problem, indeed.  Do you really need it?

 > I
 > still need the character (assumed fixed) pixel width, which I need to
 > extract like this.
 >
 >    (window-text-pixel-size (selected-window)
 >                            (point-min) (1+ (point-min)))

This will fail miserably with variable character widths.

 > This fails for empty buffers, but that case is negligible anyway.
 >
 > The code is much cleaner now, so thanks.
 >
 > Anyway, its a bit confusing that `window-width' can't take the font size
 > in consideration, while `window-text-pixel-size' can.

It can't.  Nobody can, so far ... Eli might fix this eventually.

 > Though it probably
 > makes sense since a window can display chars of many widths. But then
 > using it without PIXELWISE should be deprecated.

For a human being it's easier to think in terms of columns rather than
in pixels.

 > It might *become* its intent, if you wish to explain what you had in
 > mind.

I only thought that if you add/remove characters to/from the longest
line you might also consider recentering the entire text on the fly.

martin

Re: [mentoring-done] a darkroom/writeroom mode for Emacs

[João Távora]

martin rudalics <rudalics@gmx.at> writes:

>> Yes I got it: I can collect pixelwise statistics about the line
>> lengths and then use window width. (with one problem I can circumvent:
>> window-width does not count *existing* margins).
>
> You can always get the margins of a window via (window-margins).
> Multiply the result with (frame-char-width) and you get the pixels
> (beware of a nil return value).

That works too. I temporarily set margins to (0 . 0) then restore them.
>
>> But to do comparisons with column based variables like `fill-column',
>
> `fill-column' might be a problem, indeed.  Do you really need it?

Yes. Well, I guess. I estimate if "most" columns are filled to this
column, and if so set the window margins according to this length.

>> I
>> still need the character (assumed fixed) pixel width, which I need to
>> extract like this.
>>
>>    (window-text-pixel-size (selected-window)
>>                            (point-min) (1+ (point-min)))
>
> This will fail miserably with variable character widths.

I'm aware of that, the centering algorithm assumes fixed widths.

>> The code is much cleaner now, so thanks.
>>
>> Anyway, its a bit confusing that `window-width' can't take the font size
>> in consideration, while `window-text-pixel-size' can.
>
> It can't.  Nobody can, so far ... Eli might fix this eventually.
>> Though it probably
>> makes sense since a window can display chars of many widths. But then
>> using it without PIXELWISE should be deprecated.
>
> For a human being it's easier to think in terms of columns rather than
> in pixels.

I agree. But the contract for the new/fixed function must state that the
column value returned is only valid for one particular character width,
presumably the "main" size.

>> It might *become* its intent, if you wish to explain what you had in
>> mind.
>
> I only thought that if you add/remove characters to/from the longest
> line you might also consider recentering the entire text on the fly.

Oh, that's interesting indeed (and not tremendously hard to do.)

João

RE: [mentoring] a darkroom/writeroom mode for Emacs

[Drew Adams]

> I don't think one can, at least with "custom themes". I think "color
> themes" used to provide that possibility, so the needed
> functionality should be in Emacs.

FWIW -

Whatever features color themes "used to provide" are still provided.
`color-theme.el' works fine, through Emacs 25 and probably beyond.

And color themes have some advantages over "custom" themes, just as
custom themes have some advantages over color themes.

It is too bad that users have been given the impression that since
Emacs added custom themes they somehow supersede color themes.
They could do so, if the limitations were addressed and fixed.

http://www.emacswiki.org/ColorAndCustomThemes

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=15687
(erroneously renamed)

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=15740

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Stefan Monnier]

> I going to say this is a bug in `variable-pitch-mode', since I read
> somewhere (Stefan?) that a minor mode should always turn itself *on* when
> called with a nil argument, precisely to support use cases such as
> yours.

Indeed.  Could you make it a bug report?


        Stefan

Re: [mentoring] a darkroom/writeroom mode for Emacs

[Phillip Lord]

João Távora <joaotavora@gmail.com> writes:
>> I guess it should go to ELPA, but you need to improve it.
>
> OK, I'll improve it. Once it's in ELPA, how do I maintain it? Can I keep
> using github for the upstream since I'm so familiar with it?


I've just been through this with some of my packages (pabbrev and
omn-mode); they are in ELPA now as an external which seems to
work fairly well. I maintain it as I would normally, and just push
master up to github or ELPA (or both) as currently.

The only really difference is that to release I need to push a tag to
github (for melpa-stable), and bump the version number internally for
ELPA.

I wrote notes on this at the time, and will turn it into something
readable once my current workbomb has finished. But happy to try and
help before that if you want.

Phil

[mentor-request] Ecco - a literate programming documentation generator

[João Távora]

   [ This message is a "mentor request" and part of an experiment
     described in this thread:
     
          https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00541.html

     A mentor is any frequent Emacs contributor who directs newcomers to
     documentation and helps them polish code contributions, easing them
     through Emacs' specific procedures, aiming to lower the entry
     barrier to Emacs development. If possible, mentors should try to be
     reasonably agnostic to the proposal's pertinence or particular
     implementation - that can be discussed later. Discussion can happen
     in or off-list. If on-list, use a "[mentoring]" prefix to the
     subject line, so that other users can keep all but essential
     comments to a minimum. ]

Hi, I'm looking for a mentor who would help me clean up the code I have
in

   https://github.com/capitaomorte/ecco

"ecco" is a literate-programming style documentation generator for
emacs. Its a port of the "docco", "shocco" and "rocco" tools for other
languages found around the web.  An advantage of ecco is that it uses
Emacs's built-in comment processing funcionality and highlighting
functionality and so it works for any language.

I believe "ecco" can be polished to make it into Emacs.

I'm looking for pointers on how to clone the Emacs repository after the
recent Git transition, whether to use Emacs or ELPA for it, plus any
other tips that increase my chances.

Waiting to hear from a mentor, or from any newcomer who wants to take
over the mentoree part of this project.

Thanks,
João

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joaotavora@gmail.com (João Távora)
>> Cc: Eli Zaretskii <eliz@gnu.org>,  esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
>> Date: Sat, 06 Dec 2014 07:07:21 +0000
>> 
>> To test the process, I can volunteer to submit a couple of reasonably
>> small ideas, between 100 and 300 LOC, that need a mentor (*).
>
> Please go ahead, and thanks.
> Of course, to be practical, there's a need for a mentoree for each
> such idea, but if that's you, then that issue is solved.

Results of the "mentoring" experiment Re: Metaproblem, part 3

[João Távora]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joaotavora@gmail.com (João Távora)
>> Cc: Eli Zaretskii <eliz@gnu.org>,  esr@thyrsus.com,  phillip.lord@newcastle.ac.uk,  emacs-devel@gnu.org
>> Date: Sat, 06 Dec 2014 07:07:21 +0000
>> 
>> To test the process, I can volunteer to submit a couple of reasonably
>> small ideas, between 100 and 300 LOC, that need a mentor (*).
>
> Please go ahead, and thanks.
>
> Of course, to be practical, there's a need for a mentoree for each
> such idea, but if that's you, then that issue is solved.

Hi,

On Friday, I pushed darkroom.el to ELPA.git, as one of my "reasonably
small ideas" that I setup for the "mentoring experiment" to ELPA.git. I
consider the experiment finished:

Here are some notes:

* I posted two emails with two "mentor requests". One had a couple of
  replies the other had none.

* From one of the replies (this thread or
  https://lists.gnu.org/archive/html/emacs-devel/2014-12/msg00808.html),
  three or four iterations with Rasmus ensued until the code was mostly
  clean of obvious mistakes, according to Emacs coding-style rules and
  so on. Rasmus also helped clarify much of the functionality and
  insisted on good docstrings for example.

* Doing this on-list went OK, with not too much noise. Stefan
  contributed some very small, but useful comments. After Rasmus gave
  the go-ahead more or less informally, Dmitry Gutov and Martin Rudalics
  each gave some final advice and resolved the final blockers. I get the
  feeling there were some followers of the thread, because visits spiked
  at my github upstream. Richard Stallman also expressed curiosity about
  what the "darkroom hack" was. Stephen Turnbull complained about being
  in Cc. Sorry, for some reason I only say that mail today. You're in Cc
  now because you predicted "an early demise of this experiment."  and
  I'm interested in knowing your thoughts now that it's over.

  Anyway, after some silence, I pushed to git.

* According to Rasmus, the mentoree must do some effort in this phase to
  convincingly present the utility of his extension, and how it
  differentiates from the rest.

* According to Rasmus, and I agree, availability and commitment of
  mentors depends on the personal interest they have in the
  code. Apparently Rasmus had used something similar to darkroom.el

* Rasmus' interest motivated me to actually do the work and really clean
  it up.

* Changing subject line prefixes to express the state of the process
  didn't please Rasmus much. I guess it's a stupid way to emulate a bug
  tracker.

* It's really very easy to distract oneself into the implementation
  details (for example "loop" vs "reduce") during what I idealized that
  the mentoring phase should be. There has to be some force to focus on
  the procedure-based blockers (copyright assignment, git workflow, big
  flaws in code) and separate them from the rest of the analysis etc.

* My opinion is that this can work, but there have to be some guidelines
  in place (like manual, CONTRIBUTE or README) so that mentors and
  mentorees are aware of some minimal formality in their roles. It went
  OK without it, but could go better. Also Rasmus prefers it to be
  called "peer-review".

* I found that the information that is sought after in this phase is
  practically all written down and available already, but spread across
  the Elisp manual, wikipedia, the ELPA.git README, git tutorials,
  etc. A nice aggregation of this information would be useful, but this
  was in the original discussion I believe.

I guess the whole idea of mentoring is that a person with some
experience is the best aggregator and additionally provides (a lot of)
motivation to clean your stuff up and contribute.

Thanks everybody and bye!
João

Re: Results of the "mentoring" experiment Re: Metaproblem, part 3

[Rasmus]

Hi,

joaotavora@gmail.com (João Távora) writes:

> On Friday, I pushed darkroom.el to ELPA.git, as one of my "reasonably
> small ideas" that I setup for the "mentoring experiment" to ELPA.git.

Thanks for pushing this to ELPA.

Some quick comments, mostly to clarify João's summaries of my comments.

> * According to Rasmus, the mentoree must do some effort in this phase to
>   convincingly present the utility of his extension, and how it
>   differentiates from the rest.

If you want somebody to spend time reviewing you new, "unproven" code, you
better be ready to justify why it's going to be — or already is — worth
the effort.  Mostly everybody has got 24h-days but would like to have a
many hours more.

> * According to Rasmus, and I agree, availability and commitment of
>   mentors depends on the personal interest they have in the
>   code. Apparently Rasmus had used something similar to darkroom.el

This is related to the above.

> * Rasmus' interest motivated me to actually do the work and really clean
>   it up.

Cool.  Darkroom is bound to F6 in my init.el now.  I'll look into

> * My opinion is that this can work, but there have to be some guidelines
>   in place (like manual, CONTRIBUTE or README) so that mentors and
>   mentorees are aware of some minimal formality in their roles. It went
>   OK without it, but could go better.

It could be formalized, if you think.  I'm not sure it would make a
difference.  People give advice according to their skills and preferences
already.

> Also Rasmus prefers it to be called "peer-review".

When Stefan, David, Eli, Dmitry, Drew, Stephen, Richard and mostly
everyone on this list give advice you can call it "mentoring".  But
clearly when someone like myself gives advice, it's peer-advice.

> I guess the whole idea of mentoring is that a person with some
> experience is the best aggregator and additionally
> *provides (a lot of) motivation to clean your stuff up and contribute*.

I agree strongly with this and I think it's one of the strengths of GNU.

—Rasmus

-- 
Tack, ni svenska vakttorn. Med plutonium tvingar vi dansken på knä!

Re: Results of the "mentoring" experiment

[Stephen Leake]

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

joaotavora@gmail.com (João Távora) writes:

> * I found that the information that is sought after in this phase is
>   practically all written down and available already, but spread across
>   the Elisp manual, wikipedia, the ELPA.git README, git tutorials,
>   etc. A nice aggregation of this information would be useful, but this
>   was in the original discussion I believe.

I'm cleaning up this info; can you send me a list?

Attached is my current patch, splitting CONTRIBUTE into user vs
developer stuff; user stuff is now in the Emacs manual.

My intent is that CONTRIBUTE should state some developer information,
and reference any other useful developer information.

-- 
-- Stephe

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Move-user-level-information-from-CONTRIBUTE-to-doc-e.patch --]
[-- Type: text/x-patch, Size: 27158 bytes --]

From bb21df9a15aeb32482959c57b84a9cf5ba6d4c23 Mon Sep 17 00:00:00 2001
From: Stephen Leake <stephen_leake@stephe-leake.org>
Date: Fri, 19 Dec 2014 11:18:50 -0600
Subject: [PATCH] Move user-level information from CONTRIBUTE to
 doc/emacs/trouble.texi

Fixes bug#19299

* CONTRIBUTE: Move user-level information to doc/emacs/trouble.texi
  (commit messages): new, gathered from comments on emacs-devel
  (Changelog notes): add reference to GNU coding standards section 5.2;
  doc 'present tense', bug fix format
  (branches): freeze announcements are made on info-gnu-emacs mailing
  list
  (git vs rename): new

* doc/emacs/trouble.texi: Move user-level information from CONTRIBUTE

* lisp/startup.el (fancy-about-text): change buttons for etc/CONTRIBUTE
  to (info "(emacs)Contributing")
---
 CONTRIBUTE             | 267 ++++++++++++++-----------------------------------
 ChangeLog              |  19 ++++
 doc/emacs/trouble.texi | 240 ++++++++++++++++++++++++++++++++++++++++----
 lisp/startup.el        |   8 +-
 4 files changed, 317 insertions(+), 217 deletions(-)

diff --git a/CONTRIBUTE b/CONTRIBUTE
index dc6fd71..a190bd9 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -1,196 +1,14 @@
-Copyright (C) 2006-2014 Free Software Foundation, Inc.
-See end for license conditions.
+This file contains information on Emacs developer processes.
 
+For information on contributing to Emacs as a non-developer, see
+(info "(emacs)Contributing") or
+http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
 
-			Contributing to Emacs
-
-Emacs is a collaborative project and we encourage contributions from
-anyone and everyone.  If you want to contribute in the way that will
-help us most, we recommend (1) fixing reported bugs and (2)
-implementing the feature ideas in etc/TODO.  However, if you think of
-new features to add, please suggest them too -- we might like your
-idea.  Porting to new platforms is also useful, when there is a new
-platform, but that is not common nowadays.
-
-For documentation on Emacs (to understand how to implement your
-desired change), refer to:
-
-- the Emacs Manual
-  http://www.gnu.org/software/emacs/manual/emacs.html
-  (info "(Emacs)Top")
-
-- the Emacs Lisp Reference Manual
-  http://www.gnu.org/software/emacs/manual/elisp.html
-  (info "(elisp)Top")
-
-- http://www.gnu.org/software/emacs
-
-- http://www.emacswiki.org/
-
-There are many ways to contribute to Emacs:
-
-- implement a new feature, and submit a patch (see "Submitting
-  Patches" below).
-
-- answer questions on the Emacs user mailing list
-  https://lists.gnu.org/mailman/listinfo/help-gnu-emacs
-
-- write documentation, either on the wiki, or in the Emacs source
-  repository (see "Submitting Patches" below)
-
-- find and report bugs; use M-x report-emacs-bug
-
-- check if existing bug reports are fixed in newer versions of Emacs
-  http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs
-
-- develop a package that works with Emacs, and publish it on your own
-  or in Gnu ELPA (see admin/notes/elpa).
-
-Here are some style and legal conventions for contributors to Emacs:
-
-
-* Coding Standards
-
-Contributed code should follow the GNU Coding Standards
-(http://www.gnu.org/prep/standards/ - may also be available in info on
-your system).
-
-If it doesn't, we'll need to find someone to fix the code before we
-can use it.
-
-Emacs has additional style and coding conventions:
-
-- the "Tips" Appendix in the Emacs Lisp Reference
-  http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
-  (info "(elisp)Tips").
-
-- Avoid using `defadvice' or `eval-after-load' for Lisp code to be
-  included in Emacs.
-
-- Remove all trailing whitespace in all source and text files.
-
-- Emacs has no convention on whether to use tabs in source code;
-  please don't change whitespace in the files you edit.
-
-- Use ?\s instead of ?  in Lisp code for a space character.
-
-* Copyright Assignment
-
-The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
-The FSF is a nonprofit with a worldwide mission to promote computer
-user freedom and to defend the rights of all free software users.
-For general information, see the website http://www.fsf.org/ .
-
-Generally speaking, for non-trivial contributions to GNU Emacs we
-require that the copyright be assigned to the FSF.  For the reasons
-behind this, see: http://www.gnu.org/licenses/why-assign.html .
-
-Copyright assignment is a simple process.  Residents of some countries
-can do it entirely electronically.  We can help you get started, and
-answer any questions you may have (or point you to the people with the
-answers), at the emacs-devel@gnu.org mailing list.
-
-(Please note: general discussion about why some GNU projects ask
-for a copyright assignment is off-topic for emacs-devel.
-See gnu-misc-discuss instead.)
-
-A copyright disclaimer is also a possibility, but we prefer an assignment.
-Note that the disclaimer, like an assignment, involves you sending
-signed paperwork to the FSF (simply saying "this is in the public domain"
-is not enough).  Also, a disclaimer cannot be applied to future work, it
-has to be repeated each time you want to send something new.
-
-We can accept small changes (roughly, fewer than 15 lines) without
-an assignment.  This is a cumulative limit (e.g. three separate 5 line
-patches) over all your contributions.
-
-* Getting the Source Code
-
-The current working version of the Emacs source code is stored in a
-git repository on the Savannah web site
-(http://savannah.gnu.org/projects/emacs).  It is important to write
-your patch based on the current working version.  If you start from an
-older version, your patch may be outdated (so that maintainers will
-have a hard time applying it), or changes in Emacs may have made your
-patch unnecessary.
-
-After you have downloaded the repository source, you should read the file
-INSTALL.REPO for build instructions (they differ to some extent from a
-normal build).
-
-* Submitting Patches
-
-Every patch must have several pieces of information before we
-can properly evaluate it.
-
-When you have all these pieces, bundle them up in a mail message and
-send it to the developers.  Sending it to bug-gnu-emacs@gnu.org
-(which is the bug/feature list) is recommended, because that list
-is coupled to a tracking system that makes it easier to locate patches.
-If your patch is not complete and you think it needs more discussion,
-you might want to send it to emacs-devel@gnu.org instead.  If you
-revise your patch, send it as a followup to the initial topic.
-
-** Description
-
-For bug fixes, a description of the bug and how your patch fixes it.
-
-For new features, a description of the feature and your implementation.
-
-** ChangeLog
-
-A ChangeLog entry as plaintext (separate from the patch).
-
-See the existing ChangeLog files for format and content.  Note that,
-unlike some other projects, we do require ChangeLogs for
-documentation, i.e. Texinfo files.
-
-Ref: "Change Log Concepts" node of the GNU Coding Standards Info
-Manual, for how to write good log entries.
-http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
-
-When using git, commit messages should use ChangeLog format, with a
-single short line explaining the change, then an empty line, then
-unindented ChangeLog entries.  (Essentially, a commit message should
-be a duplicate of what the patch adds to the ChangeLog files.  We are
-planning to automate this better, to avoid the duplication.) You can
-use the Emacs functions log-edit-add-to-changelog or
-log-edit-insert-changelog to ease this process.
-
-** The patch itself.
-
-If you are accessing the Emacs repository, make sure your copy is
-up-to-date (e.g. with 'git pull').  You can commit your changes
-to a private branch and generate a patch from the master version
-by using
-	git format-patch master
-Or you can leave your changes uncommitted and use
-        git diff
-With no repository, you can use
-	diff -u OLD NEW
-
-** Mail format.
-
-We prefer to get the patches as plain text, either inline (be careful
-your mail client does not change line breaks) or as MIME attachments.
-
-** Please reread your patch before submitting it.
-
-** Do not mix changes.
-
-If you send several unrelated changes together, we will ask you to
-separate them so we can consider each of the changes by itself.
-
-** Do not make formatting changes.
-
-Making cosmetic formatting changes (indentation, etc) makes it harder
-to see what you have really changed.
-
-
-* Supplemental information for Emacs Developers.
+* Information for Emacs Developers.
 
 An "Emacs Developer" is someone who contributes a lot of code or
-documentation to the Emacs repository.
+documentation to the Emacs repository. Generally, they have write
+access to the Emacs git repository on Savannah.
 
 ** Write access to the Emacs repository.
 
@@ -213,6 +31,31 @@ entry in their name, not yours. git distinguishes between the author
 and the committer; use the --author option on the commit command to
 specify the actual author; the committer defaults to you.
 
+** commit messages
+
+When using git, commit messages should use ChangeLog format, with the
+following modifications:
+
+- Add a single short line explaining the change, then an empty line,
+  then unindented ChangeLog entries.
+
+  You can use various Emacs functions to ease this process; see (info
+  "(emacs)Change Log Commands") or
+  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
+
+- The summary line is limited to 72 characters (enforced by a commit
+  hook). If you have trouble making that a good summary, add a
+  paragraph below it, before the individual file descriptions.
+
+- If only a single file is changed, the summary line can be the normal
+  file first line (starting with the asterisk).  Then there is no
+  individual files section.
+
+- Explaining the rationale for a design choice is best done in comments
+  in the source code. However, sometimes it is useful to describe just
+  the rationale for a change; that can be done in the commit message
+  between the summary line and the file entries.
+
 ** Changelog notes
 
 - Emacs generally follows the GNU coding standards when it comes to
@@ -222,11 +65,25 @@ specify the actual author; the committer defaults to you.
   standards used to recommend) rather than 'like-this' (as they do
   now), because `...' is so widely used elsewhere in Emacs.
 
+- Some of the rules in the GNU coding standards section 5.2
+  "Commenting Your Work" also apply to Changelog entries: they must be
+  in English, and be complete sentences starting with a capital and
+  ending with a period (except the summary line should not end in a
+  period).
+
+  It is tempting to relax this rule for commit messages, since they
+  are somewhat transient.  However, they are preserved indefinitely,
+  and have a reasonable chance of being read in the future, so it's
+  better that they have good presentation.
+
 - There are multiple ChangeLogs in the emacs source; roughly one per
   high-level directory. The ChangeLog entry for a commit belongs in the
   lowest ChangeLog that is higher than or at the same level as any file
   changed by the commit.
 
+- Use the present tense; describe "what the change does", not "what
+  the change did".
+
 - Preferred form for several entries with the same content:
 
    * help.el (view-lossage):
@@ -235,7 +92,13 @@ specify the actual author; the committer defaults to you.
 
   (Rather than anything involving "ditto" and suchlike.)
 
-- In ChangeLog files, there is no standard or recommended way to
+- If the commit fixes a bug, add a separate line
+
+  Fixes: bug#NNNN
+
+  where NNNN is the bug number.
+
+- In ChangeLog entries, there is no standard or recommended way to
   identify revisions.
 
   One way to identify revisions is by quoting their summary line.
@@ -244,7 +107,7 @@ specify the actual author; the committer defaults to you.
   "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
   will suffice.
 
-- There is no need to make separate change log entries for files such
+- There is no need to make separate ChangeLog entries for files such
   as NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration
   of files such as 'configure'.  "There is no need" means you don't
   have to, but you can if you want to.
@@ -266,9 +129,8 @@ emacs-devel mailing list, and not anywhere else.
 The trunk branch is named "master" in git; release branches are named
 "emacs-nn" where "nn" is the major version.
 
-You must follow emacs-devel to know exactly what kinds of changes are
-allowed on what branch at any time. Announcements about the freeze
-(and other important events) will contain "ANNOUNCE" in the subject.
+Announcements about the freeze (and other important events) are made
+on the info-gnu-emacs mailing list.
 
 If you are fixing a bug that exists in the current release, be sure to
 commit it to the release branch; it will be merged to the master
@@ -287,6 +149,23 @@ then exclude that commit from the merge to trunk.
 See all the files in admin/notes/* . In particular, see
 admin/notes/newfile, see admin/notes/repo.
 
+*** git vs rename
+
+git does not explicitly represent a file renaming; it uses a percent
+changed heuristic to deduce that a file was renamed. So if you are
+planning to make extensive changes to a file after renaming it (or
+moving it to another directory), you should:
+
+- create a feature branch
+
+- commit the rename without any changes
+
+- make other changes
+
+- merge the feature branch to trunk, _not_ squashing the commits into
+  one. The commit message on this merge should summarize the renames
+  and all the changes.
+
 ** Emacs Mailing lists.
 
 Discussion about Emacs development takes place on emacs-devel@gnu.org.
diff --git a/ChangeLog b/ChangeLog
index ee109f7..8e74c02 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2014-12-19  Stephen Leake  <stephen_leake@stephe-leake.org>
+
+	Move user-level information from CONTRIBUTE to doc/emacs/trouble.texi
+
+	Fixes bug#19299
+
+	* CONTRIBUTE: Move user-level information to doc/emacs/trouble.texi
+	  (commit messages): new, gathered from comments on emacs-devel
+	  (Changelog notes): add reference to GNU coding standards section 5.2;
+	  doc 'present tense', bug fix format
+	  (branches): freeze announcements are made on info-gnu-emacs mailing
+	  list
+	  (git vs rename): new
+
+	* doc/emacs/trouble.texi: Move user-level information from CONTRIBUTE here
+
+	* lisp/startup.el (fancy-about-text): change buttons for etc/CONTRIBUTE
+	  to (info "(emacs)Contributing")
+
 2014-12-06  Stephen Leake  <stephen_leake@stephe-leake.org>
 
 	* CONTRIBUTE: Improve; add explicit web references, move some info
diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 5f3cf92..bae9cad 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1060,19 +1060,44 @@ but using it will take extra work.  Maintaining GNU Emacs is a lot of
 work in the best of circumstances, and we can't keep up unless you do
 your best to help.
 
+Every patch must have several pieces of information before we
+can properly evaluate it.
+
+When you have all these pieces, bundle them up in a mail message and
+send it to the developers.  Sending it to
+@email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is
+recommended, because that list is coupled to a tracking system that
+makes it easier to locate patches.  If your patch is not complete and
+you think it needs more discussion, you might want to send it to
+@email{emacs-devel@@gnu@@gnu.org} instead.  If you revise your patch,
+send it as a followup to the initial topic.
+
+We prefer to get the patches as plain text, either inline (be careful
+your mail client does not change line breaks) or as MIME attachments.
+
 @itemize @bullet
 @item
-Send an explanation with your changes of what problem they fix or what
-improvement they bring about.  For a fix for an existing bug, it is
+Include an explanation with your changes of what problem they fix or what
+improvement they bring about.
+
+@itemize
+@item
+For a fix for an existing bug, it is
 best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
 list, or the bug entry in the GNU Bug Tracker at
 @url{http://debbugs.gnu.org}.  Explain why your change fixes the bug.
 
 @item
-Always include a proper bug report for the problem you think you have
-fixed.  We need to convince ourselves that the change is right before
-installing it.  Even if it is correct, we might have trouble
-understanding it if we don't have a way to reproduce the problem.
+For a new feature, include a description of the feature and your
+implementation.
+
+@item
+For a new bug, include a proper bug report for the problem you think
+you have fixed.  We need to convince ourselves that the change is
+right before installing it.  Even if it is correct, we might have
+trouble understanding it if we don't have a way to reproduce the
+problem.
+@end itemize
 
 @item
 Include all the comments that are appropriate to help people reading the
@@ -1104,6 +1129,8 @@ right away.  That gives us the option of installing it immediately if it
 is important.
 
 @item
+The patch itself.
+
 Use @samp{diff -c} to make your diffs.  Diffs without context are hard
 to install reliably.  More than that, they are hard to study; we must
 always study a patch to decide whether we want to install it.  Unidiff
@@ -1114,6 +1141,12 @@ If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when
 making diffs of C code.  This shows the name of the function that each
 change occurs in.
 
+If you are using the Emacs repository, make sure your copy is
+up-to-date (e.g. with @code{git pull}).  You can commit your changes
+to a private branch and generate a patch from the master version by
+using @code{git format-patch master}. Or you can leave your changes
+uncommitted and use @code{git diff}.
+
 @item
 Avoid any ambiguity as to which is the old version and which is the new.
 Please make the old version the first argument to diff, and the new
@@ -1138,8 +1171,16 @@ feel that the purpose needs explaining, it probably does---but put the
 explanation in comments in the code.  It will be more useful there.
 
 Please look at the change log entries of recent commits to see what
-sorts of information to put in, and to learn the style that we use.
-@xref{Change Log}.
+sorts of information to put in, and to learn the style that we use. Note that,
+unlike some other projects, we do require change logs for
+documentation, i.e. Texinfo files.
+@xref{Change Log},
+@ifset WWW_GNU_ORG
+see
+@url{http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
+@end ifset
+@xref{Change Log Concepts, Change Log Concepts,
+Change Log Concepts, gnu-coding-standards, GNU Coding Standards}.
 
 @item
 When you write the fix, keep in mind that we can't install a change that
@@ -1160,11 +1201,52 @@ Please help us keep up with the workload by designing the patch in a
 form that is clearly safe to install.
 @end itemize
 
-@c FIXME: Include the node above?
 @node Contributing
 @section Contributing to Emacs Development
 @cindex contributing to Emacs
 
+Emacs is a collaborative project and we encourage contributions from
+anyone and everyone.
+
+There are many ways to contribute to Emacs:
+
+@itemize
+@item
+find and report bugs; @xref{Bugs}.
+
+@item
+answer questions on the Emacs user mailing list
+@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
+
+@item
+write documentation, either on the wiki, or in the Emacs source
+repository (@pxref{Sending Patches}).
+
+@item
+check if existing bug reports are fixed in newer versions of Emacs
+@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
+
+@item
+fix existing bug reports
+@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
+
+@item
+@c etc/TOOD not in WWW_GNU_ORG
+implement a feature listed in the @file{etc/TODO} file in the Emacs
+distribution, and submit a patch.
+
+@item
+implement a new feature, and submit a patch.
+
+@item
+develop a package that works with Emacs, and publish it on your own
+or in Gnu ELPA (@url{https://elpa.gnu.org/}).
+
+@item
+port Emacs to a new platform, but that is not common nowadays.
+
+@end itemize
+
 If you would like to work on improving Emacs, please contact the maintainers at
 @ifnothtml
 @email{emacs-devel@@gnu.org}.
@@ -1186,24 +1268,148 @@ you have not yet started work, it is useful to contact
 before you start; it might be possible to suggest ways to make your
 extension fit in better with the rest of Emacs.
 
+When implementing a feature, please follow the Emacs coding standards;
+@xref{Coding Standards}. In addition, non-trivial contributions
+require a copyright assignment to the FSF; @xref{Copyright Assignment}.
+
 The development version of Emacs can be downloaded from the
 repository where it is actively maintained by a group of developers.
 See the Emacs project page
-@url{http://savannah.gnu.org/projects/emacs/} for details.
+@url{http://savannah.gnu.org/projects/emacs/} for access details.
+
+It is important to write your patch based on the current working
+version.  If you start from an older version, your patch may be
+outdated (so that maintainers will have a hard time applying it), or
+changes in Emacs may have made your patch unnecessary. After you have
+downloaded the repository source, you should read the file
+@file{INSTALL.REPO} for build instructions (they differ to some extent
+from a normal build).
+
+If you would like to make more extensive contributions, see the
+@file{./CONTRIBUTE} file in the Emacs distribution for information on
+how to be an Emacs developer.
+
+For documentation on Emacs (to understand how to implement your
+desired change), refer to:
+
+@itemize
+@item
+@ifset WWW_GNU_ORG
+@ifhtml
+the Emacs Manual
+@url{http://www.gnu.org/software/emacs/manual/emacs.html}.
+@end ifhtml
+@ifnothtml
+@xref{Top, Emacs Manual,,emacs}.
+@end ifnothtml
+@end ifset
+@ifclear WWW_GNU_ORG
+@xref{Top, Emacs Manual,,emacs}.
+@end ifclear
+
+@item
+@ifset WWW_GNU_ORG
+@ifhtml
+the Emacs Lisp Reference Manual
+@url{http://www.gnu.org/software/emacs/manual/elisp.html}.
+@end ifhtml
+@ifnothtml
+@xref{Top, Emacs Lisp Reference Manual,,elisp}.
+@end ifnothtml
+@end ifset
+@ifclear WWW_GNU_ORG
+@xref{Top, Emacs Lisp Reference Manual,,elisp}.
+@end ifclear
+
+@item
+@url{http://www.gnu.org/software/emacs}
+
+@item
+@url{http://www.emacswiki.org/}
+@end itemize
+
+@menu
+* Coding Standards::        Gnu Emacs coding standards
+* Copyright Assignment::    assigning copyright to the FSF
+@end menu
 
-For more information on how to contribute, see the
+@node Coding Standards
+@subsection Coding Standards
+@cindex coding standards
+
+Contributed code should follow the GNU Coding Standards
+@url{http://www.gnu.org/prep/standards/}. This may also be available
+in info on your system.
+
+If it doesn't, we'll need to find someone to fix the code before we
+can use it.
+
+Emacs has additional style and coding conventions:
+
+@itemize
+@item
 @ifset WWW_GNU_ORG
 @ifhtml
-@url{http://gnu.org/software/emacs/CONTRIBUTE, etc/CONTRIBUTE}
+the "Tips" Appendix in the Emacs Lisp Reference
+@url{http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}.
 @end ifhtml
 @ifnothtml
-@file{etc/CONTRIBUTE}
+@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
+Appendix, elisp, Emacs Lisp Reference}.
 @end ifnothtml
 @end ifset
 @ifclear WWW_GNU_ORG
-@file{etc/CONTRIBUTE}
+@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
+Appendix, elisp, Emacs Lisp Reference}.
 @end ifclear
-file in the Emacs distribution.
+
+@item
+Avoid using @code{defadvice} or @code{eval-after-load} for Lisp code
+to be included in Emacs.
+
+@item
+Remove all trailing whitespace in all source and text files.
+
+@item
+Emacs has no convention on whether to use tabs in source code; please
+don't change whitespace in the files you edit.
+
+@item
+Use @code{?\s} instead of @code{? } in Lisp code for a space character.
+
+@end itemize
+
+@node Copyright Assignment
+@subsection Copyright Assignment
+@cindex copyright assignment
+
+The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
+The FSF is a nonprofit with a worldwide mission to promote computer
+user freedom and to defend the rights of all free software users.
+For general information, see the website @url{http://www.fsf.org/}.
+
+Generally speaking, for non-trivial contributions to GNU Emacs we
+require that the copyright be assigned to the FSF.  For the reasons
+behind this, see @url{http://www.gnu.org/licenses/why-assign.html}.
+
+Copyright assignment is a simple process.  Residents of some countries
+can do it entirely electronically.  We can help you get started, and
+answer any questions you may have (or point you to the people with the
+answers), at the @email{emacs-devel@@gnu.org} mailing list.
+
+(Please note: general discussion about why some GNU projects ask
+for a copyright assignment is off-topic for emacs-devel.
+See gnu-misc-discuss instead.)
+
+A copyright disclaimer is also a possibility, but we prefer an assignment.
+Note that the disclaimer, like an assignment, involves you sending
+signed paperwork to the FSF (simply saying "this is in the public domain"
+is not enough).  Also, a disclaimer cannot be applied to future work, it
+has to be repeated each time you want to send something new.
+
+We can accept small changes (roughly, fewer than 15 lines) without
+an assignment.  This is a cumulative limit (e.g. three separate 5 line
+patches) over all your contributions.
 
 @node Service
 @section How To Get Help with GNU Emacs
@@ -1211,8 +1417,8 @@ file in the Emacs distribution.
 @cindex help-gnu-emacs mailing list
 @cindex gnu.emacs.help newsgroup
 
-If you need help installing, using or changing GNU Emacs, there are two
-ways to find it:
+If you need help installing, using or changing GNU Emacs, there are
+two ways to find it:
 
 @itemize @bullet
 @item
diff --git a/lisp/startup.el b/lisp/startup.el
index c04b16c..8e981bb 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1463,9 +1463,7 @@ Each element in the list should be a list of strings or pairs
 	      (goto-char (point-min))))
      "\tMany people have contributed code included in GNU Emacs\n"
      :link ("Contributing"
-	    ,(lambda (_button)
-	      (view-file (expand-file-name "CONTRIBUTE" data-directory))
-	      (goto-char (point-min))))
+	    ,(lambda (_button) (info "(emacs)Contributing")))
      "\tHow to contribute improvements to Emacs\n"
      "\n"
      :link ("GNU and Freedom" ,(lambda (_button) (describe-gnu-project)))
@@ -2039,9 +2037,7 @@ Type \\[describe-distribution] for information on "))
 
   (insert-button "Contributing"
 		 'action
-		 (lambda (_button)
-		   (view-file (expand-file-name "CONTRIBUTE" data-directory))
-		   (goto-char (point-min)))
+		 (lambda (_button) (info "(emacs)Contributing"))
 		 'follow-link t)
   (insert "\tHow to contribute improvements to Emacs\n\n")
 
-- 
2.1.1

Re: Results of the "mentoring" experiment

[João Távora]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> joaotavora@gmail.com (João Távora) writes:
>
>> * I found that the information that is sought after in this phase is
>>   practically all written down and available already, but spread across
>>   the Elisp manual, wikipedia, the ELPA.git README, git tutorials,
>>   etc. A nice aggregation of this information would be useful, but this
>>   was in the original discussion I believe.
>
> I'm cleaning up this info; can you send me a list?

These are the ones I remember from the top of my head: there is
obviously more info around. There is also a lot of overlap. Without any
mentoring whatsoever, I'd say this is the minimal set for the common
case: cleaning up some rotten hack on github and contributing to
ELPA.git. Though most of it also applies to contributions to Emacs
trunk of course.

* https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html

* https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html#Tips

  Particularly the nodes "Coding Conventions" and "Library Headers". I
  think M-x auto-insert should be mentioned in there somewhere.

* etc/CONTRIBUTE or CONTRIBUTE

* http://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README (very
  useful).

* http://www.emacswiki.org/emacs/GitForEmacsDevs (emacswiki is down
  right now but I think there is also has a quick-start variant):

* http://www.emacswiki.org/emacs/ELPA#toc2

* https://savannah.gnu.org/git/?group=emacs and its linked
  http://savannah.gnu.org/maintenance/UsingGit/, which is mostly
  duplication maybe?

  I had git credentials already, so I don't know about the patch
  process if there is one (in the past I just sent them to this list or
  the bug tracker).

Some useful non-GNU stuff

* http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/

* https://hpc.uni.lu/blog/2014/understanding-git-subtree/

> Attached is my current patch, splitting CONTRIBUTE into user vs
> developer stuff; user stuff is now in the Emacs manual.

Sorry, didn't see it and didn't follow that part of the discussion. Were
you looking for comments on any specific part of it? 

João

Re: Results of the "mentoring" experiment

[João Távora]

  [ sorry for the duplicate reply I sent the previous one from my work
    address and can't recall it. Please reply to this address. ]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> joaotavora@gmail.com (João Távora) writes:
>
>> * I found that the information that is sought after in this phase is
>>   practically all written down and available already, but spread across
>>   the Elisp manual, wikipedia, the ELPA.git README, git tutorials,
>>   etc. A nice aggregation of this information would be useful, but this
>>   was in the original discussion I believe.
>
> I'm cleaning up this info; can you send me a list?

These are the ones I remember from the top of my head: there is
obviously more info around. There is also a lot of overlap. Without any
mentoring whatsoever, I'd say this is the minimal set for the common
case: cleaning up some rotten hack on github and contributing to
ELPA.git. Though most of it also applies to contributions to Emacs
trunk of course.

* https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html

* https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html#Tips

  Particularly the nodes "Coding Conventions" and "Library Headers". I
  think M-x auto-insert should be mentioned in there somewhere.

* etc/CONTRIBUTE or CONTRIBUTE

* http://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README (very
  useful).

* http://www.emacswiki.org/emacs/GitForEmacsDevs (emacswiki is down
  right now but I think there is also has a quick-start variant):

* http://www.emacswiki.org/emacs/ELPA#toc2

* https://savannah.gnu.org/git/?group=emacs and its linked
  http://savannah.gnu.org/maintenance/UsingGit/, which is mostly
  duplication maybe?

  I had git credentials already, so I don't know about the patch
  process if there is one (in the past I just sent them to this list or
  the bug tracker).

Some useful non-GNU stuff

* http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/

* https://hpc.uni.lu/blog/2014/understanding-git-subtree/

> Attached is my current patch, splitting CONTRIBUTE into user vs
> developer stuff; user stuff is now in the Emacs manual.

Sorry, didn't see it and didn't follow that part of the discussion. Were
you looking for comments on any specific part of it? 

João

Re: Metaproblem, part 3

[Phillip Lord]

João Távora <joaotavora@gmail.com> writes:
> I hope I did clarify a bit, but ideally others can pitch in. I think
> simulating a hypothetic platonic dialog between "JR Hacker" and "JR
> Mentor" would be a good format to pitch in. Phillip, what would be the
> ideal dialog between mentor and mentoree be?


I think you have got it about right. As an example, I had two
discussions with Stefan off-list. One about ELPA (where I contributed a
package). I told him what my problem was (that I synchronize my work
between machines and cloning all of ELPA was problematic for me). He
hold me the solution.

Another time I asked what I know is a stupid question, which is, why is
my ssh private key not working. He said, can't help you with that, but
the savannah mailing list will. And they did.

I know it's a stupid question because I'd been teaching my students
about it ssh keys two days before. It's very frustrating to have a
problem that you know you should be able to fix.

Right, said I would say no more in the last post!

Phil

Re: Metaproblem, part 3

[Eric Abrahamsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joaotavora@gmail.com (João Távora)
>> Date: Fri, 05 Dec 2014 10:27:49 +0000
>> Cc: esr@thyrsus.com, phillip.lord@newcastle.ac.uk, emacs-devel@gnu.org
>> 
>> As you pointed out, mentorship happens on emacs-devel and on
>> bug-gnu-emacs. But also as you pointed out, a lot of effort goes into
>> questions only tangentially related to Emacs.
>> 
>> The proposed mentoring would be targeted at first time code
>> contributions only and administered by anyone with a reasonably solid
>> grasp of Emacs's and GNU's red tape.
>> 
>> >From my (limited) perspective this is frequently channeled to Stefan,
>> who is really good at it, but is possibly overloaded.
>> 
>> So what is being proposed, or what at least what I understood from
>> Phillip's message, is that a new broad guideline is added to the top of
>> the contribution guide [1] reading something like:
>> 
>>   "If this is your first time contributing to Emacs, ask for a mentor on
>>   emacs-devel first. A mentor can be anyone who has contributed to Emacs
>>   at least once, and will guide you through the instructions [linked]
>>   below, as well as any extra documentation. He/she can also answer
>>   specific questions about copyright assignment, version control,
>>   changelogs, coding style, etc."
>
> OK, so how would this mentoring be different from what we have now?
> Does it happen in private email instead of on the list?  If it's still
> on the list, do we formally tell people stay out of the
> mentor/mentoree dialog and let the mentor alone handle that?  Or is
> the only difference that a specific person will step forward and say
> he/she will be the mentor for a particular J.R. Hacker, and all the
> rest should stay as it is today?
>
> IOW, I have a difficulty translating the above principles (with which
> I agree) into practical steps that need to be made, to make the
> procedure different from what it is now.  Can you please clarify?

A brief two cents to add to Phillip, who seems to be in exactly the same
position as me:

It would be nice to explicitly let posters know that they can ask
someone for help with implementing a feature/squashing a bug. There's
lots of helpful advice here and on emacs.help, but that's not quite the
same as knowing that someone has committed (to some extent) to assisting
you.

"Mentoring", to me, also implies that the purpose of the process is, in
large part, the education of the mentoreee.

The above is totally contingent on someone having the time and patience
to take on "students", and I think silence in response to a request for
mentoring should be quite normal.

I'd lean towards on-list discussions, with the assumption that most
people will ignore them.

Eric

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Date: Fri, 05 Dec 2014 21:20:22 +0800
> 
> It would be nice to explicitly let posters know that they can ask
> someone for help with implementing a feature/squashing a bug. There's
> lots of helpful advice here and on emacs.help, but that's not quite the
> same as knowing that someone has committed (to some extent) to assisting
> you.

I don't know how to do that.  The offer of help is implicit on this
list, and if someone needs to see it explicitly, then here it is.

> The above is totally contingent on someone having the time and patience
> to take on "students", and I think silence in response to a request for
> mentoring should be quite normal.
> 
> I'd lean towards on-list discussions, with the assumption that most
> people will ignore them.

I think we already have quite a lot of that going on, but if some
labels on the subject line could help, let's do it.

Re: Metaproblem, part 3

[Stephen J. Turnbull]

Eric Abrahamsen writes:

 > It would be nice to explicitly let posters know that they can ask
 > someone for help with implementing a feature/squashing a
 > bug. There's lots of helpful advice here and on emacs.help, but
 > that's not quite the same as knowing that someone has committed (to
 > some extent) to assisting you.

I see worries about "hostile" environment, and suggestions for making
things more welcoming to new contributors.  I have to ask, what do all
you folks who are suggesting Emacs change its procedures think is in
it for the mentors and core developers?

Re: Metaproblem, part 3

[Eric S. Raymond]

Stephen J. Turnbull <stephen@xemacs.org>:
> I see worries about "hostile" environment, and suggestions for making
> things more welcoming to new contributors.  I have to ask, what do all
> you folks who are suggesting Emacs change its procedures think is in
> it for the mentors and core developers?

A future for Emacs.

I'm trying to get the project moving in a direction that will lower
barriers to entry and attract new developers because I'm seriously
concerned that without such changes Emacs will ossify and dwindle into
irrelevance.

There are lots of other claims on my time.  There are many things I would
rather be doing than having the kinds of arguments this aim will 
inecitably land me in.

But I think it's important enough that I'm here.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: Metaproblem, part 3

[Eli Zaretskii]

> Date: Sat, 6 Dec 2014 01:18:07 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Eric Abrahamsen <eric@ericabrahamsen.net>, emacs-devel@gnu.org
> 
> Stephen J. Turnbull <stephen@xemacs.org>:
> > I see worries about "hostile" environment, and suggestions for making
> > things more welcoming to new contributors.  I have to ask, what do all
> > you folks who are suggesting Emacs change its procedures think is in
> > it for the mentors and core developers?
> 
> A future for Emacs.

That's a slogan.  You are trying to sell that to us, but so far you've
failed.

> I'm trying to get the project moving in a direction that will lower
> barriers to entry and attract new developers because I'm seriously
> concerned that without such changes Emacs will ossify and dwindle into
> irrelevance.

A laudable goal, but doing so requires a good analysis of what are the
barriers and how to lower them in practice.  Your suggestions are a
clear evidence that your analysis, if it was done, is incorrect and
misguided, and as result you are trying to solve the wrong problems
using methods that are dead wrong.  The controversy that follows
speaks volumes about that.

Re: Metaproblem, part 3

[Stephen J. Turnbull]

Eric S. Raymond writes:
 > Stephen J. Turnbull <stephen@xemacs.org>:

 > > I see worries about "hostile" environment, and suggestions for
 > > making things more welcoming to new contributors.  I have to ask,
 > > what do all you folks who are suggesting Emacs change its
 > > procedures think is in it for the mentors and core developers?
 > 
 > A future for Emacs.

Nonsense.  Emacs surely has a future (!= "oblivion").  You want a
*different* future for Emacs than the one it's heading toward now.

My question is what is *that* future, and what's in it for the current
crew of developers?

 > I'm trying to get the project moving in a direction that will lower
 > barriers to entry and attract new developers

That would be nice, as long as they are able to contribute at the
level of coherence with existing facilities and the level of quality
demanded of a platform.  It's not obvious to me that the kinds of
changes you're insisting on will attract the kind of developer that
I believe Emacs needs.  OTOH, it might chase some of the ones it has
already into early retirement.

And note well: I'm not sure you meant it the way it sounds, but lower
barriers to entry don't attract entry.  Expected profits do.
Contributing to Emacs *is* like contributing to an OS kernel, or to a
production-quality language translator, or a debugger, or a security
library.  High quality is demanded, and a large fraction of
submissions require substantial rewrites and often design changes to
be acceptable.  That drives the cost for drive-bys way up (not to
mention a bit for the reviewers).

 > because I'm seriously concerned that without such changes Emacs
 > will ossify and dwindle into irrelevance.

I don't see ossification, nor do I expect it, and I'm not sure why you
do.  Nor can irrelevance be remedied by drive-by contributors.

I think you're likely making the same mistake that economic pundits
have made repeatedly concerning the decline of the US economy.  Emacs
development is very resilient, just as American industry has been.[1]

I'll also mention another analogy: note that many of the same business
practices that Japan has made famous have been of no help when grafted
into foreign firms, at least as the Japanese do them.  Sometimes they
were doomed to failure because they required ripping the organization
apart to fit it into the Japanese mold, and in other cases they
required careful adaptation to U.S. and European contexts.

Moral: I see no hurry to fix what could be better, but ain't yet
broke.  "To everything there is a season."  This season was git's.
It's time to rest on your laurels for a while.  Emacs will still be
here when you're again ready for it, and it for you. ;-)

 > There are many things I would rather be doing than having the kinds
 > of arguments this aim will inecitably land me in.

It's hardly inevitable that there be arguments about doing the things
being proposed here.  What makes the arguments inevitable is you want
to do them now, directly changing the current infrastructure (which
necessarily interferes with the work of the core developers), and with
promises of acceptance etc.

Karl wants to put the new "contributor docs" in www/ under source.
Why not create a subproject with a modern workflow (and modern
infrastructure)?  That might not be a good answer in other projects,
but it deserves consideration in Emacs because Emacs has a long
history of successful decentralized subprojects.  Savannah would host
them, I'm sure, in git.  You can use the existing emacs-devel list or
a new list (also GNU-hosted).  I don't know about tracker
infrastructure, but surely between the two of you you can scare up a
proof-of-concept host.

You want to move away from Texinfo.  The issue there IMHO is that all
of the HTML docs (even Sphinx) are beat by Info because (1) the
navigation tools provided are poor and nonstandard except for
hyperlinks (most important), (2) HTML is ugly in Emacs and therefore
requires starting up a browser (hardly agile and changes focus, as
well as affecting my browsing reflexes), and (3) they lack good
indexes (the indicies generated by Texinfo at
https://www.gnu.org/software/emacs/manual/html_node/emacs/ are better
than nothing, but hardly great).  On top of that, conversion of the
doc tree will be a large effort.  Why fix what really ain't broke?
It's not important that your opinion differs from mine -- what matters
is that an awful lot of people agree with me that the only immediately
available direction from the current doc system is *down*.

But OK, reasonable people might say Emacs doc system is broke.  So
port the Elisp manual to your proposed efficient and beautiful source
format, and demonstrate satisfactory navigation tools for several
target formats and an excellent target format that runs in Emacs, and
you'll have a *lot* of support and *much* less resistence.  And guess
what?  You can do this in a separate branch too, and the same
considerations as for the new website apply.  Of course the format
change will make merging changes between the branch and the mainline a
pain in the interim, but if it's not worth that small amount of pain,
I have to question the need for the whole project.

The issue tracker is a different dimension.  There are big gains
possible there, but yes, as somebody complained, *all* of the effort
needs to come from outside the maintainer group -- who are a key
constituency for a tracker.  The maintainers are definitely going to
suffer severe disruption in their time allocation (due to requirements
specification before the switch, and changes in workflow after) and in
their workflow post-switch.

For all of the above, build it and they will come, I'm pretty sure --
your time won't be wasted.  But ask them to do much of the work, or
buy a pig in a poke -- you'll get resistence.

The Emacs development community is in a box and not realizing its
potential, I'll admit, and out-of-the-box thinking is needed.  What
you and Karl are missing is that the projects on which you base your
New Conventional Wisdom are in their own box, and the thinking Emacs
needs is, IMHO, outside of *that* box too!

 > But I think it's important enough that I'm here.

<rant>
If you think it's that important, you'll stifle yourself and address
the single most important issue, which is making the population of
potential reviewers and mentors of the fresh blood happy with your
changes.  Those are the current core devs and maintainers.
</rant>

You say, "you build it and they (the fresh blood) will come".  My
guess is a trickle -- Lisp, let alone Emacs Lisp, is a barrier, as is
the collection of (by modern standards) crufty old coding idioms in C.
Again, I say "you (Eric and Karl) build it and they (the existing core
and maintainership) will come."  That's a no-brainer because they're
already here, aren't going anywhere, and your new infrastructure is
going to be as good as you say, right?  Anything *that* good, the
maintainers will notice![2]

"Even in Emacs"[sic], there is no shortage of drive-by contributors.
But Emacs Lisp is more than an "extension language"; along with Emacs
itself it is a complete application development and runtime support
platform.  What Emacs core needs, far more so than org-mode or "Battle
for Wesnoth" or even Subversion does, is developers who have a pretty
good knowledge of a fair slice of the code base and deep knowledge of
some piece of it, to be to able review and mentor others, as well as
to keep the code base sane.[3]  Of course, such developers must be
completely ignorant of Emacs at some point in their lives!  But to
bring them up to speed in reasonable time requires not only mentoring,
but dedicated unsexy study and repeated submission to correction on
the part of the wannabe core developer.  If Texinfo and debbugs scare
someone away, I doubt they were core material in the first place.
(That's not saying at least a better website and bug tracker aren't
obviously good ideas, just that I doubt they'll have that much effect
on new blood, and if not the impact on maintainers had better be
minimal.)


Footnotes: 
[1]  And yes, there are real problems, in both Emacs and the American
economy.  But no need to ask for Last Rites for either.

[2]  And no, they don't have to be fools to fail to see how wonderful
it will be.  They just have to be not-you.  I don't see it either, and
I work with a lot of the tools you espouse.

[3]  That's why the "bias" that Karl noticed in Eli's list of projects
whose practices are similar to Emacs's probably means that they are an
appropriate peer group for comparison, rather than a sample hopelessly
unrepresentative of best current practice.

Re: Metaproblem, part 3

[Eric Abrahamsen]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Eric Abrahamsen writes:
>
>  > It would be nice to explicitly let posters know that they can ask
>  > someone for help with implementing a feature/squashing a
>  > bug. There's lots of helpful advice here and on emacs.help, but
>  > that's not quite the same as knowing that someone has committed (to
>  > some extent) to assisting you.
>
> I see worries about "hostile" environment, and suggestions for making
> things more welcoming to new contributors.  I have to ask, what do all
> you folks who are suggesting Emacs change its procedures think is in
> it for the mentors and core developers?

FWIW (not much), I have never felt any hostility here or in emacs.help,
and I'm not complaining about anything. Possibly I haven't felt it
because I'm coming in at such a low level that no nerves are touched --
I'm asking basic questions.

The only reason I chimed in is because I'm one of those who would love
to contribute more substantially, but needs guidance. For example, I've
got the basics of an epub-editing mode in place. I'd like it to be a
solid library, and would likely need assistance to get it there.

What's in it for the mentors and core developers is that, a few years
from now, I'd like to be making larger contributions to the Emacs core.
Mentoring would help me get there.

Eric

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Date: Sat, 06 Dec 2014 16:29:40 +0800
> 
> The only reason I chimed in is because I'm one of those who would love
> to contribute more substantially, but needs guidance. For example, I've
> got the basics of an epub-editing mode in place. I'd like it to be a
> solid library, and would likely need assistance to get it there.

Please feel free to ask your questions.  My suggestion would be to ask
here if the questions are general enough and not related to any
specific code.  Once you get to the stage where you have something
working that you aren't ashamed to publish, I suggest to submit it as
a patch to the bug tracker, and ask for review and specific advice
there.

TIA

Re: Metaproblem, part 3

[Eric Abrahamsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> Date: Sat, 06 Dec 2014 16:29:40 +0800
>> 
>> The only reason I chimed in is because I'm one of those who would love
>> to contribute more substantially, but needs guidance. For example, I've
>> got the basics of an epub-editing mode in place. I'd like it to be a
>> solid library, and would likely need assistance to get it there.
>
> Please feel free to ask your questions.  My suggestion would be to ask
> here if the questions are general enough and not related to any
> specific code.  Once you get to the stage where you have something
> working that you aren't ashamed to publish, I suggest to submit it as
> a patch to the bug tracker, and ask for review and specific advice
> there.

That's good guidance, actually -- general questions to the list,
code-specific questions to the bug tracker.

I'm imagining this package as destined for ELPA (no real reason, it just
seems to fit there). Is the bug tracker an appropriate place to discuss
external packages?

E

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Date: Sat, 06 Dec 2014 18:40:02 +0800
> 
> Is the bug tracker an appropriate place to discuss external
> packages?

I see no reason why not, but please wait for Glenn and/or Stefan to
reply.

Re: Metaproblem, part 3

[David Kastrup]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> "Stephen J. Turnbull" <stephen@xemacs.org> writes:
>
>> Eric Abrahamsen writes:
>>
>>  > It would be nice to explicitly let posters know that they can ask
>>  > someone for help with implementing a feature/squashing a
>>  > bug. There's lots of helpful advice here and on emacs.help, but
>>  > that's not quite the same as knowing that someone has committed
>>  > (to some extent) to assisting you.
>>
>> I see worries about "hostile" environment, and suggestions for making
>> things more welcoming to new contributors.  I have to ask, what do
>> all you folks who are suggesting Emacs change its procedures think is
>> in it for the mentors and core developers?
>
> FWIW (not much), I have never felt any hostility here or in emacs.help,
> and I'm not complaining about anything. Possibly I haven't felt it
> because I'm coming in at such a low level that no nerves are touched --
> I'm asking basic questions.

See, that's your mistake.  The first steps towards feeling hostility on
developer lists is to tell people that they are doing it all wrong but
they are lucky you came around to tell them.  There are a lot of
variations on the theme, of course.  But if you feel that a technical
mailing list as such rather than, say, an isolated person having a bad
day, act hostile, chances are that you score in that area.

> The only reason I chimed in is because I'm one of those who would love
> to contribute more substantially, but needs guidance. For example,
> I've got the basics of an epub-editing mode in place. I'd like it to
> be a solid library, and would likely need assistance to get it there.

Can you figure out what is missing and phrase it into questions?  While
there is the phenomenon that if you are asking 10 people, you'll get 20
answers, I think that for basic problems the Emacs list will not split
into so many different factions of "do it my way" that you'll get much
more confusing answers from the group of people reading this list than
you would get from a single tutor.

-- 
David Kastrup

Re: Metaproblem, part 3

[Ivan Shmakov]

>>>>> David Kastrup <dak@gnu.org> writes:
>>>>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:

[…]

 >> The only reason I chimed in is because I'm one of those who would
 >> love to contribute more substantially, but needs guidance.  For
 >> example, I've got the basics of an epub-editing mode in place.  I'd
 >> like it to be a solid library, and would likely need assistance to
 >> get it there.

 > Can you figure out what is missing and phrase it into questions?
 > While there is the phenomenon that if you are asking 10 people,
 > you'll get 20 answers, I think that for basic problems the Emacs list
 > will not split into so many different factions of "do it my way" that
 > you'll get much more confusing answers from the group of people
 > reading this list than you would get from a single tutor.

	Furthermore, that’s where the discrepancy between vocality and
	productivity (so to say) may come to be an issue.

	My personal approach to the “how should I do this?” problem is
	to read the existing code.  (Literacy is gained first and
	foremost by reading, – not writing; computer literacy isn’t all
	that different.)  Hence, when I have an idea for which I could
	readily think of several implementations, my better question
	would be not “what of the following should I choose?” but rather
	“I want to do X; could you please point me to the existing code
	that does something like that?”

	And there, the more of the code I’ll be pointed to, and the more
	of that I’ll read through, the more informed my choice will be.

-- 
FSF associate member #7257  http://boycottsystemd.org/  … 3013 B6A0 230E 334A

Re: Metaproblem, part 3

[Eric Abrahamsen]

David Kastrup <dak@gnu.org> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> "Stephen J. Turnbull" <stephen@xemacs.org> writes:
>>
>>> Eric Abrahamsen writes:
>>>
>>>  > It would be nice to explicitly let posters know that they can ask
>>>  > someone for help with implementing a feature/squashing a
>>>  > bug. There's lots of helpful advice here and on emacs.help, but
>>>  > that's not quite the same as knowing that someone has committed
>>>  > (to some extent) to assisting you.
>>>
>>> I see worries about "hostile" environment, and suggestions for making
>>> things more welcoming to new contributors.  I have to ask, what do
>>> all you folks who are suggesting Emacs change its procedures think is
>>> in it for the mentors and core developers?
>>
>> FWIW (not much), I have never felt any hostility here or in emacs.help,
>> and I'm not complaining about anything. Possibly I haven't felt it
>> because I'm coming in at such a low level that no nerves are touched --
>> I'm asking basic questions.
>
> See, that's your mistake.  The first steps towards feeling hostility on
> developer lists is to tell people that they are doing it all wrong but
> they are lucky you came around to tell them.  There are a lot of
> variations on the theme, of course.  But if you feel that a technical
> mailing list as such rather than, say, an isolated person having a bad
> day, act hostile, chances are that you score in that area.
>
>> The only reason I chimed in is because I'm one of those who would love
>> to contribute more substantially, but needs guidance. For example,
>> I've got the basics of an epub-editing mode in place. I'd like it to
>> be a solid library, and would likely need assistance to get it there.
>
> Can you figure out what is missing and phrase it into questions?  While
> there is the phenomenon that if you are asking 10 people, you'll get 20
> answers, I think that for basic problems the Emacs list will not split
> into so many different factions of "do it my way" that you'll get much
> more confusing answers from the group of people reading this list than
> you would get from a single tutor.

Yeah, I'm not sure anything new has come out of the "mentoring"
discussion besides the possibility of using a tag in subject line. There
are obviously many people prepared to help mid-level programmers, and
that's probably good enough.

Re: Metaproblem, part 3

[João Távora]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Yeah, I'm not sure anything new has come out of the "mentoring"
> discussion besides the possibility of using a tag in subject line. There
> are obviously many people prepared to help mid-level programmers, and
> that's probably good enough.

I do hope a little more comes out of it, that is the idea of a
short-term, one-on-one dialog, desirably backed by good docs/references,
so that even high-level programmers from other programming cultures
don't find a barrier in navigating Emacs's procedures.

Also, "hostility" is a subjective perception (and discussing it as a
universal is uninteresting), so the very word in the tag should
might/should modulate that perception in the right direction.

João

Re: Metaproblem, part 3

[Stephen J. Turnbull]

Eric Abrahamsen writes:

 > The only reason I chimed in

I need to get my finger off the "F" key.  I should have replied to
somebody else, as you definitely did not claim hostility on anybody's
part.  My apologies.

 > is because I'm one of those who would love to contribute more
 > substantially, but needs guidance. For example, I've got the basics
 > of an epub-editing mode in place. I'd like it to be a solid
 > library, and would likely need assistance to get it there.

Sure, and you'll find plenty of willing assistance once you figure out
how to ask for it.  Or you could just submit your code. :-) The people
you see posting here day-in-and-day-out will help you and *not* drop
the ball when they get bored.  Some more than others, of course, and
more at some times than others.

 > What's in it for the mentors and core developers is that, a few years
 > from now, I'd like to be making larger contributions to the Emacs core.
 > Mentoring would help me get there.

Sure.  My experience is that that works best with somebody who is, as
you are, already somewhat committed to the project.  But as a couple
people pointed out, mentoring anybody who comes in is not a profitable
strategy for adding core contributors (my definition is pretty broad,
that's anybody with some track record, who hangs out on project
channels, and who proposes to make "larger" contributions (plural) in
the future -- so the contributor you hope to be would be a core
contributor in my book).  That doesn't mean nobody will mentor you,
just that they'll do it at first for other reasons (not to forget that
it's a good way to sound out the actual intentions of the prospective
contributor).

Steve

Re: Metaproblem, part 3

[Eric Abrahamsen]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Eric Abrahamsen writes:
>
>  > The only reason I chimed in
>
> I need to get my finger off the "F" key.  I should have replied to
> somebody else, as you definitely did not claim hostility on anybody's
> part.  My apologies.

No worries!

>  > is because I'm one of those who would love to contribute more
>  > substantially, but needs guidance. For example, I've got the basics
>  > of an epub-editing mode in place. I'd like it to be a solid
>  > library, and would likely need assistance to get it there.
>
> Sure, and you'll find plenty of willing assistance once you figure out
> how to ask for it.  Or you could just submit your code. :-) The people
> you see posting here day-in-and-day-out will help you and *not* drop
> the ball when they get bored.  Some more than others, of course, and
> more at some times than others.
>
>  > What's in it for the mentors and core developers is that, a few years
>  > from now, I'd like to be making larger contributions to the Emacs core.
>  > Mentoring would help me get there.
>
> Sure.  My experience is that that works best with somebody who is, as
> you are, already somewhat committed to the project.  But as a couple
> people pointed out, mentoring anybody who comes in is not a profitable
> strategy for adding core contributors

I definitely agree with this part.

Re: Metaproblem, part 3

[David Kastrup]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Eric Abrahamsen writes:
>
>  > It would be nice to explicitly let posters know that they can ask
>  > someone for help with implementing a feature/squashing a
>  > bug. There's lots of helpful advice here and on emacs.help, but
>  > that's not quite the same as knowing that someone has committed (to
>  > some extent) to assisting you.
>
> I see worries about "hostile" environment, and suggestions for making
> things more welcoming to new contributors.  I have to ask, what do all
> you folks who are suggesting Emacs change its procedures think is in
> it for the mentors and core developers?

Profiting increasingly from work done by others.  That's actually a bit
more of expected payback than for the usual "you developers should jump
for joy when I have a good idea for your project that just needs some
working out by code runts" offering to free projects where the resulting
mailing list threads tend to get even more level-headed developers
marked for hostility.

The previous active maintainer of LilyPond, Graham Percival, chose to
try the effectiveness of mentoring, investing a large amount of work and
effort in individual mentoring of several would-be contributors.

The outcome overall was characterized as a huge disappointment by him,
with less work being done in the time the mentored persons stayed active
than he could have done himself in the time the tutoring took.

I have seen similar results for hiring outside people for doing free
software work: the return of investment tends to be hugely
disappointing.

The main reason for that is that the people commonly working on Free
Software projects tend to be self-motivated and skilled, and their skill
level leads to a reasonable return of satisfaction from their work.

So to get more people on board, it does not seem effective helping
single persons across some barriers of entry that are actually of the
kind that will stick around and that will continue to affect the balance
of freely contributed work and the satisfaction derived from a job well
done.  Instead you have to work on lowering the barriers of entry
altogether.  For better or worse, work will only get done by people
developing a vested interest and some loyalty to a project and its goals
and community.

And it is also useful to try breaking down the barriers between users,
power users, and developers as their numbers tend to be vastly different
and so even small changes can make quite a difference.

A system has to become usable and workable without too many of the
"please look aside while I fix this using some magic incantations that
you'll never understand" moments for users asking for assistance with
the problems encountered in daily work.

Texinfo is not really a relevant hurdle for getting Emacs documentation
written.  Elisp is.  Arguably things like lexical bindings have taken
far too long to arrive (and they still aren't in XEmacs if I remember
correctly) and there is not much in direction of making the language
more placatable.  Common Lisp compatibility might be one idea for
inheriting other people's work on making Lisp a general-purpose
commodity but, uh, Common Lisp has not exactly focused on being a
concise expressive language easily embraced by its users.

At any rate, I am suspicious of any promise of free software prosperity
to come from the hands of preachers rather than workers.  The danger
that one is left with less than what one started with when the
motivational Ponzi scheme of rewiring infrastructure to the newest fad
breaks down is real.

-- 
David Kastrup

Re: Metaproblem, part 3

[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 outcome overall was characterized as a huge disappointment by him,
  > with less work being done in the time the mentored persons stayed active
  > than he could have done himself in the time the tutoring took.

  > I have seen similar results for hiring outside people for doing free
  > software work: the return of investment tends to be hugely
  > disappointing.

I have also found that trying to actively help people learn how to
contribute, if they don't basically understand how to do so, consumes
more time than the contributions were worth.

If they do basically understand, and just need to know a few details,
then it's useful to show them.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: Metaproblem, part 3

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: joaotavora@gmail.com (João Távora)
>> Date: Thu, 04 Dec 2014 14:32:23 +0000
>> Cc: esr@thyrsus.com, emacs-devel@gnu.org
>> 
>> phillip.lord@newcastle.ac.uk (Phillip Lord) writes:
>> 
>> > Cheesy as it sounds, perhaps, what is needed is "mentors". So, someone
>> > wants to fix something or change something about Emacs, they get a short
>> > term mentor to help them through the process (both at a code level, and
>> > at a rules of community level). So, the first piece of advice in
>> > contribute wouldn't be "do this, do that", it would be "think of a
>> > problem, ask for a mentor".
>> 
>> +1 to this. In every software project I've worked on, some form of
>> mentorship has proven essential in every first-time
>> contribution. Including projects that I started, and including Emacs
>> (thanks Stefan!).
>
> I also think that we have mentoring here, so I don't understand what
> exactly is this gripe about.  People ask questions, both here and on
> bug-gnu-emacs, and get helpful answers and guidance even when the
> questions are only tangentially related to Emacs (or even not at
> all).  What exactly is missing?

I've gone back and read what I wrote. I can't see where it is a gripe.
It seems to me to be a positive suggestion. I understand that you do not
see the problem, but then you've been committing to Emacs for ages, so
it's clear that it's not a problem you have.

Phil

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Cc: João Távora <joaotavora@gmail.com>,
>   <esr@thyrsus.com>,  <emacs-devel@gnu.org>
> Date: Fri, 05 Dec 2014 10:56:17 +0000
> 
> > I also think that we have mentoring here, so I don't understand what
> > exactly is this gripe about.  People ask questions, both here and on
> > bug-gnu-emacs, and get helpful answers and guidance even when the
> > questions are only tangentially related to Emacs (or even not at
> > all).  What exactly is missing?
> 
> I've gone back and read what I wrote. I can't see where it is a gripe.

I apologize for using the word "gripe".  Let me rephrase: what is
missing in the current practices on emacs-devel to make them eligible
to be called "mentoring", in your opinion?

> It seems to me to be a positive suggestion.

I didn't perceive it as negative.  I just didn't understand what was
being suggested in practical terms.  Please elaborate.

Re: Metaproblem, part 3

[Phillip Lord]

Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> I've gone back and read what I wrote. I can't see where it is a gripe.
>
> I apologize for using the word "gripe".  Let me rephrase: what is
> missing in the current practices on emacs-devel to make them eligible
> to be called "mentoring", in your opinion?


Oh, well, the idea is that when someone wants to do something they get a
person to talk to, to help them through, away from the main line traffic
of emacs-devel.

What is missing on the current emacs-devel? It's not that anything in
missing, it's more the opposite. Emacs-devel is a high-traffic, complex
mailing list with lots of discussion going on. The discussion can get
heated also, but even when it's not it's somewhat intimidating; partly
this is because of the high level of technical competance of many of the
developers here. Obviously, having skilled developers is an asset to
Emacs, but it can have some occasional consequences.

Now, emacs-devel is not the worse I have seen. Years ago, I submitted a
potential patch once to the cygwin mailing list. I would have been quite
understanding of a "no, it does fit without objectives because of a, b
and c". What I got was "no, and you would have known that it was going
to be no, if you knew anything about it, which you would have, if you'd
read the mailing list for several months before posting".

I have commit rights to ELPA (and I guess therefore Emacs core). I've
used the former, but never the latter, because I am worried about
screwing things up. I never worried about this with cider, or clojure
mode because I committed to my own repo and send a pull request (several
of which were refused, with reasonable explanations as to why).


>> It seems to me to be a positive suggestion.
>
> I didn't perceive it as negative.  I just didn't understand what was
> being suggested in practical terms.  Please elaborate.

I hope that I have.

Probably I talk to much, and don't code enough, so after this I will
take Stefan's advice and do some more of the latter.

Phil

Re: Metaproblem, part 3

[Eli Zaretskii]

> From: phillip.lord@newcastle.ac.uk (Phillip Lord)
> Cc: <joaotavora@gmail.com>,  <esr@thyrsus.com>,  <emacs-devel@gnu.org>
> Date: Fri, 05 Dec 2014 12:09:09 +0000
> 
> Oh, well, the idea is that when someone wants to do something they get a
> person to talk to, to help them through, away from the main line traffic
> of emacs-devel.

If people would feel better getting advice in private email, they can
ask for it, and I don't see any problem with that.  I know I had a few
requests like that in the past.

> I have commit rights to ELPA (and I guess therefore Emacs core). I've
> used the former, but never the latter, because I am worried about
> screwing things up. I never worried about this with cider, or clojure
> mode because I committed to my own repo and send a pull request (several
> of which were refused, with reasonable explanations as to why).

You can always post the patch to bug-gnu-emacs@gnu.org, if you aren't
sure it's good to go, and ask for a review.

Thanks.

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[David Engster]

Stefan Monnier writes:
>> +before descending into it, and if nil is returned at that point
>> +the descent will be prevented.  Directory entries are sorted with
>> +string-lessp"
>              ^^^
> Don't forget to punctuate your docstrings.

And string-lessp should be quoted, but it doesn't matter since AFAICS
that sentence isn't true anyway.

>> +  (cond ((file-directory-p dir)
>> +	 (or (char-equal ?/ (aref dir (1- (length dir))))
>> +	     (setq dir (file-name-as-directory dir)))
>> +	 (let ((lst (directory-files dir nil nil t))
>
> Experience taught me that file-name-all-completions followed by testing
> the presence of a trailing "/" is *much* faster because calling
> file-directory-p on each entry ends up costly.
>
> I got this trick from Eshell's code for ** globbing, where the speed
> difference was a factor 10 when I tested it.

Apart from that, I find this function confusing. Why not simply call
ACTION with the full filename instead of splitting in into DIR and the
filename sans the directory part (where the latter might actually be a
subdirectory)?

-David

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eric S. Raymond]

David Engster <deng@randomsample.de>:
> Stefan Monnier writes:
> >> +before descending into it, and if nil is returned at that point
> >> +the descent will be prevented.  Directory entries are sorted with
> >> +string-lessp"
> >              ^^^
> > Don't forget to punctuate your docstrings.
> 
> And string-lessp should be quoted, but it doesn't matter since AFAICS
> that sentence isn't true anyway.

Huh?  They're from directory-files, which according to its documentation
sorts the names with string-lessp.
 
> Apart from that, I find this function confusing. Why not simply call
> ACTION with the full filename instead of splitting in into DIR and the
> filename sans the directory part (where the latter might actually be a
> subdirectory)?

Because that's how the well-tested code I found in the EmacsWiki 
cookbook section worked.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[David Engster]

Eric S. Raymond writes:
> David Engster <deng@randomsample.de>:
>> Stefan Monnier writes:
>> >> +before descending into it, and if nil is returned at that point
>> >> +the descent will be prevented.  Directory entries are sorted with
>> >> +string-lessp"
>> >              ^^^
>> > Don't forget to punctuate your docstrings.
>> 
>> And string-lessp should be quoted, but it doesn't matter since AFAICS
>> that sentence isn't true anyway.
>
> Huh?  They're from directory-files, which according to its documentation
> sorts the names with string-lessp.

Yes, unless you set NOSORT.

>> Apart from that, I find this function confusing. Why not simply call
>> ACTION with the full filename instead of splitting in into DIR and the
>> filename sans the directory part (where the latter might actually be a
>> subdirectory)?
>
> Because that's how the well-tested code I found in the EmacsWiki 
> cookbook section worked.

Oh, I didn't know it was from the EmacsWiki. Please forget I said
something.

-David

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eric S. Raymond]

David Engster <deng@randomsample.de>:
> > Because that's how the well-tested code I found in the EmacsWiki 
> > cookbook section worked.
> 
> Oh, I didn't know it was from the EmacsWiki. Please forget I said
> something.

No problem.  BTW, in case it's not obvious, the reason I added this was for
VC mode.  There is presently a rather ad-hoc implementation in vc-file-tree-walk
and I had been about to add another in order to inmplement vc-dir-status-files
for RCS and SCCS more cleanly.  Now I can unify those two with much simpler
code.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[David Engster]

Eric S. Raymond writes:
> David Engster <deng@randomsample.de>:
>> > Because that's how the well-tested code I found in the EmacsWiki 
>> > cookbook section worked.
>> 
>> Oh, I didn't know it was from the EmacsWiki. Please forget I said
>> something.
>
> No problem.  BTW, in case it's not obvious, the reason I added this was for
> VC mode.  There is presently a rather ad-hoc implementation in vc-file-tree-walk

Yes, that ad-hoc implementation is actually rather sound compared to
that code you got from the Wiki. BTW, when you write "found in the
Emacswiki", you surely mean you put it there in the first place, right?
Because otherwise you couldn't really add it to Emacs under your name.

-David

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eric S. Raymond]

David Engster <deng@randomsample.de>:
> > No problem.  BTW, in case it's not obvious, the reason I added this was for
> > VC mode.  There is presently a rather ad-hoc implementation in vc-file-tree-walk
> 
> Yes, that ad-hoc implementation is actually rather sound compared to
> that code you got from the Wiki.

That's nice.  I wrote the one in VC mode.

>                                    BTW, when you write "found in the
> Emacswiki", you surely mean you put it there in the first place, right?
> Because otherwise you couldn't really add it to Emacs under your name.

I thought the point of the cookbook was to make code free for re-use.
I have no idea who wrote that one, and don't see how it matters.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[David Engster]

Eric S. Raymond writes:
> David Engster <deng@randomsample.de>:
>>                                    BTW, when you write "found in the
>> Emacswiki", you surely mean you put it there in the first place, right?
>> Because otherwise you couldn't really add it to Emacs under your name.
>
> I thought the point of the cookbook was to make code free for re-use.
> I have no idea who wrote that one, and don't see how it matters.

I thought it matters because of copyright. But if no one else cares, I
certainly won't make a fuzz about it. It will make my life easier as
well: if a contributor does not want to go through this tedious paper
signing process, he can simply put in on a wiki page, and I can then
take it from there.

-David

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eli Zaretskii]

> From: David Engster <deng@randomsample.de>
> Date: Thu, 04 Dec 2014 21:28:58 +0100
> Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> 
> > I thought the point of the cookbook was to make code free for re-use.
> > I have no idea who wrote that one, and don't see how it matters.
> 
> I thought it matters because of copyright.

Of course, it does.

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Stefan Monnier]

> I thought it matters because of copyright.

Indeed, it does matter.  We can't take such random code.


        Stefan

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Glenn Morris]

Stefan Monnier wrote:

>> I thought it matters because of copyright.
>
> Indeed, it does matter.  We can't take such random code.

For the record, that is the first point in "summary for the impatient"
in admin/notes/copyright; and adding changes under the name of the true
author is also the first point in admin/notes/repo. (Even if copyright
assignment did not require it, surely it's common courtesy.)

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Stefan Monnier]

>     Added file-tree-walk to files.el.

How many freaking times will i have to tell you include
ChangeLog-formatted entries in the commit messages?


        Stefan

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Thien-Thi Nguyen]

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

() Stefan Monnier <monnier@iro.umontreal.ca>
() Wed, 03 Dec 2014 10:34:14 -0500

   How many freaking times will i have to tell you include
   ChangeLog-formatted entries in the commit messages?

To reduce stress, you should draw a line in the sand:
- write it down;
- adopt a conformance-gate policy (and write THAT down);
- enforce it dispassionately.

By "write it down" i mean add it to HACKING or similar.
E.g., that's what i do for GNU Serveez:

 http://git.sv.gnu.org/cgit/serveez.git/tree/HACKING?h=p#n262

Alternatively, big projects (e.g., Linux) have a hierarchical
"pull priv" structures.  People push to public, but ephemeral,
branches and someone higher (in authority) only merges into
the "mainline" (via pulls) when satisfied that the candidate
branch has the right characteristics (form and content).

Otherwise, you will have to continue to play babysitter, and
(i think my fellow babysitters will concur) that's not so much
fun after the Nth "accident"...

In sum: Tough Love -- Just Do It -- Invest Wisely Soon.  :-D

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

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

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnu.org>
> Date: Wed, 03 Dec 2014 17:41:01 +0100
> 
> Otherwise, you will have to continue to play babysitter, and
> (i think my fellow babysitters will concur) that's not so much
> fun after the Nth "accident"...

There's an easier way: after Nth accident, revoke the write access to
the repo.

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Tom]

Eli Zaretskii <eliz <at> gnu.org> writes:

> > 
> > Otherwise, you will have to continue to play babysitter, and
> > (i think my fellow babysitters will concur) that's not so much
> > fun after the Nth "accident"...
> 
> There's an easier way: after Nth accident, revoke the write access to
> the repo.
> 

There is a better way. Git like other VC tools has precommit hooks.

Just add a script which checks the commit message and if there
is no proper changeLog-formatted entry in the commit message then
it rejects the commit.

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Paul Eggert]

On 12/03/2014 10:36 AM, Tom wrote:
> Just add a script which checks the commit message and if there
> is no proper changeLog-formatted entry in the commit message then
> it rejects the commit.
>

We already have such scripts in build-aux/git-hooks/*, which I wrote 
recently and which are installed in .git/hooks when you run autogen.sh.  
I made them reasonably permissive, since I figured that people would 
have enough trouble with the bzr-to-git transition that they wouldn't 
appreciate nagging about ChangeLog format too.  Also, the hooks are 
optional, in the sense that not everybody runs autogen.sh, or it may be 
a while before they run autogen.sh, or perhaps they commit in some way 
that bypasses the hooks.  At some point I suppose we could tighten up 
the hooks and make them less easy to bypass..

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Tom]

Paul Eggert <eggert <at> cs.ucla.edu> writes:
> 
> Also, the hooks are 
> optional, in the sense that not everybody runs autogen.sh, or it may be 
> a while before they run autogen.sh, or perhaps they commit in some way 
> that bypasses the hooks.  

Git has client and server side hooks. This should be a server side
hook, so it can't be bypassed:


In addition to the client-side hooks, you can use a couple of important
server-side hooks as a system administrator to enforce nearly any kind of
policy for your project. These scripts run before and after pushes to the
server. The pre hooks can exit non-zero at any time to reject the push as
well as print an error message back to the client; you can set up a push
policy that’s as complex as you wish.

http://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Lars Magne Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Thien-Thi Nguyen <ttn@gnu.org>
>> Date: Wed, 03 Dec 2014 17:41:01 +0100
>> 
>> Otherwise, you will have to continue to play babysitter, and
>> (i think my fellow babysitters will concur) that's not so much
>> fun after the Nth "accident"...
>
> There's an easier way: after Nth accident, revoke the write access to
> the repo.

The current thing going on here is kinda unusual, though.  Perhaps Eric
has lost email access without knowing?  Someone could send him an SMS or
something...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eric S. Raymond]

Lars Magne Ingebrigtsen <larsi@gnus.org>:
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Thien-Thi Nguyen <ttn@gnu.org>
> >> Date: Wed, 03 Dec 2014 17:41:01 +0100
> >> 
> >> Otherwise, you will have to continue to play babysitter, and
> >> (i think my fellow babysitters will concur) that's not so much
> >> fun after the Nth "accident"...
> >
> > There's an easier way: after Nth accident, revoke the write access to
> > the repo.
> 
> The current thing going on here is kinda unusual, though.  Perhaps Eric
> has lost email access without knowing?  Someone could send him an SMS or
> something...

No, I was asleep while this thread was going on.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Thien-Thi Nguyen]

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

() Eli Zaretskii <eliz@gnu.org>
() Wed, 03 Dec 2014 20:08:13 +0200

   There's an easier way: after Nth accident,
   revoke the write access to the repo.

Yes, that's the "enforce" part of "enforce it".
It's the "it" part that requires timely finessing.

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

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

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eric S. Raymond]

Stefan Monnier <monnier@iro.umontreal.ca>:
> How many freaking times will i have to tell you include
> ChangeLog-formatted entries in the commit messages?

I've been doing that.  You want it even when the ChangeLog part is a trivial
repetition of the summary line?
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Paul Eggert]

On 12/03/2014 11:27 AM, Eric S. Raymond wrote:
> You want it even when the ChangeLog part is a trivial
> repetition of the summary line?

It's not needed for one-liners.  For commit 
e820f16c06a5a6be4bc87910b349c7c3c6eca0f4, for example, your ChangeLog 
entry was "* files.el (file-tree-walk): Lisp translation of ANSI 
ftw(3).", and that one-liner should have been the git commit message, too.

For longer messages, please use the same text for both the ChangeLog 
file as for the commit message, except omit the 2nd-blank-line in the 
former and omit the leading tabs in the latter.  For commit 
b1a765b3a8586cd53c21579982c8fbc0ce534336, in contrast, it would have 
been better to use the following text (removing indentation) as the 
commit message:

     In vc, abolish the dir-status method.

     *  vc.el, all backends: API simplification: Abolish dir-status.
     It's replaced by dir-status-files.

and to use the same text (with indentation, but without the blank line) 
as the ChangeLog entry.

It is a pain to have to have essentially two copies of the same text, 
one in the ChangeLog file and the other in the commit message, but we 
haven't yet had strong consensus on fixing this.

Commit comment rules - and a metaproblem

[Eric S. Raymond]

Paul Eggert <eggert@cs.ucla.edu>:
> On 12/03/2014 11:27 AM, Eric S. Raymond wrote:
> >You want it even when the ChangeLog part is a trivial
> >repetition of the summary line?
> 
> It's not needed for one-liners.  For commit
> e820f16c06a5a6be4bc87910b349c7c3c6eca0f4, for example, your
> ChangeLog entry was "* files.el (file-tree-walk): Lisp translation
> of ANSI ftw(3).", and that one-liner should have been the git commit
> message, too.
> 
> For longer messages, please use the same text for both the ChangeLog
> file as for the commit message, except omit the 2nd-blank-line in
> the former and omit the leading tabs in the latter.  For commit
> b1a765b3a8586cd53c21579982c8fbc0ce534336, in contrast, it would have
> been better to use the following text (removing indentation) as the
> commit message:
> 
>     In vc, abolish the dir-status method.
> 
>     *  vc.el, all backends: API simplification: Abolish dir-status.
>     It's replaced by dir-status-files.
> 
> and to use the same text (with indentation, but without the blank
> line) as the ChangeLog entry.
> 
> It is a pain to have to have essentially two copies of the same
> text, one in the ChangeLog file and the other in the commit message,
> but we haven't yet had strong consensus on fixing this.

A larger problem is that these rules are both fussy and poorly documented -
in fact I don't know that they're documented at all.

And then there was talk of revoking commit access for violation of fussy
and poorly documented rules.

Emacs has very few contributors for its size.  It desperately needs new
blood, but has chronic trouble attracting any.

Connect the dots.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: [Emacs-diffs] master e820f16: Added file-tree-walk to files.el.

[Eli Zaretskii]

> Date: Wed, 03 Dec 2014 11:41:40 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: emacs-devel@gnu.org
> 
> On 12/03/2014 11:27 AM, Eric S. Raymond wrote:
> > You want it even when the ChangeLog part is a trivial
> > repetition of the summary line?
> 
> It's not needed for one-liners.

I agree.

> For commit 
> e820f16c06a5a6be4bc87910b349c7c3c6eca0f4, for example, your ChangeLog 
> entry was "* files.el (file-tree-walk): Lisp translation of ANSI 
> ftw(3).", and that one-liner should have been the git commit message, too.

Yes, but please lose the "*" part, it just wastes precious real estate.

>      In vc, abolish the dir-status method.
> 
>      *  vc.el, all backends: API simplification: Abolish dir-status.
>      It's replaced by dir-status-files.

Likewise here: no need to keep the asterisks.

More metaproblem

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> > On 12/03/2014 11:27 AM, Eric S. Raymond wrote:
> > > You want it even when the ChangeLog part is a trivial
> > > repetition of the summary line?
> > 
> > It's not needed for one-liners.
> 
> I agree.
> 
> > For commit 
> > e820f16c06a5a6be4bc87910b349c7c3c6eca0f4, for example, your ChangeLog 
> > entry was "* files.el (file-tree-walk): Lisp translation of ANSI 
> > ftw(3).", and that one-liner should have been the git commit message, too.
> 
> Yes, but please lose the "*" part, it just wastes precious real estate.
> 
> >      In vc, abolish the dir-status method.
> > 
> >      *  vc.el, all backends: API simplification: Abolish dir-status.
> >      It's replaced by dir-status-files.
> 
> Likewise here: no need to keep the asterisks.

I realize you both mean well, but have you actually thought about the
effect of adding more edge cases to commenting rules that are already
rather fussy?  (And undocumented.)

The overhead from all these picky requirements adds to big ones like
"you must execute a copyright assignment" in ways I don't think people
here understand. What looks reasonable and easy to you, from long
practice, is a wilderness of brambles to outsiders.

Once I've finished cleaning up and extending VC mode I'm going to
clean out the dusty attic in /etc (RMS and I discussed this and
basically agreed on a plan about 11 month ago).  If you don't see how
that's relevant, stop and think until you get it.

For Emacs to attract new developers, its code and the culture need to
be discoverable.  As part of this, practice rules need to be *clear*,
*documented*, and *minimal*.  Right now they fail all three tests.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Karl Fogel]

"Eric S. Raymond" <esr@thyrsus.com> writes:
>For Emacs to attract new developers, its code and the culture need to
>be discoverable.  As part of this, practice rules need to be *clear*,
>*documented*, and *minimal*.  Right now they fail all three tests.

+1 all over that.

For example, as far as I can see -- and I've looked, though maybe in the
wrong places -- there's never been a permanent sign anywhere, like on a
web page, telling developers when they should commit to release branches
versus when they should commit to master (trunk).

Sometimes trunk is locked down and most commits are supposed to go to
the current emacs-NN branch.  Other times it's not locked down.  And
you're just supposed to know, somehow, I guess by saving random bits of
state gleaned from a rather high-traffic mailing list.

Emacs is not an easy project for newcomers or drive-by contributors.
(And somebody please stop me before I start ranting about debbugs as a
primary bug tracker even when email-enabled things like Redmine are
available, since it's been discussed elsewhere.  Apparently for the
Emacs project in 2014, "send email" is still considered an acceptable UI
gesture for manipulating a bug ticket.)

-K

Re: More metaproblem

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Paul Eggert <eggert@cs.ucla.edu>,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Wed, 03 Dec 2014 16:13:55 -0600
> 
> "Eric S. Raymond" <esr@thyrsus.com> writes:
> >For Emacs to attract new developers, its code and the culture need to
> >be discoverable.  As part of this, practice rules need to be *clear*,
> >*documented*, and *minimal*.  Right now they fail all three tests.
> 
> +1 all over that.
> 
> For example, as far as I can see -- and I've looked, though maybe in the
> wrong places -- there's never been a permanent sign anywhere, like on a
> web page, telling developers when they should commit to release branches
> versus when they should commit to master (trunk).

See admin/notes/repo and admin/notes/commits.  What else is missing?

> Sometimes trunk is locked down and most commits are supposed to go to
> the current emacs-NN branch.

Thats a thing of a distant past.  Trunk (a.k.a. "master") is nowadays
never locked, but there are (usually short) periods before a new
release branch is cut, when there's a "feature freeze", i.e. commits
that introduce new features should not be pushed to master.

> Other times it's not locked down.  And you're just supposed to know,
> somehow, I guess by saving random bits of state gleaned from a
> rather high-traffic mailing list.

You need to read this list, yes.  Emacs is not the only project that
uses this practice, though.  GDB is another one.  Publishing such
ephemeral information on the developer's list is an established
practice; posting that on Web pages is IMO worse, because this kind of
information quickly becomes obsolete, and Google searches will then
bring wrong info to people.

> Emacs is not an easy project for newcomers or drive-by contributors.

Which large and complex project _is_ easy for newcomers?

> (And somebody please stop me before I start ranting about debbugs as a
> primary bug tracker even when email-enabled things like Redmine are
> available, since it's been discussed elsewhere.  Apparently for the
> Emacs project in 2014, "send email" is still considered an acceptable UI
> gesture for manipulating a bug ticket.)

I think if you dislike so much in Emacs development practices, you
should become much more active than you are, and then you maybe stand
a chance to start changing all that.

Re: More metaproblem

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Karl Fogel <kfogel@red-bean.com>
>> For example, as far as I can see -- and I've looked, though maybe in the
>> wrong places -- there's never been a permanent sign anywhere, like on a
>> web page, telling developers when they should commit to release branches
>> versus when they should commit to master (trunk).
>
> See admin/notes/repo and admin/notes/commits.  What else is missing?

That says that there is such a thing as a "freeze". It does not say "the
trunk is currently frozen".

>> Sometimes trunk is locked down and most commits are supposed to go to
>> the current emacs-NN branch.
>
> Thats a thing of a distant past.  Trunk (a.k.a. "master") is nowadays
> never locked, but there are (usually short) periods before a new
> release branch is cut, when there's a "feature freeze", i.e. commits
> that introduce new features should not be pushed to master.

That's not what admin/notes/repo says:

    Sometime before the release of a new major version of Emacs
    a "feature freeze" is imposed on the trunk.  No new features may be
    added after this point.  This is usually some months before the release.

"some months" is not "short". (see below for suggested patch)

(there is also the issue that "trunk" is now spelled "master")

>> Other times it's not locked down.  And you're just supposed to know,
>> somehow, I guess by saving random bits of state gleaned from a
>> rather high-traffic mailing list.
>
> You need to read this list, yes.  Emacs is not the only project that
> uses this practice, though.  GDB is another one.  Publishing such
> ephemeral information on the developer's list is an established
> practice; posting that on Web pages is IMO worse, because this kind of
> information quickly becomes obsolete, and Google searches will then
> bring wrong info to people.

admin/notes/repo goes on:

    Consult emacs-devel to know exactly what kinds of changes are
    allowed on what branch at any time.

"consult" an email list can mean several things:

1) Search the archive to find the information

2) Post a question

3) Follow the list, and record the information privately

Strategy 1 is problematic; searching for "freeze" on
http://lists.gnu.org/archive/cgi-bin/namazu.cgi?idxname=emacs-devel
turns up a couple start dates, but no end date, in the first page of
hits. Searching for '+from:"stefan monnier" freeze' does not change the
results, which appears to be a bug in the search engine.

Strategy 2 is annoying to the list.

Strategy 3 is problematic due to the fairly high volume on emacs-devel.
That could be improved by establishing a second list for "important
announcments", or using a unique identifier string in the email subject.

>
>> Emacs is not an easy project for newcomers or drive-by contributors.
>
> Which large and complex project _is_ easy for newcomers?

Good point. But there are still those (like me) with some experience who
are considering contributing; the issues raised here are barriers to
them.


Possible patch to admin/notes/repo:

--- a/admin/notes/repo
+++ b/admin/notes/repo
@@ -23,18 +23,17 @@ before possibly being merged to the trunk.

 Development is discussed on the emacs-devel mailing list.

-Sometime before the release of a new major version of Emacs
-a "feature freeze" is imposed on the trunk.  No new features may be
-added after this point.  This is usually some months before the release.
-
-Shortly before the release, a release branch is created, and the
-trunk is then free for development.
+Sometime before the release of a new major version of Emacs a "feature
+freeze" is imposed on the trunk, to prepare for creating a release
+branch.  No new features may be added to the trunk after this point,
+until the release branch is created. This freeze is announced on the
+emacs-devel mailing list, and not anywhere else.

 For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for
 23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x.

-Consult emacs-devel for exactly what kinds of changes are allowed
-on what branch at any time.
+You must follow emacs-devel to know exactly what kinds of changes are
+allowed on what branch at any time. Announcements about the freeze
+(and other important events) will contain "ANNOUNCE" in the subject.

 ** elpa



--
-- Stephe

Re: More metaproblem

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Thu, 04 Dec 2014 02:38:52 -0600

Thanks for the feedback.  A few comments below.

> >> Sometimes trunk is locked down and most commits are supposed to go to
> >> the current emacs-NN branch.
> >
> > Thats a thing of a distant past.  Trunk (a.k.a. "master") is nowadays
> > never locked, but there are (usually short) periods before a new
> > release branch is cut, when there's a "feature freeze", i.e. commits
> > that introduce new features should not be pushed to master.
> 
> That's not what admin/notes/repo says:
> 
>     Sometime before the release of a new major version of Emacs
>     a "feature freeze" is imposed on the trunk.  No new features may be
>     added after this point.  This is usually some months before the release.
> 
> "some months" is not "short".

The text doesn't say anything about the duration of the freeze, only
about the timing of its beginning.

The tendency lately is to make the freeze "as short as possible".  But
making a decision that master is stable enough to cut a release branch
requires human judgment, and cannot be too fast with Emacs.  E.g.,
blatant bugs sometimes take more than a week to be reported after they
are committed.

> (see below for suggested patch)

I don't think it's accurate, but I'll let Stefan and Glenn comment.

> >> Emacs is not an easy project for newcomers or drive-by contributors.
> >
> > Which large and complex project _is_ easy for newcomers?
> 
> Good point. But there are still those (like me) with some experience who
> are considering contributing; the issues raised here are barriers to
> them.

I think we are all for that; the problem, as always, is how to do
that, not if we want doing it.

Re: More metaproblem

[David Kastrup]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> That's not what admin/notes/repo says:
>
>     Sometime before the release of a new major version of Emacs
>     a "feature freeze" is imposed on the trunk.  No new features may be
>     added after this point.  This is usually some months before the release.
>
> "some months" is not "short". (see below for suggested patch)

Shrug.  In project life cycles, it tends to be short.  When the move to
Git became an imminent topic, Eli complained about the performance of
git-blame like on src/xdisp.c.  I said that I probably could do
something about that in some reasonably short amount of time.  Took me
probably half a year to come through on that promise.  And
lo-and-behold, when we converted to Git, most stable (rather than
long-term) distributions of software containing Git had the fix in time
for Emacs' move.

I was pretty sure I had dropped the ball, but apparently there is not a
lot of gravity.

For quality-delayed releases rather than fixed schedule releases,
I don't think I've seen freezes that turned out shorter than a few
months at least.

-- 
David Kastrup

Re: More metaproblem

[Stefan Monnier]

>>> For example, as far as I can see -- and I've looked, though maybe in the
>>> wrong places -- there's never been a permanent sign anywhere, like on a
>>> web page, telling developers when they should commit to release branches
>>> versus when they should commit to master (trunk).

I'd be happy to put such info somewhere, but I'm not sure where that
should go.  I see two problems to solve:
- Make sure people don't commit to the wrong branch.
- Help people find out where to commit.
The two are closely related, yet different: many contributors end up
contributing to the wrong branch because they don't even know that
there's a decision to make about which branch to use.

Since most pople aren't going to check a docfile or webpage every time
they commit, just on the off-chance that the rules have changed, it's
important for these rules to be permanent, if we want them to work well.

So, I think we should say that we always have 2 branches:
- master, for the bleeding edge.
- stable, for bug fixes.

And to avoid errors, "master" should never be frozen (so far, this has
not been the case, although I have tried to shorten the freeze time over
the years).

> That's not what admin/notes/repo says:
>
>     Sometime before the release of a new major version of Emacs
>     a "feature freeze" is imposed on the trunk.  No new features may be
>     added after this point.  This is usually some months before the release.
>
> "some months" is not "short". (see below for suggested patch)

For the last few releases, the process has been:
- when we're ready to start the release: freeze the trunk.
- a month or so later: cut a release branch from the trunk, re-open the
  trunk to changes.
- keep on fixing bugs on the release branch, updating the doc, then make
  pretest releases, and finally after several more months: make a release.

The purpose of the "freeze the trunk" is to try and get people to focus
on fixing bugs for a while.  I'm not sure it's very effective, tho.

> (there is also the issue that "trunk" is now spelled "master")

Indeed.

> > >> Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
> > >> admin/notes only stuff that is minor/obscure etc.
[...]
> We can have a section there labeled "if you have write access to the
> repository".  I see nothing wrong with that, and no need to have yet
> another file with possibly contradictory instructions.

I don't have a strong opinion on any of this, but if we want this info
to be effective, we should make it as visible as possible, i.e. not in
admin/notes (which no newcomer would think of consulting) but in
./CONTRIBUTE (that's right: not in `etc' either but at the toplevel).

And it should be kept as short as possible (e.g. things like formatting
of references to particular revisions is the kind of nitpicking we
don't need in there).


        Stefan

Re: More metaproblem

[Stephen Leake]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>>> For example, as far as I can see -- and I've looked, though maybe in the
>>>> wrong places -- there's never been a permanent sign anywhere, like on a
>>>> web page, telling developers when they should commit to release branches
>>>> versus when they should commit to master (trunk).
>
> I'd be happy to put such info somewhere, but I'm not sure where that
> should go.  I see two problems to solve:
> - Make sure people don't commit to the wrong branch.
> - Help people find out where to commit.
> The two are closely related, yet different: many contributors end up
> contributing to the wrong branch because they don't even know that
> there's a decision to make about which branch to use.
>
> Since most pople aren't going to check a docfile or webpage every time
> they commit, just on the off-chance that the rules have changed, it's
> important for these rules to be permanent, if we want them to work
> well.

Good point.

> So, I think we should say that we always have 2 branches:
> - master, for the bleeding edge.
> - stable, for bug fixes.

+1

> For the last few releases, the process has been:
> - when we're ready to start the release: freeze the trunk.
> - a month or so later: cut a release branch from the trunk, re-open the
>   trunk to changes.
> - keep on fixing bugs on the release branch, updating the doc, then make
>   pretest releases, and finally after several more months: make a release.
>
> The purpose of the "freeze the trunk" is to try and get people to focus
> on fixing bugs for a while.  I'm not sure it's very effective, tho.

We could try to leave trunk open, but put in a commit preprocessor that
looks for "fixes bug [0-9]+". It could then either refuse the commit, or
issue a stern warning.

>> > >> Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
>> > >> admin/notes only stuff that is minor/obscure etc.
> [...]
>> We can have a section there labeled "if you have write access to the
>> repository".  I see nothing wrong with that, and no need to have yet
>> another file with possibly contradictory instructions.
>
> I don't have a strong opinion on any of this, but if we want this info
> to be effective, we should make it as visible as possible, i.e. not in
> admin/notes (which no newcomer would think of consulting) but in
> ./CONTRIBUTE (that's right: not in `etc' either but at the toplevel).

I'll take a stab at writing that. 

> And it should be kept as short as possible (e.g. things like formatting
> of references to particular revisions is the kind of nitpicking we
> don't need in there).

I'll refer to admin/notes/* for "more advanced developers".

-- 
-- Stephe

Re: More metaproblem

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 04 Dec 2014 10:35:24 -0500
> Cc: emacs-devel@gnu.org
> 
> And it should be kept as short as possible (e.g. things like formatting
> of references to particular revisions is the kind of nitpicking we
> don't need in there).

I think this requirement raises the bar impossibly high.  You cannot
have a useful set of instructions that leave those out.  E.g., this
whole discussion started because of such "nitpicking".

Neither do I see why would we need to restrict ourselves like that.  A
document with a clear structure and a list of topics at the beginning
can be longish and still useful.  OTOH, having instructions scattered
over several files makes discovery harder.

Re: More metaproblem

[Stefan Monnier]

> I think this requirement raises the bar impossibly high.  You cannot
> have a useful set of instructions that leave those out.  E.g., this
> whole discussion started because of such "nitpicking".

Actually no.  It started because of missing something important (for us
anyway) and which should be in ./CONTRIBUTE.

The formatting of references to revisions is a nitpick and should simply
not be mentioned anywhere.  We've survived quite happily for the last 30
years with "references to revisions" which are not machine-processable,
so if we leave people use the format they like, it's not going to be any
worse than what we've had so far.

> Neither do I see why would we need to restrict ourselves like that.  A
> document with a clear structure and a list of topics at the beginning
> can be longish and still useful.

People's attention span is much too limited for that.

> OTOH, having instructions scattered over several files makes
> discovery harder.

Agreed.


        Stefan

Re: More metaproblem

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stephen_leake@stephe-leake.org,  emacs-devel@gnu.org
> Date: Thu, 04 Dec 2014 15:43:47 -0500
> 
> The formatting of references to revisions is a nitpick and should simply
> not be mentioned anywhere.

You've elided your original text, to which I responded:

> And it should be kept as short as possible (e.g. things like formatting
> of references to particular revisions is the kind of nitpicking we
> don't need in there).

"Things LIKE formatting of references", IOW not _just_ those
references.

If you meant _only_ those references, we are in violent agreement.

But other small details like that do need to be mentioned, if we want
to standardize and codify the process, and have it documented.

> > Neither do I see why would we need to restrict ourselves like that.  A
> > document with a clear structure and a list of topics at the beginning
> > can be longish and still useful.
> 
> People's attention span is much too limited for that.

They don't have to read all of the stuff, only what they need at any
given moment.

Re: More metaproblem

[chad]

> On 04 Dec 2014, at 07:35, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>>>> For example, as far as I can see -- and I've looked, though maybe in the
>>>> wrong places -- there's never been a permanent sign anywhere, like on a
>>>> web page, telling developers when they should commit to release branches
>>>> versus when they should commit to master (trunk).
> 
> I'd be happy to put such info somewhere, but I'm not sure where that
> should go.  I see two problems to solve:

This might be too much of a shotgun to the problem, but what if we
added a file FEATURE-FREEZE to the master when the feature freeze
was on, along with the email to emacs-dev? It could contain the
explicit details like "Hey, please hold on to the feature for now,
and try to help us test/finish the release candidate instead.
Thanks!"

~Chad

Re: More metaproblem

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> "Eric S. Raymond" <esr@thyrsus.com> writes:
>> >For Emacs to attract new developers, its code and the culture need to
>> >be discoverable.  As part of this, practice rules need to be *clear*,
>> >*documented*, and *minimal*.  Right now they fail all three tests.
>>
> See admin/notes/repo and admin/notes/commits.  What else is missing?

That does not describe the changelog entry/commit message format. There
is admin/notes/changelog, which contains a reference to the Gnu coding
standards and some hints.

admin/notes/commits explictly says the commit message does _not_ need to
contain all the info the Changelog entry does; that is apparently
incorrect.

It also assumes CVS, while at the same time allowing for other systems;
confusing.

It would help if the emails that say "please follow the standard style"
would mention these documents, so people get used to refering to them.

Proposed patch for repo in another email; patches for commits,
changelogs:

diff --git a/admin/notes/changelogs b/admin/notes/changelogs
index e815806..503b73a 100644
--- a/admin/notes/changelogs
+++ b/admin/notes/changelogs
@@ -30,3 +30,13 @@ Preferred form for several entries with the same content:
    * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.

 (Rather than anything involving "ditto" and suchlike.)
+
+In ChangeLog files, it is best to use ways of identifying revisions
+that are not dependent on a particular version control system.  (At
+time of writing Emacs has just moved to its fourth VCS and another
+move in the future is not impossible.)  An excellent way to identify
+commits is by quoting their summary line.  Another is with an action
+stamp - an RFC3339 date followed by ! followed by the committer's
+email - for example, "2014-01-16T05:43:35Z!esr@thyrsus.com". Often,
+"my previous commit" will suffice.
+
diff --git a/admin/notes/commits b/admin/notes/commits
index f33c690..5371b2b 100644
--- a/admin/notes/commits
+++ b/admin/notes/commits
@@ -1,70 +1,27 @@
 HOW TO COMMIT CHANGES TO EMACS

-Most of these points are from:
-
-http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html
-From: 	 Miles Bader
-Subject: commit style redux
-Date: 	 Tue, 31 Mar 2009 12:21:20 +0900
-
 (0) Each commit should correspond to a single change (whether spread
     over multiple files or not).  Do not mix different changes in the
     same commit (eg adding a feature in one file, fixing a bug in
     another should be two commits, not one).

-(1) Commit all changed files at once with a single log message (which
-    in CVS will result in an identical log message for all committed
-    files), not one-by-one.  This is pretty easy using vc-dir now.
-
-(2) Make the log message describe the entire changeset, perhaps
-    including relevant changelog entries (I often don't bother with
-    the latter if it's a trivial sort of change).
-
-    Many modern source-control systems vaguely distinguish the first
-    line of the log message to use as a short summary for abbreviated
-    history listing (in arch this was explicitly called the summary,
-    but many other systems have a similar concept).  So it's nice if
-    you can format the log entry like:
-
-        SHORTISH ONE-LINE SUMMARY
-
-        MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR
-        CONSISTING OF) CHANGELOG ENTRIES
+(1) Commit all changed files at once with a single log message (the
+    default behavior in git).

-    [Even with CVS this style is useful, because web CVS browsing
-    interfaces often include the first N words of the log message of
-    the most recent commit as a short "most recent change"
-    description.]
-
-(3) Don't phrase log messages assuming the filename is known, because
-    in non-file-oriented systems (everything modern other than CVS),
-    the log listing tends to be treated as global information, and the
-    connection with specific files is less explicit.
-
-    For instance, currently I often see log messages like "Regenerate";
-    for modern source-control systems with a global log, it's better to
-    have something like "Regenerate configure".
-
-(4) (Added in 2014) In commit comments, and ChangeLog files, it is best
-    to use ways of identifying revisions that are not dependent on a
-    particular version control system.  (At time of writing Emacs is
-    about to move to its fourth VCS and another move in the future is
-    not impossible.)  An excellent way to identify commits is by
-    quoting their summary line.  Another is with an action stamp - an
-    RFC3339 date followed by ! followed by the committer's email - for
-    example, "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my
-    previous commit" will suffice.
-
-Followup discussion:
-http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html
-http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html
+(2) Make the log message describe the entire changeset. The log
+    message should be the same as the Changelog entry, without the
+    date line. You can write the Changelog first, then use C-c C-a
+    from the *VC-Log* buffer to copy it to the commit log message. See
+    the file 'changelog' for information on the Changelog entry
+    format.

+(3) If committing changes written by someone else, make the ChangeLog
+    entry in their name, not yours. git distinguishes between the
+    author and the committer; use the --author option on the commit
+    command to specify the actual author; the committer defaults to
+    you.

 PREVIOUS GUIDELINES FOR CVS

 For historical interest only, here is the old-style advice for CVS logs:
 http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html
-
-From: Eli Zaretskii
-Subject: Re: Log messages in CVS
-Date: Sat, 29 Dec 2007 16:06:29 +0200


--
-- Stephe

Re: More metaproblem

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Thu, 04 Dec 2014 03:08:14 -0600
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> "Eric S. Raymond" <esr@thyrsus.com> writes:
> >> >For Emacs to attract new developers, its code and the culture need to
> >> >be discoverable.  As part of this, practice rules need to be *clear*,
> >> >*documented*, and *minimal*.  Right now they fail all three tests.
> >>
> > See admin/notes/repo and admin/notes/commits.  What else is missing?
> 
> That does not describe the changelog entry/commit message format. There
> is admin/notes/changelog, which contains a reference to the Gnu coding
> standards and some hints.

Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
admin/notes only stuff that is minor/obscure etc.

Re: More metaproblem

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Date: Thu, 04 Dec 2014 03:08:14 -0600
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> "Eric S. Raymond" <esr@thyrsus.com> writes:
>> >> >For Emacs to attract new developers, its code and the culture need to
>> >> >be discoverable.  As part of this, practice rules need to be *clear*,
>> >> >*documented*, and *minimal*.  Right now they fail all three tests.
>> >>
>> > See admin/notes/repo and admin/notes/commits.  What else is missing?
>> 
>> That does not describe the changelog entry/commit message format. There
>> is admin/notes/changelog, which contains a reference to the Gnu coding
>> standards and some hints.
>
> Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
> admin/notes only stuff that is minor/obscure etc.

etc/CONTRIBUTE should contain everything necessary to create a patch
submission that can just be applied with "git am" without modification
(well, apart from another git commit --amend -s for adding a
"Signed-off-by" from the person picking up and pushing the patch).

While less polished submissions may be processed, that requires more of
a personal investment from "somebody" picking them up.  So it's a good
idea to have everything necessary in that file.

That does not mean that the file can't start with an encouragement to
submit less complete contributions if people get stuck getting the full
thing accomplished.

-- 
David Kastrup

Re: More metaproblem

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> > From: Stephen Leake <stephen_leake@stephe-leake.org>
> > Date: Thu, 04 Dec 2014 03:08:14 -0600
> > 
> > Eli Zaretskii <eliz@gnu.org> writes:
> > 
> > >> "Eric S. Raymond" <esr@thyrsus.com> writes:
> > >> >For Emacs to attract new developers, its code and the culture need to
> > >> >be discoverable.  As part of this, practice rules need to be *clear*,
> > >> >*documented*, and *minimal*.  Right now they fail all three tests.
> > >>
> > > See admin/notes/repo and admin/notes/commits.  What else is missing?
> > 
> > That does not describe the changelog entry/commit message format. There
> > is admin/notes/changelog, which contains a reference to the Gnu coding
> > standards and some hints.
> 
> Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
> admin/notes only stuff that is minor/obscure etc.

I agree, and was intending to suggest that myself.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Eli Zaretskii <eliz@gnu.org>:
>> > From: Stephen Leake <stephen_leake@stephe-leake.org>
>> > Date: Thu, 04 Dec 2014 03:08:14 -0600
>> > 
>> > Eli Zaretskii <eliz@gnu.org> writes:
>> > 
>> > >> "Eric S. Raymond" <esr@thyrsus.com> writes:
>> > >> >For Emacs to attract new developers, its code and the culture need to
>> > >> >be discoverable.  As part of this, practice rules need to be *clear*,
>> > >> >*documented*, and *minimal*.  Right now they fail all three tests.
>> > >>
>> > > See admin/notes/repo and admin/notes/commits.  What else is missing?
>> > 
>> > That does not describe the changelog entry/commit message format. There
>> > is admin/notes/changelog, which contains a reference to the Gnu coding
>> > standards and some hints.
>> 
>> Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
>> admin/notes only stuff that is minor/obscure etc.
>
> I agree, and was intending to suggest that myself.

admin/notes should only contain stuff relevant for people with push
access.  Preparing a patch does not entail that.

-- 
David Kastrup

Re: More metaproblem

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Thu, 04 Dec 2014 11:35:03 +0100
> 
> >> Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
> >> admin/notes only stuff that is minor/obscure etc.
> >
> > I agree, and was intending to suggest that myself.
> 
> admin/notes should only contain stuff relevant for people with push
> access.  Preparing a patch does not entail that.

We can have a section there labeled "if you have write access to the
repository".  I see nothing wrong with that, and no need to have yet
another file with possibly contradictory instructions.

Re: More metaproblem

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> > From: David Kastrup <dak@gnu.org>
> > Date: Thu, 04 Dec 2014 11:35:03 +0100
> > 
> > >> Maybe we should simply move all that into etc/CONTRIBUTE, and leave in
> > >> admin/notes only stuff that is minor/obscure etc.
> > >
> > > I agree, and was intending to suggest that myself.
> > 
> > admin/notes should only contain stuff relevant for people with push
> > access.  Preparing a patch does not entail that.
> 
> We can have a section there labeled "if you have write access to the
> repository".  I see nothing wrong with that, and no need to have yet
> another file with possibly contradictory instructions.

+1
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Stephen J. Turnbull]

Eric S. Raymond writes:

 > I agree, and was intending to suggest that myself.

I think we've had way too many suggestions and way too little actual
text.  It would be better if somebody would write a GEEP[1] containing
the full proposed CONTRIBUTE text.  I nominate Stephen Leake because
he's the one who's shown the most tendency to actually write text, but
if he's lucky somebody else will raise their hand.[2][3]

Footnotes: 
[1]  GNU Emacs Enhancement Proposal.

[2]  It would be a bad idea to counternominate me -- I'll just dump
the XEmacs DevGuide verbatim, explicit recruiting text and all. ;-)

[3]  Besides, the date would embarrass both me (for not updating) and
Emacs (since I would guess I first published it in '03 or so).

Re: More metaproblem

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,
>     Stephen Leake <stephen_leake@stephe-leake.org>,
>     emacs-devel@gnu.org
> Date: Fri, 05 Dec 2014 10:23:35 +0900
> 
> Eric S. Raymond writes:
> 
>  > I agree, and was intending to suggest that myself.
> 
> I think we've had way too many suggestions and way too little actual
> text.  It would be better if somebody would write a GEEP[1] containing
> the full proposed CONTRIBUTE text.

I was going to, but then Stephen Leake said he will, so I guessed
he'll beat me up to that.

Re: More metaproblem

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>> "Eric S. Raymond" <esr@thyrsus.com> writes:
>>> For Emacs to attract new developers, its code and the culture need to
>>> be discoverable.  As part of this, practice rules need to be *clear*,
>>> *documented*, and *minimal*.  Right now they fail all three tests.
>> 
>> +1 all over that.
>> 
>> For example, as far as I can see -- and I've looked, though maybe in the
>> wrong places -- there's never been a permanent sign anywhere, like on a
>> web page, telling developers when they should commit to release branches
>> versus when they should commit to master (trunk).
>
>See admin/notes/repo and admin/notes/commits.  What else is missing?

New developers are somehow supposed to know that those random files in
admin/notes/ are what they need to read?

What most projects do is have a development web page. linked to from
their main user-facing web page.  The development page organizes all
this stuff and provides links to source code repository, dev guidelines
& documentation, etc.

For Emacs, the main web page is http://www.gnu.org/software/emacs/.

It links to two possible candidates for the "developer page":

  https://savannah.gnu.org/projects/emacs
  https://savannah.gnu.org/bzr/?group=emacs

But neither of those automatically-generated pages provides what a real
development web page provides.  Instead they just tell you how to get
the development sources and where the mailing lists are.  They don't
tell you to look in admin/notes/ (for example).

Compare those with develompent pages for projects that are trying to
make it easy for new developers to come on board:

  http://subversion.apache.org/contributing.html
  http://www.libreoffice.org/community/developers/

(both of which are easy to find from their projects' respective main
home pages, by the way.)

I hope the contrast between those examples and the way Emacs currently
is is sufficiently clear as to not require much elucidation.

Else-thread you wrote this:

> > For Emacs to attract new developers, its code and the culture need to
> > be discoverable.  As part of this, practice rules need to be *clear*,
> > *documented*, and *minimal*.  Right now they fail all three tests.
> 
> Feel free to contribute the missing documentation, and thanks in
> advance.

It's not just a matter of contributing documentation.  We don't even
*have a place to put such documentation* right now.

Heck, for all I know there _is_ a "Contributing to Emacs" guide
somewhere on the Net at this moment.  Maybe more than one.  What would
be needed is for the Emacs project to make it official by moving it to
somewhere under an official-ish Emacs URL, linking to it from the
obvious places, and helping to maintain it.

(I'm not volunteering to take ownership of that task, though I'd
participate in maintaining such a guide.  I only have time to do
occasional patching, and to write emails like this one that try to point
out specifically the ways in which the project is currently
developer-hostile and stagnating.)

>> Emacs is not an easy project for newcomers or drive-by contributors.
>
>Which large and complex project _is_ easy for newcomers?

Mozilla Firefox or LibreOffice, to name two off the top of my head.
There are many more.

Like others here, I contribute to plenty of free software projects.  As
it happens, I also study the development procedures of many more --
doing so is, in fact, my full time job.  Emacs is one of the least
developer-friendly.  I have time to explain some of the ways in which it
is so, though not enough time to explain all the ways.

I think the fact that several people on this mailing list -- people who
also have lots of experience with other projects -- have repeatedly said
so, should also indicate that most likely there is a bigger problem here
than elsewhere.  And the fact that we don't see a comparable number of
similarly experienced people making this complaint in the forums of,
say, Mozilla Firefox or LibreOffice, is further evidence.  (Btw, yes I
have actually asked about this among contributors to those projects.
See also, e.g., https://wiki.mozilla.org/Good_first_bug.)

>> (And somebody please stop me before I start ranting about debbugs as a
>> primary bug tracker even when email-enabled things like Redmine are
>> available, since it's been discussed elsewhere.  Apparently for the
>> Emacs project in 2014, "send email" is still considered an acceptable UI
>> gesture for manipulating a bug ticket.)
>
>I think if you dislike so much in Emacs development practices, you
>should become much more active than you are, and then you maybe stand
>a chance to start changing all that.

It's precisely that I don't have time to be more active than I am, that
leads me to want the project's development procedures to be more
conducive to developers like me -- there are many of them out there.

Look, it might be reasonable to say "There's an inevitable tradeoff
between being easy for new developers and being efficient for expert,
long-time developers, and the Emacs project has chosen the latter side
of that tradeoff."  That's fine.

But to deny that the project is difficult for incoming developers?  That
seems to me empirically wrong; as a simple fact, the difficulty should
not be in doubt by this point.

Embrace the tradeoff, if you wish -- I think choosing that side of the
tradeoff is a mistake, but at least it's reasonable discussion to have.
But claiming there is no problem, that the phenomenon is not real, does
not seem plausible to me.  For a widely used *programmer's tool*, that
is self-documenting and has an extension language, Emacs has an
astonishingly low rate of lightweight contributed development.

Can you help make your hypothesis falsifiable?  (In the intellectually
rigorous sense, I mean, not the "make it false" sense.)  I might be able
to find some time to do that.  In other words, can you tell me what
measurable signs *you* would look for to determine if a free software
project were stagnating, and then we can look to see if Emacs is
exhibiting those signs?  (For example: rate at which developers slow
down or stop contributing; relatively greater slowdown in rate of
acquisition of new developers compared to other projects; shrinking
diversity in first responders to bug reports; etc, etc.)

Committers sorted by commit count since 1985, in case it's interesting
(obviously doesn't count patches and many other things, so this is only
semi-data, not data):

  20572 Richard M. Stallman 
  10107 Glenn Morris 
   7395 Stefan Monnier 
   7099 Eli Zaretskii 
   6637 Kenichi Handa 
   6011 Chong Yidong 
   4803 Gerd Moellmann 
   4416 Juanma Barranquero 
   3767 Karl Heuer 
   3374 Paul Eggert 
   3320 Dave Love 
   3025 Kim F. Storm 
   1860 Miles Bader 
   1781 Jim Blandy 
   1511 Jason Rumney 
   1474 Dan Nicolaescu 
   1472 Andreas Schwab 
   1458 Juri Linkov 
   1421 Nick Roberts 
   1397 Michael Albinus 
   1390 Jan Djärv 
   1284 Luc Teirlinck 
    940 Jay Belanger 
    907 YAMAMOTO Mitsuharu 
    826 Lars Magne Ingebrigtsen 
    749 Pavel Janík 
    697 Martin Rudalics 
    638 Dmitry Antipov 
    615 Carsten Dominik 
    596 Karoly Lorentey 
    584 Roland McGrath 
    583 Thien-Thi Nguyen 
    518 Katsumi Yamaoka 
    470 Eric S. Raymond 
    445 Alan Mackenzie 
    436 Andrew Innes 
    435 Francesco Potortì 
    427 Bill Wohler 
    420 Geoff Voelker 
    407 Lute Kamstra 
    399 André Spiegel 
    337 Leo Liu 
    320 Colin Walters 
    317 Sam Steingold 
    312 Romain Francoise 
    299 John Paul Wallington 
    279 Vinicius Jose Latorre 
    273 Fabián Ezequiel Gallina 
    266 Xue Fuqiao 
    259 Markus Rost 
    254 Ken Raeburn 
    242 Adrian Robert 
    235 Simon Marshall 
    211 Dmitry Gutov 
    206 Reiner Steib 
    205 Lars Ingebrigtsen 
    191 Michael Kifer 
    182 Tassilo Horn 
    180 John Wiegley 
    178 Daniel Colascione 
    174 Erik Naggum 
    167 Stephen Berman 
    159 Bastien Guerry 
    152 Kai Großjohann 
    149 Gnus developers 
    136 Daiki Ueno 
    129 Steven Tamm 
    127 Karl Berry 
    125 David Kastrup 
    122 Robert J. Chassell 
    119 Masatake YAMATO 
    114 Edward M. Reingold 
    113 Roland Winkler 
    112 Simon Josefsson 
    112 Julien Danjou 
    111 Daniel Pfeiffer 
    110 Karl Fogel 
    106 Ted Zlatanov 
    106 Noah Friedman 
    101 Lars Hansen 
     99 Andrew Choi 
     97 Jan D 
     94 Michael Olson 
     86 Stephen Eglen 
     84 Teodor Zlatanov 
     83 Ulf Jasper 
     82 Per Abrahamsen 
     80 Tom Tromey 
     80 David J. MacKenzie 
     77 ShengHuo ZHU 
     77 Mathias Dahl 
     75 Paul Reilly 
     69 Agustín Martín 
     68 Joseph Arceneaux 
     67 J.D. Smith 
     67 Boris Goldowsky 
     65 Michaël Cadilhac 
     64 Kevin Ryde 
     64 Ken Brown 
     61 David Engster 
     61 Brian Fox 
     60 Fred Pierresteguy 
     60 David Ponce 
     59 Martin Stjernholm 
     58 David Reitter 
     56 Eric M. Ludlam 
     56 Deniz Dogan 
     54 Werner LEMBERG 
     52 Richard Kenner 
     48 Ken Manheimer 
     47 Rüdiger Sonderfeld 
     47 Deepak Goel 
     43 Magnus Henoch 
     43 Andrew Cohen 
     41 Bozhidar Batsov 
     40 Mark A. Hershberger 
     39 Christoph Scholtes 
     38 Oliver Seidel 
     38 Jim Meyering 
     37 Johan Bockgård 
     35 Dmitry Dzhus 
     35 Dani Moncayo 
     33 Joakim Verona 
     32 Jonathan Yavner 
     30 Peter Breton 
     30 Alex Schroeder 
     29 Vincent Belaïche 
     28 Per Bothner 
     27 Jesper Harder 
     26 Reuben Thomas 
     26 Ramprasad B 
     26 Christopher Schmidt 
     24 Mike Williams 
     23 Thierry Volpiatto 
     22 Michal Nazarewicz 
     22 Jeffrey C Honig 
     22 Aidan Gauland 
     21 Doug Evans 
     20 root <root>
     20 Michael I. Bushnell 
     19 Michael Mauger 
     19 Drew Adams 
     18 Phillip Rulon 
     18 Károly Lőrentey 
     18 Jambunathan K 
     18 Ivan Shmakov 
     17 Stefan Merten 
     17 Joel N. Weber II 
     16 Ulrich Drepper 
     16 João Távora 
     16 Christopher Zaborsky 
     16 Ben Key 
     16 Barry O'Reilly 
     16 Alp Aker 
     15 Ulrich Mueller 
     15 Rajesh Vaidheeswarran 
     15 Kelvin White 
     15 Ivan Kanis 
     15 Brian Preble 
     14 Rudy Gevaert 
     14 Marcelo Toledo 
     14 Fabrice Popineau 
     13 Stephen Gildea 
     13 Ian Lance Taylor 
     13 Charles Hannum 
     13 Aaron S. Hawley 
     12 Wolfgang Jenkner 
     12 Wilson Snyder 
     12 Seiji Zenitani 
     12 Lawrence Mitchell 
     12 Ben Elliston 
     11 thierry volpiatto 
     11 Melissa Weisshaus 
     11 Daniel LaLiberte 
     11 Dan Davison 
     11 Adam Sjøgren 
     10 Tomohiro Matsuyama 
     10 Michael Meissner 
     10 Kenjiro NAKAYAMA 
     10 Jan Tatarik 
      9 Ulrich Müller 
      9 Stephen Leake 
      9 Sebastian Kremer 
      9 Nicolas Richard 
      9 Jürgen Hötzel 
      9 Jeff Law 
      9 Christian Ohler 
      9 Bob Rogers 
      9 Antoine Levitt 
      8 Jari Aalto 
      8 Helmut Eller 
      8 Brian Youmans 
      7 Vivek Dasmohapatra 
      7 Peter Galbraith 
      7 Paul D. Smith 
      7 Matthias Meulien 
      7 Matthias Dahl 
      7 Luke Lee 
      7 Dima Kogan 
      7 Claudio Bley 
      7 Alexandre Julliard 
      6 Štěpán Němec 
      6 Samuel Bronson 
      6 Oscar Fuentes 
      6 Nathan Trapuzzano 
      6 Mark Lillibridge 
      6 Johan Vromans 
      6 Jim Wilson 
      6 Jarek Czekalski 
      6 Ivan Andrus 
      6 Fabrice Niessen 
      6 Eric Hanchrow 
      6 Eric Ding 
      5 William M. Perry 
      5 Vitalie Spinu 
      5 Troels Nielsen 
      5 Simon South 
      5 Santiago Payà i Miralta 
      5 Mohsen BANAN 
      5 Michael Heerdegen 
      5 Mario Lang 
      5 Kelly Dean 
      5 Kan-Ru Chen 
      5 Jonas Bernoulli 
      5 John Gilmore 
      5 Jean-Philippe Gravel 
      5 Jaeyoun Chung 
      5 Grégoire Jadi 
      5 enami tsugutomo 
      5 Elias Pipping 
      5 Eduard Wiebe 
      5 Andreas Politz 
      5 Albert Krewinkel 
      4 William Xu 
      4 Tom Willemse 
      4 Thomas Bushnell, BSG 
      4 Teemu Likonen 
      4 Sven Joachim 
      4 Satyaki Das 
      4 Reto Zimmermann 
      4 Ralf Angeli 
      4 Phil Hagelberg 
      4 Morten Welinder 
      4 Matthew Swift 
      4 Mark D. Baushke 
      4 Kazuhiro Ito 
      4 Karel Klíc 
      4 Jérémy Compostella 
      4 Erich Stefan Boleyn 
      4 Dave Abrahams 
      4 Darren Hoo 
      4 Daniel Hackney 
      4 Alex Harsanyi 
      3 Ulf Jasper <>
      3 Toby Cubitt 
      3 Takafumi Arakaki 
      3 Simon Leinen 
      3 Sergio Durigan Junior 
      3 Ray Blaak 
      3 Ralph Schleicher 
      3 Per Starbäck 
      3 Óscar Fuentes 
      3 MON KEY 
      3 Mike Lamb 
      3 Michael Witten 
      3 Mark Oteiza 
      3 Ken Olum 
      3 Jorgen Schaefer 
      3 John Anthony 
      3 gnulists <gnulists>
      3 Feng Li 
      3 Erik Charlebois 
      3 Emilio C. Lopes 
      3 Eli Barzilay 
      3 David Lawrence 
      3 David Edmondson 
      3 Cameron Desautels 
      3 Arni Magnusson 
      3 Ari Roponen 
      3 Anders Lindgren 
      3 Alexander Klimov 
      3 Akinori MUSHA 
      2 Zachary Kanfer 
      2 Yoni Rabkin 
      2 Yann Hodique 
      2 William Stevenson 
      2 T.V. Raman 
      2 Torbjorn Granlund 
      2 Tetsurou Okazaki 
      2 Sylvain Chouleur 
      2 Steve Morningthunder 
      2 Steve Chamberlain 
      2 Stan Cox 
      2 Ron Schnell 
      2 Rob Browning 
      2 Richard Copley 
      2 Phil Sainty 
      2 Peter Oliver 
      2 Peter O'Gorman 
      2 Peter J. Weisberg 
      2 OKAZAKI Tetsurou 
      2 Nobuyoshi Nakada 
      2 Nix 
      2 Nicolas Avrutin 
      2 Nguyen Thai Ngoc Duy 
      2 Nathan Weizenbaum 
      2 Mike Stump 
      2 Michael R. Mauger 
      2 Matthew Leach 
      2 Martin Blais 
      2 Le Wang 
      2 Leonard Randall 
      2 Lennart Borgman 
      2 Lars Ljung 
      2 Kevin Rodgers 
      2 Kevin Gallagher 
      2 Kaushik Srenevasan 
      2 Josh Feinstein 
      2 Jim Elgin 
      2 Jeff Bailey 
      2 Jan Nieuwenhuizen 
      2 Jan Moringen 
      2 Ingo Lohmar 
      2 Giorgos Keramidas 
      2 Gabor Vida 
      2 Francesc Rocher 
      2 Eyal Lotem 
      2 E Sabof 
      2 Eric Abrahamsen 
      2 era eriksson 
      2 Ed Reingold 
      2 Dmitry Kurochkin 
      2 Didier Verna 
      2 David Röthlisberger 
      2 Daniel Dehennin 
      2 Brian Jenkins 
      2 Barry A. Warsaw 
      2 Alex Ott 
      2 Aleksei Gusev 
      2 Alan Schmitt 
      2 Adam Spiers 
      1 Йордан Миладинов 
      1 Yves Baumes 
      1 Yuya Nishihara 
      1 Yuri Karaban 
      1 Yuanle Song 
      1 Yoshiaki Kasahara 
      1 YE Qianchuan 
      1 Yavor Doganov 
      1 Yair Friedman 
      1 W. Trevor King 
      1 Wolfgang Schnerring 
      1 W. Martin Borgert 
      1 William Parsons 
      1 Wilfred Hughes 
      1 Wesley Dawson 
      1 Werner Meisner 
      1 Wang Diancheng 
      1 Volker Sobek 
      1 Vida Gabor 
      1 Vegard Øye 
      1 Vagn Johansen 
      1 Uwe Brauer 
      1 U. Ser 
      1 Uday S Reddy 
      1 Tsuyoshi Kitamoto 
      1 Toru TSUNEYOSHI 
      1 Tom Wood 
      1 Tom Seddon 
      1 Tom Regner 
      1 Tom Breton 
      1 Tomas Abrahamsson 
      1 Toke Høiland-Jørgensen 
      1 Tobias C. Rittweiler 
      1 Timo Myyrä 
      1 Tim Landscheidt 
      1 Thomas Fitzsimmons 
      1 Thierry Banel 
      1 Tetsuo Tsukamoto 
      1 Ted Phelps 
      1 Tak Ota 
      1 Syver Enstad 
      1 Svante Signell 
      1 Steve Yegge 
      1 Steve Chapel 
      1 Steinar Bang 
      1 Stefan-W. Hahn 
      1 Stefano Facchini 
      1 Stefan Bruda 
      1 Simon Schubert 
      1 Simon Law 
      1 Simen Heggestøyl 
      1 Shyam Karanatt 
      1 Shigeru Fukaya 
      1 shawn boles 
      1 Sergei Organov 
      1 Sébastien Gross 
      1 Sebastian Hermida 
      1 Sean Neakums 
      1 Scott Frazer 
      1 Samuel Thibault 
      1 rzl24ozi 
      1 Ryan Yeske 
      1 Ryan Twitchell 
      1 Ryan Crum 
      1 Ryan Barrett 
      1 Ryan 
      1 Rupert Swarbrick 
      1 Roy Hashimoto 
      1 Rod Whitby 
      1 Robert Pluim 
      1 Robert Brown (tiny change) 
      1 Richard Levitte 
      1 Richard Kim 
      1 René Kyllingstad 
      1 Raul Acevedo 
      1 Rasmus Pank Roulund 
      1 Ransom Williams 
      1 Rainer Orth 
      1 Primoz PETERLIN 
      1 Prestoo Ten 
      1 PJ Weisberg 
      1 Pieter Schoenmakers 
      1 Philipp Rumpf 
      1 Philipp Haselwarter 
      1 Petr Hracek 
      1 Peter S Galbraith 
      1 Peter Rosin 
      1 Peter Münster 
      1 Peter Kleiweg 
      1 Peder O. Klingenberg 
      1 Paul Rankin 
      1 Paul Pogonyshev 
      1 Paul Fisher 
      1 Olof Ohlsson Sax 
      1 Oliver Scholz 
      1 Oleksandr Gavenko 
      1 Oleh Krehel 
      1 Ognyan Kulev 
      1 oblique 
      1 Noam Postavsky 
      1 Nikolaj Schumacher 
      1 Nic Ferrier 
      1 Nelson Ferreira 
      1 Naohiro Aota 
      1 Nali Toja 
      1 Mitchel Humpherys 
      1 Mirek Kaim 
      1 Milan Zamazal 
      1 Mike Rowan 
      1 Mihir Rege 
      1 Michael Welsh Duggan 
      1 Michael Vehrs 
      1 Michael Shields 
      1 Michael McNamara 
      1 Michael Marchionna 
      1 Michael Hoffman 
      1 Michael Gauland 
      1 Micah Anderson 
      1 Matt McClure 
      1 Matt Fidler 
      1 Mats Lidell 
      1 Masashi Fujimoto 
      1 Martin Pohlack 
      1 Markus Triska 
      1 Mark Diekhans 
      1 Manuel Gómez 
      1 Manoj Srivastava 
      1 LynX 
      1 Lukas Huonker 
      1 Luis Felipe López Acevedo 
      1 Ludovic Courtès 
      1 Ludovic Courtes 
      1 Liang Wang 
      1 Liam Stitt 
      1 Leonardo Nobrega 
      1 Leonard H. Tower Jr 
      1 Laimonas V bra 
      1 l3thal 
      1 Kristoffer Grönlund 
      1 Knut Anders Hatlen 
      1 Kirk Kelsey 
      1 Kirill A. Korinskiy 
      1 Kevin Layer 
      1 Kenjiro Nakayama 
      1 Keitaro Miyazaki 
      1 Karol Ostrovsky 
      1 Karl Pflästerer 
      1 Karl Chen 
      1 Julian Scheid 
      1 Juergen Hoetzel 
      1 Jose Marino 
      1 Jose E. Marchesi 
      1 Jorge A. Alfaro Murillo 
      1 Joost Kremers 
      1 Jonathan Rockway 
      1 Jonathan Marchand 
      1 John Yates 
      1 John Mastro 
      1 John Marino 
      1 John Hassey 
      1 Joe Vornehm Jr. 
      1 Joe Matarazzo 
      1 Joel Ray Holveck 
      1 Joel Bion 
      1 Jirka Kosek 
      1 Jim Diamond 
      1 Jes Bodi Klinke 
      1 Jeremy Moore 
      1 Jed Brown 
      1 Jean Haidouk 
      1 Jason S. Cornez 
      1 Jason Merrill 
      1 Jason L. Wright 
      1 Jarosław Rzeszótko 
      1 Jan Beich 
      1 Jae-hyeon Park 
      1 Jack Duthen 
      1 IRIE Shinsuke 
      1 Ikumi Keita 
      1 Igor Kuzmin 
      1 Ian D 
      1 Hrvoje Niksic 
      1 HIROSHI OOTA 
      1 H. Dieter Wilhelm 
      1 HAMANO Kiyoto 
      1 Gustav Hållberg 
      1 Gregor Zattler 
      1 Giuseppe Scrivano 
      1 Gergely Risko 
      1 George McNinch 
      1 Geoff Gole 
      1 Fran Litterio 
      1 Florian Adamsky 
      1 Felix H. Dahlke 
      1 Esa Peuha 
      1 Eric Schulte 
      1 Eric Brown 
      1 Enami Tsugutomo 
      1 Edward Reingold 
      1 Edward O'Connor 
      1 Drake Wilson 
      1 Douglas Lewan 
      1 Don March 
      1 Dmitry Bolshakov 
      1 Dieter Schuster 
      1 Devon Sean McCullough 
      1 Detlev Zundel 
      1 David Raynes 
      1 David Michael 
      1 David Koppelman 
      1 David De La Harpe Golden 
      1 David Caldwell 
      1 David Cadé 
      1 David Burger 
      1 David Biesack 
      1 David Benjamin 
      1 David Abrahams 
      1 Dave Goldberg 
      1 Dato Simó 
      1 Daniel Hagerty 
      1 Daniel E. Doherty 
      1 Daniel Clemente 
      1 Daniel Bergey 
      1 Damyan Pepper 
      1 Damien Cassou 
      1 Dale Sedivec 
      1 Courtney Bane 
      1 Constantin Kulikov 
      1 Chris Zheng 
      1 Christoph Scholtes <>
      1 Christopher J. White 
      1 Christopher Genovese 
      1 Christoph Egger 
      1 Christoph 
      1 Christian Wittern 
      1 Chris Siebenmann 
      1 Chris Newton 
      1 Chris Hanson 
      1 Chris Foote 
      1 Charles Rendleman 
      1 cg 
      1 BT Templeton 
      1 Bruno Félix Rezende Ribeiro 
      1 Brian McKenna 
      1 Brent Goodrick 
      1 Bob Nnamtrop 
      1 Bill Carpenter 
      1 Benjamin Rutt 
      1 Bastien 
      1 Barry Fishman 
      1 Aurélien Aptel 
      1 Łukasz Stelmach 
      1 Atsuo Ohki 
      1 Artur Malabarba 
      1 Arne Jørgensen 
      1 “Martin 
      1 Anonymous 
      1 Anmol Khirbat 
      1 Andy Sawyer 
      1 Andy Moreton 
      1 Andrey Kotlarski 
      1 Andrew W. Nosenko 
      1 Andrew Schein 
      1 Andrew Beals 
      1 Andrei Chitu 
      1 Andreas Rottmann 
      1 Andrea Rossetti 
      1 Ami Fischman 
      1 Alvar Jesus Ibeas Martin 
      1 Adam W 
      1 Adam Sokolnicki 

Re: More metaproblem

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: esr@thyrsus.com,  eggert@cs.ucla.edu,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Thu, 04 Dec 2014 12:33:10 -0600

Not really sure how to respond to this.  What exactly is the purpose
of what you wrote?

Anyway, some random comments.

> >See admin/notes/repo and admin/notes/commits.  What else is missing?
> 
> New developers are somehow supposed to know that those random files in
> admin/notes/ are what they need to read?

They usually ask and get told about that.

> What most projects do is have a development web page. linked to from
> their main user-facing web page.  The development page organizes all
> this stuff and provides links to source code repository, dev guidelines
> & documentation, etc.

Volunteers are welcome to take similar care of the Emacs Web page.
I'm sure they will be most welcome if and when they come.

> > Feel free to contribute the missing documentation, and thanks in
> > advance.
> 
> It's not just a matter of contributing documentation.  We don't even
> *have a place to put such documentation* right now.

Of course we do: etc/CONTRIBUTE.  We just decided to move it to the
top-level directory.

> >> Emacs is not an easy project for newcomers or drive-by contributors.
> >
> >Which large and complex project _is_ easy for newcomers?
> 
> Mozilla Firefox or LibreOffice, to name two off the top of my head.

Don't know anything about those.  I do know about GCC, GDB, Groff,
Guile, heck, even Make.  Nothing easy there for newcomers.

> There are many more.

Please name them.

And what counts as "easy", anyway? having a "contribute" Web page?
Are you really going to seriously claim that this is all that stands
between a project and being "easy" on newcomers?  If so, perhaps we
have been contributing to 2 very different classes of software
projects, because the main obstacle in my experience is not the
mundane rules like that, it's the need to understand the architecture
and the design of a complex piece of software, enough so to be able to
contribute non-trivial changes.

> >I think if you dislike so much in Emacs development practices, you
> >should become much more active than you are, and then you maybe stand
> >a chance to start changing all that.
> 
> It's precisely that I don't have time to be more active than I am, that
> leads me to want the project's development procedures to be more
> conducive to developers like me -- there are many of them out there.

Then you don't have the right to whine about how the project is being
managed.  Any serious change in management comes from within, not from
the outside.  This is Free Software; each one scratches the itches
that bother them.  You cannot force me or anyone else to do things we
don't like or don't feel qualified doing.  You think it's important --
get your own sleeves up, and get to work.  If you don't, then you need
to learn to live in peace with what others do for you, however they
decide to do it.  Not working on something you consider important, and
instead pouncing on those who do work is just plain rude.

> But to deny that the project is difficult for incoming developers?

Who denied it?  I didn't.

> But claiming there is no problem, that the phenomenon is not real, does
> not seem plausible to me.

Who claimed that?  I didn't!

> For a widely used *programmer's tool*, that is self-documenting and
> has an extension language, Emacs has an astonishingly low rate of
> lightweight contributed development.

There's any number of small jobs described both in etc/TODO and on the
bug tracker.  If there are indeed people who want to contribute on
some small scale, there's a lot to be done, and such contributions
will and always were very welcome.

> Can you help make your hypothesis falsifiable?  (In the intellectually
> rigorous sense, I mean, not the "make it false" sense.)  I might be able
> to find some time to do that.  In other words, can you tell me what
> measurable signs *you* would look for to determine if a free software
> project were stagnating, and then we can look to see if Emacs is
> exhibiting those signs?  (For example: rate at which developers slow
> down or stop contributing; relatively greater slowdown in rate of
> acquisition of new developers compared to other projects; shrinking
> diversity in first responders to bug reports; etc, etc.)

I have neither time nor motivation for that.  I do what I can for
Emacs; I cannot do more.  I only hope what I do is enough.  I'm sure
the same is true for Stefan, and Glenn, and a handful of other "core
maintainers".  If you or someone else think what we do is not good
enough in some area, you are invited to come aboard and change how
things are done.

> Committers sorted by commit count since 1985, in case it's interesting
> (obviously doesn't count patches and many other things, so this is only
> semi-data, not data):

And what was that all about?  What did you post the list for?

To summarize, my analysis of what you wrote is that you expect too
much of the handful of volunteers who develop and maintain Emacs
entirely on their free time.  A few people can only do this much.  You
want to improve things -- come aboard and be welcome.

Re: More metaproblem

[Jorgen Schaefer]

On Thu, 04 Dec 2014 23:21:33 +0200
Eli Zaretskii <eliz@gnu.org> wrote:

> > It's precisely that I don't have time to be more active than I am,
> > that leads me to want the project's development procedures to be
> > more conducive to developers like me -- there are many of them out
> > there.
> 
> Then you don't have the right to whine about how the project is being
> managed.

Do you realize how incredibly hostile this comes across as?

As a possible contributor, reading this, how inclined do you think this
makes me to bring up possible stumbling blocks I might have when trying
to contribute to Emacs?

And let me tell you, my experience with *trying* to contribute to Emacs
so far mainly has left me with the impression that I might be able to
contribute to Emacs *despite*, not *because*, of the best efforts of
"the management". But only if I work really hard for it.

Of course, I should not bring this up, because my time is limited and I
am only interested in some minor contributions, so my opinion is
irrelevant, and I "don't have the right to whine" about this, right?

On this topic, I can highly recommend Brenda Lynne Chawner's thesis
_Factors Influencing Participant Satisfaction with Free/Libre and Open
Source Software Projects._[1] Section 9.3 includes this rather hands-on
list of suggestions (p. 213):

| - ensure that the project’s ‘About’ page and documentation include
|   information about what types of contributions are most needed, and
|   how to contribute
| - acknowledge and celebrate contributions, so that people who do
|   contribute feel appreciated and motivated to continue;
| - monitor questions in the project’s email discussion list and/or
|   forums, particularly those from newcomers, to ensure that they are
|   answered;
| - provide information to the project’s community about the project’s
|   future development, perhaps in the form of a ‘road map’ that lists
|   the planned changes and enhancements;
| - ensure that documentation is up-to-date, and that aspects of the
|   software that may be perceived as complex are explained clearly;
|   and
| - find out what barriers participants encounter when making a
|   contribution to the project, and take steps to minimise or
|   eliminate them.

It is probably not obvious to you, but Emacs fails at every single one
of those to various degrees.

And only somewhat related, for you especially, Eli, I can highly
recommend John E. Vincent's essay on _Software Empathy_.[2]


(As a balancing point, I should add that it's not all bleak. I have
received very kind and helpful responses to some questions on this
list, and especially - but not only - Stefan can be very friendly and
supportive.)


Regards,
Jorgen


[1]
http://researcharchive.vuw.ac.nz/bitstream/handle/10063/1710/thesis.pdf?sequence=4
Summary at
http://opensource.com/business/14/8/study-participant-satisfaction-open-source-projects

[2] http://blog.lusis.org/blog/2014/10/19/software-empathy/

Re: More metaproblem

[Eli Zaretskii]

> Date: Thu, 4 Dec 2014 23:01:31 +0100
> From: Jorgen Schaefer <forcer@forcix.cx>
> Cc: Karl Fogel <kfogel@red-bean.com>, esr@thyrsus.com,
>  monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> On Thu, 04 Dec 2014 23:21:33 +0200
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > > It's precisely that I don't have time to be more active than I am,
> > > that leads me to want the project's development procedures to be
> > > more conducive to developers like me -- there are many of them out
> > > there.
> > 
> > Then you don't have the right to whine about how the project is being
> > managed.
> 
> Do you realize how incredibly hostile this comes across as?

It's not.  Just try reading it with fresh eyes.

In any case, it's no more hostile than Karl's attack.

And it's the truth.

> As a possible contributor, reading this, how inclined do you think this
> makes me to bring up possible stumbling blocks I might have when trying
> to contribute to Emacs?

I hope the same as you were before.  People bring up stumbling blocks
here all the time, and I think we try to eliminate the ones that we
can.

> And let me tell you, my experience with *trying* to contribute to Emacs
> so far mainly has left me with the impression that I might be able to
> contribute to Emacs *despite*, not *because*, of the best efforts of
> "the management". But only if I work really hard for it.

If you imply that "the management" consciously makes it harder for you
to contribute, then I certainly disagree and object.

> Of course, I should not bring this up, because my time is limited and I
> am only interested in some minor contributions, so my opinion is
> irrelevant, and I "don't have the right to whine" about this, right?

No, that's not what I said.  And it all depends what you say and how.
For now, I have no idea yet what bothers you and why, so I really
cannot comment.

> | - ensure that the project’s ‘About’ page and documentation include
> |   information about what types of contributions are most needed, and
> |   how to contribute
> | - acknowledge and celebrate contributions, so that people who do
> |   contribute feel appreciated and motivated to continue;
> | - monitor questions in the project’s email discussion list and/or
> |   forums, particularly those from newcomers, to ensure that they are
> |   answered;
> | - provide information to the project’s community about the project’s
> |   future development, perhaps in the form of a ‘road map’ that lists
> |   the planned changes and enhancements;
> | - ensure that documentation is up-to-date, and that aspects of the
> |   software that may be perceived as complex are explained clearly;
> |   and
> | - find out what barriers participants encounter when making a
> |   contribution to the project, and take steps to minimise or
> |   eliminate them.

I think we do most of that.

> It is probably not obvious to you, but Emacs fails at every single one
> of those to various degrees.

I disagree.  But I'd be delighted to see more people participate in
these efforts, and I'm sure so will Stefan and others.

> And only somewhat related, for you especially, Eli, I can highly
> recommend John E. Vincent's essay on _Software Empathy_.[2]

That's simply unfair and uncalled for.

Re: More metaproblem

[Aurélien Aptel]

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

Concerning the new developer resources and architectural complexity:
there's the HackerGuide buried on the wiki which could be improved and get
more exposition.

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

Re: More metaproblem

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 08:55:06 +0100
> From: Aurélien Aptel <aurelien.aptel@gmail.com>
> Cc: kfogel@red-bean.com, Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org, 
> 	Jorgen Schaefer <forcer@forcix.cx>, esr@thyrsus.com
> 
> Concerning the new developer resources and architectural complexity: there's
> the HackerGuide buried on the wiki which could be improved and get more
> exposition.

Indeed, thanks.  I've posted some comments on that in

  http://lists.gnu.org/archive/html/help-gnu-emacs/2013-03/msg00006.html

Re: the Emacs wiki

[Stephen Leake]

Aurélien Aptel <aurelien.aptel@gmail.com> writes:

> Concerning the new developer resources and architectural complexity:
> there's the HackerGuide buried on the wiki which could be improved and get
> more exposition.

It starts with "Bazaar".

Most of the rest is better done in (info "(elisp)Top").

So I'd much rather _delete_ that page, and add a reference to CONTRIBUTE
to http://www.emacswiki.org/emacs/GitForEmacsDevs. CONTRIBUTE in turn
references the elisp manual.



What is the intended process for maintaining the wiki?

Suppose I want to clean up all references to Bazaar, and make sure the
wiki presents a clear and consistent picture of the Emacs development
process?

I can easily do that in ./CONTRIBUTE, because it will be reviewed by the
other Emacs developers.

Finding things in the wiki is a nightmare. Maintaining them is worse.

I don't mind maintaining one or two wiki pages, as long as they are referenced
from CONTRIBUTE as important web pages. That's my concession to the "we must
use the web" bandwagon. Anything more than that is unmaintainable.

It would make more sense if there was a higher-level wiki page that was
well maintained, that talked more about Emacs in general, not just how
to use git.

-- 
-- Stephe

Re: the Emacs wiki

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Sat, 06 Dec 2014 04:41:49 -0600
> 
> What is the intended process for maintaining the wiki?
> 
> Suppose I want to clean up all references to Bazaar, and make sure the
> wiki presents a clear and consistent picture of the Emacs development
> process?
> 
> I can easily do that in ./CONTRIBUTE, because it will be reviewed by the
> other Emacs developers.
> 
> Finding things in the wiki is a nightmare. Maintaining them is worse.
> 
> I don't mind maintaining one or two wiki pages, as long as they are referenced
> from CONTRIBUTE as important web pages. That's my concession to the "we must
> use the web" bandwagon. Anything more than that is unmaintainable.
> 
> It would make more sense if there was a higher-level wiki page that was
> well maintained, that talked more about Emacs in general, not just how
> to use git.

(You forgot to mention that the Wiki stuff is uncontrolled and
therefore its quality sucks.)

Wiki is a hydra you cannot cut enough heads off to make it die.  I
tried, and failed miserably.  I suggest you don't waste your efforts
and time on that.

Ideally, everything that's valuable on the Wiki should be in some
manual under doc/misc/.  But there are people out there that just
cannot be convinced, and I stopped trying.

The best we can do is to add such manuals to Emacs, maintain them to
be always up to date, and hope that the Wiki will die of natural
causes, because it falls behind.  But adding that stuff under doc/
requires a dedicated volunteer, which is hard to get by, because the
job sounds like a waste of resources (and in some sense, it really
is).

Bottom line, I suggest that we make the best effort we can to have our
documentation in this area as good as it gets, and turn a blind eye
towards the Wiki.  Then, if people come up, here or on help-gnu-emacs,
complaining that the Wiki says something that isn't correct, we could
just tell them that the Wiki isn't supported by the project, and
advise them to look at our documents instead.

Re: the Emacs wiki

[Nic Ferrier]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> What is the intended process for maintaining the wiki?

There's a git repo that backs it up so you can use that to do extensive
processing. You can't update that way though.

There are APIs for the emacswiki though. So it wouldn't be hard to right
a tool to batch process the git repo and send updates through the api.


Nic

Re: the Emacs wiki

[Stephen Leake]

Nic Ferrier <nferrier@ferrier.me.uk> writes:

> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>
>> What is the intended process for maintaining the wiki?
>
> There's a git repo that backs it up so you can use that to do extensive
> processing. You can't update that way though.
>
> There are APIs for the emacswiki though. So it wouldn't be hard to right
> a tool to batch process the git repo and send updates through the api.

What I get from this is:

    1) There is _no_ intended process for maintaining the wiki.

    2) The technical means are in place to do some editing.

A successful process requires much more than technical means; it
requires developer/editor/user buy in.

-- 
-- Stephe

Re: the Emacs wiki

[Nic Ferrier]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

> Nic Ferrier <nferrier@ferrier.me.uk> writes:
>
>> Stephen Leake <stephen_leake@stephe-leake.org> writes:
>>
>>> What is the intended process for maintaining the wiki?
>>
>> There's a git repo that backs it up so you can use that to do extensive
>> processing. You can't update that way though.
>>
>> There are APIs for the emacswiki though. So it wouldn't be hard to right
>> a tool to batch process the git repo and send updates through the api.
>
> What I get from this is:
>
>     1) There is _no_ intended process for maintaining the wiki.
>
>     2) The technical means are in place to do some editing.
>
> A successful process requires much more than technical means; it
> requires developer/editor/user buy in.

That's right. I would like to help move the wiki to a nicer place than
it is now but please note there are a whole bunch of people from whom
the chaotic nature (in opposition to a controlled one) is the principle
reason for using it.


Nic

Re: the Emacs wiki

[Alexis]

Nic Ferrier writes:

> That's right. I would like to help move the wiki to a nicer place than
> it is now but please note there are a whole bunch of people from whom
> the chaotic nature (in opposition to a controlled one) is the principle
> reason for using it.

Might it be possible/practical to have at least a /section/ of the wiki
set aside as a 'controlled' area for Emacs devs/maintainers to make use
of[1]?


Alexis.

[1] Should they feel it useful to do so, of course!

Re: the Emacs wiki

[Nic Ferrier]

Alexis <flexibeast@gmail.com> writes:

> Nic Ferrier writes:
>
>> That's right. I would like to help move the wiki to a nicer place than
>> it is now but please note there are a whole bunch of people from whom
>> the chaotic nature (in opposition to a controlled one) is the principle
>> reason for using it.
>
> Might it be possible/practical to have at least a /section/ of the wiki
> set aside as a 'controlled' area for Emacs devs/maintainers to make use
> of[1]?

All sorts of things might be possible.

The current software might find that difficult... basically it's mostly
one guy making it. But he might be happy to help.

I and another chap are slowly making an alternative (but supporting)
wiki server. But I'm bogged down in work again now and won't be free for
months.


Nic

Re: More metaproblem

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > > Date: Thu, 4 Dec 2014 23:01:31 +0100
 > > From: Jorgen Schaefer <forcer@forcix.cx>
 > > Cc: Karl Fogel <kfogel@red-bean.com>, esr@thyrsus.com,
 > >  monnier@iro.umontreal.ca, emacs-devel@gnu.org
 > > 
 > > On Thu, 04 Dec 2014 23:21:33 +0200
 > > Eli Zaretskii <eliz@gnu.org> wrote:
 > > 
 > > > > It's precisely that I don't have time to be more active than I am,
 > > > > that leads me to want the project's development procedures to be
 > > > > more conducive to developers like me -- there are many of them out
 > > > > there.
 > > > 
 > > > Then you don't have the right to whine about how the project is
 > > > being managed.
 > > 
 > > Do you realize how incredibly hostile this comes across as?
 > 
 > It's not.  Just try reading it with fresh eyes.

That's also a "hostile" response.

In the brave new world, the writers are supposed to be responsible for
not offending the readers and considering the needs of the reader.
Sometimes this is taken too far, but in general it's very workable and
has some advantages.  In particular, it helps avoid long stupid
threads.  (It's not a vaccine, but it does help.)

In particular, the older "infrastructure" projects (the earlier GNU
projects such as gcc, glibc, Emacs, the Linux kernel, the BSDs) today
have a widespread reputation for hostility in general and
unfriendliness to "diversity" in particular.  One respected developer
in another community recently referred to GNU as a "cesspit" in the
same breath as condemning GitHub for its hostile internal environment.

I don't agree with this evaluation of Emacs or other GNU projects, but
it's only fair that you know that it is indeed widespread.

 > In any case, it's no more hostile than Karl's attack.

If "Karl's attack" refers to the text "It's precisely ... out there."
quoted above, your retort was indeed more hostile.  That quote nowhere
describes only the feelings of Karl himself, and therefore cannot be
considered hostile.  The word "whine", however, is hostile, however
justified.

 > And it's the truth.

It's not obvious he was whining.

What's true IMO is that Emacs doesn't necessarily need more drive-by
contributions (although ELPA does want them).

 > > As a possible contributor, reading this, how inclined do you think this
 > > makes me to bring up possible stumbling blocks I might have when trying
 > > to contribute to Emacs?
 > 
 > I hope the same as you were before.

Doesn't work that way in the brave new world, sorry.  Consider this
list:

 > > | - ensure that the project’s ‘About’ page and documentation include
 > > |   information about what types of contributions are most needed, and
 > > |   how to contribute
 > > | - acknowledge and celebrate contributions, so that people who do
 > > |   contribute feel appreciated and motivated to continue;
 > > | - monitor questions in the project’s email discussion list and/or
 > > |   forums, particularly those from newcomers, to ensure that they are
 > > |   answered;
 > > | - provide information to the project’s community about the project’s
 > > |   future development, perhaps in the form of a ‘road map’ that lists
 > > |   the planned changes and enhancements;
 > > | - ensure that documentation is up-to-date, and that aspects of the
 > > |   software that may be perceived as complex are explained clearly;
 > > |   and
 > > | - find out what barriers participants encounter when making a
 > > |   contribution to the project, and take steps to minimise or
 > > |   eliminate them.

Emacs indeed does not come up to current "standard" for these aspects
of project management.  But since when does GNU conform to standard,
rather than take it as suggestive?  OTOH, you might want to consider
that "current standard" does affect the desire of new contributor to
participate in the Emacs project.

 > > And only somewhat related, for you especially, Eli, I can highly
 > > recommend John E. Vincent's essay on _Software Empathy_.[2]
 > 
 > That's simply unfair and uncalled for.

Indeed, *that* was hostile.  Compare to the first quote in the stack
at the very beginning.

Re: More metaproblem

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Cc: Jorgen Schaefer <forcer@forcix.cx>,
>     kfogel@red-bean.com,
>     esr@thyrsus.com,
>     monnier@iro.umontreal.ca,
>     emacs-devel@gnu.org
> Date: Sat, 06 Dec 2014 14:11:48 +0900
> 
> In particular, the older "infrastructure" projects (the earlier GNU
> projects such as gcc, glibc, Emacs, the Linux kernel, the BSDs) today
> have a widespread reputation for hostility in general and
> unfriendliness to "diversity" in particular.  One respected developer
> in another community recently referred to GNU as a "cesspit" in the
> same breath as condemning GitHub for its hostile internal environment.
> 
> I don't agree with this evaluation of Emacs or other GNU projects, but
> it's only fair that you know that it is indeed widespread.

I do know.

>  > In any case, it's no more hostile than Karl's attack.
> 
> If "Karl's attack" refers to the text "It's precisely ... out there."
> quoted above, your retort was indeed more hostile.

No, it refers to the entire series of his posts on the related issues
here, lately and in the past.  You need to read them in their entirety
to get the feeling.

>  > And it's the truth.
> 
> It's not obvious he was whining.

OK, if "whine" is the only hostile part, then I apologize for using
that word.  I should have replaced it with a less aggressive one, I
suppose.

But that was just one word.  Remove it from the text, and then tell me
whether it is still hostile.

Re: More metaproblem

[Nicolas Richard]

Jorgen Schaefer <forcer@forcix.cx> writes:
> And only somewhat related, for you especially, Eli, I can highly
> recommend John E. Vincent's essay on _Software Empathy_.[2]

FWIW, it took me a bit of getting used to his style, but I found Eli's
answer helpful at all times. I don't know if the above comment was meant
as an honest suggestion, but I can see how it can be taken as a
personnal attack and that saddens me some.

-- 
Nicolas

Re: More metaproblem

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

Often it is hard to anticipate how our words might be taken
as personal criticism.  That is one of the bad aspects of email:
people perceive offense where no offense was meant.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: More metaproblem

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>Not really sure how to respond to this.  What exactly is the purpose
>of what you wrote?

I'm trying to spell out the nature of the problem in order to persuade
influential Emacs developers (like you) that there is a problem.  If
enough agree, that can make it easier to fix, even if those people
aren't the ones who fix it.

For example, momentum is building around auto-generated ChangeLogs now,
largely because developers who contribute a lot to Emacs are either
supporting it or no longer actively resisting it.

I'd like to build momentum similarly around the idea of revamping the
way we treat contributors, especially new or lightly-contributing ones.

If we had a consensus about how to improve the contributor intake
process, that might make people who are currently too afraid to
volunteer to do it less afraid.  Currently, volunteering to do it
implies long arguments on this list with people who think things are
fine the way they are, which is prospectively exhausting, so no one's
likely to come out of the woodwork and even try right now.

>> What most projects do is have a development web page. linked to from
>> their main user-facing web page.  The development page organizes all
>> this stuff and provides links to source code repository, dev guidelines
>> & documentation, etc.
>
>Volunteers are welcome to take similar care of the Emacs Web page.
>I'm sure they will be most welcome if and when they come.

Hmm, what is the path for such volunteers?

That site & page are maintained by the FSF -- they're not in the Emacs
tree anywhere.  In other words, whatever the procedures are for
improving the Emacs home page (and creating a developer welcome page),
they are completely different from the procedures for improving the
Emacs code.  So, yay, now I have to learn *two* contribution paths.

>> > Feel free to contribute the missing documentation, and thanks in
>> > advance.
>> 
>> It's not just a matter of contributing documentation.  We don't even
>> *have a place to put such documentation* right now.
>
>Of course we do: etc/CONTRIBUTE.  We just decided to move it to the
>top-level directory.

It should be a web page.  That's how things work now.

But my hypothesis is that anyone who tried to convert it to web page
right now would face multiple obstacles, including not just technical
obstacles but resistance to goal itself.

I'd love to be wrong about that.  Am I?

Specifically:

If we could work out the technical details to have a "www/" directory at
the top level of the Emacs source tree, and have that be where both the
home page http://www.gnu.org/software/emacs/ *and* soon-to-be-written
new developer-oriented pages are maintained, would you be in favor of
that?

(I don't mean volunteer to help, I just mean support the goal or anyway
not oppose it.)

>> Mozilla Firefox or LibreOffice, to name two off the top of my head.
>
>Don't know anything about those.  I do know about GCC, GDB, Groff,
>Guile, heck, even Make.  Nothing easy there for newcomers.

You've named some of the oldest free software projects on the Net, and
ones specifically oriented toward GNU toolchain programmers.  I think
there *might* be some selection bias at work here :-).

>And what counts as "easy", anyway? having a "contribute" Web page?
>Are you really going to seriously claim that this is all that stands
>between a project and being "easy" on newcomers?  If so, perhaps we
>have been contributing to 2 very different classes of software
>projects, because the main obstacle in my experience is not the
>mundane rules like that, it's the need to understand the architecture
>and the design of a complex piece of software, enough so to be able to
>contribute non-trivial changes.

(See above about selection bias.)

My claim was specific:

I claimed that in the other projects I named, you *don't* see people
complaining about how hard it is to contribute, the way we regularly see
here.  I'll add to that the claim that you *do* see new contributor
acquisition and retention at a better rate in well-run projects.  I have
seen this myself in projects I know well, and I've checked my
impressions with people in other projects and they confirm it.

Above, you seem to be confirming my assertion that you don't think
there's a real problem here -- that is, you think that the changes I
describe would not make Emacs easier to contribute to, because the real
causes that make Emacs hard to contribute to have to do with the nature
of the code base.  I don't think that's true, especially in Emacs' case:
it has a well-documented extension language and gazillions of lines of
Elisp code for people to use as examples.  Few projects should be as
easy to contribute to as Emacs should be.

>To summarize, my analysis of what you wrote is that you expect too
>much of the handful of volunteers who develop and maintain Emacs
>entirely on their free time.  A few people can only do this much.  You
>want to improve things -- come aboard and be welcome.

My request is simple and specific:

I'm asking the biggest contributors to Emacs (you, among others) to

  - Not oppose a revamp of the contributor documentation along the lines
    I described;

  - Not oppose using a modern bug tracker -- one that supports email
    manipulation but *also* supports manipulation via a web browser.
    (Redmine, for example.)

Those two changes alone would lower the barrier to entry significantly.

Senior developer resistance to those changes effectively means they can
never take place.  Absence of such resistance doesn't guarantee that
they will take place, but is certainly a necessary precondition.

Right now, any volunteer energy toward such changes is pre-quashed:
anyone who might think of doing them, but who reads this list, would
quickly come to the conclusion that it would be a huge fight, a
months-long abuse fest, and give up in advance.

So I'd love to see that barrier go away, just to see what would happen.

-K

Re: More metaproblem

[Lars Magne Ingebrigtsen]

Karl Fogel <kfogel@red-bean.com> writes:

> If we could work out the technical details to have a "www/" directory at
> the top level of the Emacs source tree, and have that be where both the
> home page http://www.gnu.org/software/emacs/ *and* soon-to-be-written
> new developer-oriented pages are maintained, would you be in favor of
> that?

I think that's a great idea.  

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: More metaproblem

[Eric S. Raymond]

Lars Magne Ingebrigtsen <larsi@gnus.org>:
> Karl Fogel <kfogel@red-bean.com> writes:
> 
> > If we could work out the technical details to have a "www/" directory at
> > the top level of the Emacs source tree, and have that be where both the
> > home page http://www.gnu.org/software/emacs/ *and* soon-to-be-written
> > new developer-oriented pages are maintained, would you be in favor of
> > that?
> 
> I think that's a great idea.  

Yes.  Something like this needs to happen.  It is possible that this is
what the doc directory should become - home for the new, unified,
fully hypertexted document strucuture.  

But getting hung up on the name would be a mistake, and we mustn't 
bikeshed about that. The main points are: no more documentation ghettos,
full web exposure - and info, necessarily, taken out and shot. 
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Karl Fogel]

"Eric S. Raymond" <esr@thyrsus.com> writes:
>> > If we could work out the technical details to have a "www/" directory at
>> > the top level of the Emacs source tree, and have that be where both the
>> > home page http://www.gnu.org/software/emacs/ *and* soon-to-be-written
>> > new developer-oriented pages are maintained, would you be in favor of
>> > that?
>> 
>> I think that's a great idea.  
>
>Yes.  Something like this needs to happen.  It is possible that this is
>what the doc directory should become - home for the new, unified,
>fully hypertexted document strucuture.  
>
>But getting hung up on the name would be a mistake, and we mustn't 
>bikeshed about that. The main points are: no more documentation ghettos,
>full web exposure - and info, necessarily, taken out and shot. 

Oh, agreed.  "doc" is fine instead of "www", whatever.  It's the thing,
not the name, that's most important here.

Re: More metaproblem

[Stefan Monnier]

>> If we could work out the technical details to have a "www/" directory at
>> the top level of the Emacs source tree, and have that be where both the
>> home page http://www.gnu.org/software/emacs/ *and* soon-to-be-written
>> new developer-oriented pages are maintained, would you be in favor of
>> that?
> I think that's a great idea.

The web pages are kept currently in a CVS repository, which requires the
same access rights as the Git repository.
See http://web.cvs.savannah.gnu.org/viewvc/?root=emacs

This is handled by Savannah and I have no idea how easy it would be to
change the setup such that the pages come out of the emacs.git instead.


        Stefan

Re: More metaproblem

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: esr@thyrsus.com,  eggert@cs.ucla.edu,  monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Fri, 05 Dec 2014 10:51:40 -0600
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> >Not really sure how to respond to this.  What exactly is the purpose
> >of what you wrote?
> 
> I'm trying to spell out the nature of the problem in order to persuade
> influential Emacs developers (like you) that there is a problem.

In that case, you are wasting your energy, at least on me.  I have no
doubt there is a problem.  The question, as always, is how to solve
it, not whether it exists.

> I'd like to build momentum similarly around the idea of revamping the
> way we treat contributors, especially new or lightly-contributing ones.

We don't need a momentum.  We need specific practical actions, which
boils down to have volunteers step forward and make that happen.

> If we had a consensus about how to improve the contributor intake
> process, that might make people who are currently too afraid to
> volunteer to do it less afraid.  Currently, volunteering to do it
> implies long arguments on this list with people who think things are
> fine the way they are, which is prospectively exhausting, so no one's
> likely to come out of the woodwork and even try right now.

The arguments happen _solely_ because instead of volunteering, people
try to steam about how wrong the current situation is.  The moment
someone actually does something to improve things, I assure you there
will be no arguments, at least not long ones and not involving the
core maintainers.  (Yes, there will be a few requests here and there,
but that's understandable.)

> >> What most projects do is have a development web page. linked to from
> >> their main user-facing web page.  The development page organizes all
> >> this stuff and provides links to source code repository, dev guidelines
> >> & documentation, etc.
> >
> >Volunteers are welcome to take similar care of the Emacs Web page.
> >I'm sure they will be most welcome if and when they come.
> 
> Hmm, what is the path for such volunteers?

Err... just say that you do, and ask Stefan for instructions on how to
modify the relevant pages?

> That site & page are maintained by the FSF -- they're not in the Emacs
> tree anywhere.  In other words, whatever the procedures are for
> improving the Emacs home page (and creating a developer welcome page),
> they are completely different from the procedures for improving the
> Emacs code.  So, yay, now I have to learn *two* contribution paths.

So you want to change the way FSF maintains Savannah at the same time
you improve Emacs?  And you are still saying this is the practical way
towards improving Emacs, with good chances of success?

> >> It's not just a matter of contributing documentation.  We don't even
> >> *have a place to put such documentation* right now.
> >
> >Of course we do: etc/CONTRIBUTE.  We just decided to move it to the
> >top-level directory.
> 
> It should be a web page.  That's how things work now.
> 
> But my hypothesis is that anyone who tried to convert it to web page
> right now would face multiple obstacles, including not just technical
> obstacles but resistance to goal itself.
> 
> I'd love to be wrong about that.  Am I?

Yes, you are.  AFAIR, no one ever tried that, and therefore there
could be no resistance.

> >> Mozilla Firefox or LibreOffice, to name two off the top of my head.
> >
> >Don't know anything about those.  I do know about GCC, GDB, Groff,
> >Guile, heck, even Make.  Nothing easy there for newcomers.
> 
> You've named some of the oldest free software projects on the Net, and
> ones specifically oriented toward GNU toolchain programmers.  I think
> there *might* be some selection bias at work here :-).

The only bias here is that those are projects I actively participate
in, on some more or less meaningful level.  I can only speak about
things I'm familiar with.

> Above, you seem to be confirming my assertion that you don't think
> there's a real problem here -- that is, you think that the changes I
> describe would not make Emacs easier to contribute to, because the real
> causes that make Emacs hard to contribute to have to do with the nature
> of the code base.

Yes.

> I don't think that's true, especially in Emacs' case: it has a
> well-documented extension language and gazillions of lines of Elisp
> code for people to use as examples.  Few projects should be as easy
> to contribute to as Emacs should be.

What we sorely miss is not random contributions -- these are
important, but they won't help enough.  What we need is to widen the
very small circle of people who can be called "core maintainers" --
those who can review patches, mentor newcomers, write meaningful and
correct "contribute" Web pages, and do all the other tasks that were
discussed here.  And, btw, also develop major new features for Emacs,
without which this project is doomed.

It is impossible to do all that without good familiarity with at least
some areas of the Emacs core.  Without that, you cannot do all those
tasks that everyone wants to be done.  If you don't understand this,
then I'm sorry, but your views on how to make Emacs a better project
in the long run are of no practical importance, because your accents
are all wrong.  Yes, it is very important to make the initiation for
new contributors easier and more friendly, but that will not "save" us
in the long run, unless we also have some practical way of drawing
those newcomers into the Emacs depths, until they become "core".

> I'm asking the biggest contributors to Emacs (you, among others) to
> 
>   - Not oppose a revamp of the contributor documentation along the lines
>     I described;

There's no opposition to that.  Never was, never will be.  The only
problem is to find volunteers capable of doing that and then
maintaining the results.

>   - Not oppose using a modern bug tracker -- one that supports email
>     manipulation but *also* supports manipulation via a web browser.
>     (Redmine, for example.)

I don't know anything about that, and personally never expressed any
opposition.  I do have a few simple requirements for a bug tracker,
but that's all.

> Those two changes alone would lower the barrier to entry significantly.

Then let's go!

> Senior developer resistance to those changes effectively means they can
> never take place.  Absence of such resistance doesn't guarantee that
> they will take place, but is certainly a necessary precondition.

THERE'S NO RESISTANCE!!  Please stop barking up the wrong tree.

> Right now, any volunteer energy toward such changes is pre-quashed:
> anyone who might think of doing them, but who reads this list, would
> quickly come to the conclusion that it would be a huge fight, a
> months-long abuse fest, and give up in advance.

I cannot read people's minds; maybe you can.  I don't know what anyone
might think about volunteering, unless they actually speak up and
volunteer.  I challenge you to find any examples of volunteers in this
area who were turned down by "senior developers".

> So I'd love to see that barrier go away, just to see what would happen.

That barrier doesn't exist!  You are imagining it.

Re: More metaproblem

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>> So I'd love to see that barrier go away, just to see what would happen.
>
>That barrier doesn't exist!  You are imagining it.

The barrier to the bug tracker change is well-documented on this list;
you're probably seen those conversations.  Explicit proposals to move
off debbugs have been made and have been equally explicitly shot down on
the grounds that debbugs is easier for senior maintainers who are
already familiar with it.

I'm very glad to hear you aren't one of those, though.

The barrier to the documentation change is when people see senior devs
pointing to etc/CONTRIBUTE as a fine place for dev documentation and
think "Oh, so the project thinks that's okay?  They point to that as a
solution, rather than as a problem?  I guess I'm in the wrong place."

Perhaps I shouldn't have characterized that as "resistance"; it's more
"active promotion of a sub-optimal thing as though it were perfectly
fine, with implied demotion of better things that could replace it".

I agree that's only an inference -- albeit one that many observers are
likely to make, even if inaccurate.  But if as you're saying the
inference is inaccurate, and that you're fine with the kinds of changes
I described, that's great.  Thanks.

-K

Re: More metaproblem

[Glenn Morris]

Karl Fogel wrote:

> The barrier to the bug tracker change is well-documented on this list;
> you're probably seen those conversations.  Explicit proposals to move
> off debbugs have been made

[citation needed]

Mentioning Launchpad is not an explicit proposal.

> and have been equally explicitly shot down on the grounds that debbugs
> is easier for senior maintainers who are already familiar with it.

I have put a lot of work into debbugs.gnu.org.
I didn't much like it when we got it, but it was the system we had, so I
did work to make it better. Because although many people were
making a lot of noise, as usual not many people were doing anything.
In terms of using it, I've closed well over 1000 bugs.

It integrates pretty well with Emacs IMO, in part thanks to the add-ons
other developers have written.

If you want to replace it with something better, fine by me.
I'd find your arguments more compelling if you had contributed more to
Emacs, but perhaps the existing systems make it impossible for you to do
so. I take Stefan concerns with the tracker much more seriously.
But I have no energy left to make it any better.

Some other GNU projects are using debbugs.gnu.org, so my work won't be
totally wasted.

This and other discussions have pretty much demotivated me,
so I hope whatever new system you put in place works well for whoever is
left to use it.


Taking the weekend off now.

Re: More metaproblem

[Karl Fogel]

Glenn Morris <rgm@gnu.org> writes:
>> The barrier to the bug tracker change is well-documented on this list;
>> you're probably seen those conversations.  Explicit proposals to move
>> off debbugs have been made
>
>[citation needed]
>
>Mentioning Launchpad is not an explicit proposal.
>
>> and have been equally explicitly shot down on the grounds that debbugs
>> is easier for senior maintainers who are already familiar with it.
>
>I have put a lot of work into debbugs.gnu.org.
>I didn't much like it when we got it, but it was the system we had, so I
>did work to make it better. Because although many people were
>making a lot of noise, as usual not many people were doing anything.
>In terms of using it, I've closed well over 1000 bugs.
>
>It integrates pretty well with Emacs IMO, in part thanks to the add-ons
>other developers have written.
>
>If you want to replace it with something better, fine by me.
>I'd find your arguments more compelling if you had contributed more to
>Emacs, but perhaps the existing systems make it impossible for you to do
>so. I take Stefan concerns with the tracker much more seriously.
>But I have no energy left to make it any better.

The sentiment you express above, toward the end, is one I see more often
expressed in this project than in any other I work on.  I'm sorry to
hear it.

I'm also sorry you put so much work into debbugs only to have me
complain about it.  However, I don't think that the only possible way
people should be able to make proposals for new trackers (or whatever)
is to post gigantic, detailed proposals that anticipates every question
and technical difficulty -- and *then* get a "yes or no" answer.

Instead, the way this usually works is someone posts an overview
proposal first.

I don't have time to dig mine out of the archives now, but when I did it
was basically "How about we move to a modern, web-friendly bug tracker
that *also* integrates with email similarly to how debbugs does, so that
everyone has the functionality they want?"  I then named some systems
that do this, so people would know it wasn't just blue-sky dreaming.

This was shot down with "we senior devs like the way debbugs works, so
your proposal has little chance of happening".

So *after that*, I'm supposed to spend the time to write up the full,
detailed proposal?  As a way of maybe winning the argument anyway?
That's going to be a good investment of my time, after the initial
rejection of the idea?

I don't that's a reasonable way to expect volunteers to approach things.

Re: More metaproblem

[Eric S. Raymond]

Karl Fogel <kfogel@red-bean.com>:
> That's going to be a good investment of my time, after the initial
> rejection of the idea?

There's another version of this that's common here.  It's "We will not
consider anything new unless you commit to doing *all* the hard work
yourself, up front, and also a whole bunch of related shitwork that we
haven't been able to find anyone to take on."

It's basically a way to day "Fuck off" while sounding pseudo-responsible.
It doesn't fool anyone, though.  The underlying message of reflexive
rejection of change is clear.

Heaven forfend anyone should offer to ... cooperate.  Spread the load.
When was the last time we heard anyone saying in reaction to a big new
proposal "That's a great idea you just had.  I'll do *this* piece."

And yet, we wonder why there are 500+ regulars on #emacs  who don't dare
set foot in here.  Well, why should they?  It's a hostile work environment.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Ted Zlatanov]

On Fri, 5 Dec 2014 17:24:16 -0500 "Eric S. Raymond" <esr@thyrsus.com> wrote: 

ESR> And yet, we wonder why there are 500+ regulars on #emacs  who don't dare
ESR> set foot in here.  Well, why should they?  It's a hostile work environment.

The environment here was actually pretty friendly and professional until recently.

Ted

Re: More metaproblem

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Fri, 05 Dec 2014 17:41:14 -0500
> 
> On Fri, 5 Dec 2014 17:24:16 -0500 "Eric S. Raymond" <esr@thyrsus.com> wrote: 
> 
> ESR> And yet, we wonder why there are 500+ regulars on #emacs  who don't dare
> ESR> set foot in here.  Well, why should they?  It's a hostile work environment.
> 
> The environment here was actually pretty friendly and professional until recently.

Indeed, and I wonder what exactly caused the change...

Re: More metaproblem

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 17:24:16 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Glenn Morris <rgm@gnu.org>, Eli Zaretskii <eliz@gnu.org>,
> 	eggert@cs.ucla.edu, monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> Karl Fogel <kfogel@red-bean.com>:
> > That's going to be a good investment of my time, after the initial
> > rejection of the idea?
> 
> There's another version of this that's common here.  It's "We will not
> consider anything new unless you commit to doing *all* the hard work
> yourself, up front, and also a whole bunch of related shitwork that we
> haven't been able to find anyone to take on."

Welcome to Free Software.

> It's basically a way to day "Fuck off" while sounding pseudo-responsible.
> It doesn't fool anyone, though.  The underlying message of reflexive
> rejection of change is clear.

It just means it's not my itch to scratch.  There's no rejection here,
quite the contrary: many times such suggestions are welcome.  But
someone still has to do the work, and the best candidate is the one
who is the most motivated to do it.

> Heaven forfend anyone should offer to ... cooperate.  Spread the load.
> When was the last time we heard anyone saying in reaction to a big new
> proposal "That's a great idea you just had.  I'll do *this* piece."

You don't see that because you don't want to.  Read this list more
carefully, and you will see plenty of examples of such cooperation.

> And yet, we wonder why there are 500+ regulars on #emacs  who don't dare
> set foot in here.  Well, why should they?  It's a hostile work environment.

Nonsense.  There's no hostility here.

Re: More metaproblem

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> Nonsense.  There's no hostility here.

I think if you asked on #emacs you might discover that this opinion is ...
not widely shared.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 23:58:51 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: kfogel@red-bean.com, eggert@cs.ucla.edu, monnier@iro.umontreal.ca,
> 	emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org>:
> > Nonsense.  There's no hostility here.
> 
> I think if you asked on #emacs you might discover that this opinion is ...
> not widely shared.

I challenge you to ask and then post the results here, including
similar results for other Free Software projects.  I'm old enough to
know the answer, having seen hostility, including towards myself, and
being able to tell when I see it.

Re: More metaproblem

[Eric S. Raymond]

Eli Zaretskii <eliz@gnu.org>:
> I challenge you to ask and then post the results here, including
> similar results for other Free Software projects.

Wow.  You are truly a *master* of subtle obstructionism. The second
clause in that sentence was a work of art, leaving you wiggle room to
disregard any survey numbers I might to bring back on grounds of
insufficient breadth of sample. And camouflaging this maneuver as an
appeal to scientific objectivity - genius, sheer genius!

Why, if I were a more naive person, I might have immediately gone
beavering off to #emacs, collected several hundred expressions of
frustration, and brought them back here only to have them
high-handedly dismissed.

That general tactic of "I will disregard you until you put in
an amount of work I have pre-defined to be effectively impossible",
yes. An old favorite on this list, a hardy perennial.  Very effective
for resisting any kind of innovation.

This is how Emacs dies.  Not with a bang, but with a whimper.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[David Kastrup]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Eli Zaretskii <eliz@gnu.org>:
>> I challenge you to ask and then post the results here, including
>> similar results for other Free Software projects.
>
> Wow.  You are truly a *master* of subtle obstructionism. The second
> clause in that sentence was a work of art, leaving you wiggle room to
> disregard any survey numbers I might to bring back on grounds of
> insufficient breadth of sample. And camouflaging this maneuver as an
> appeal to scientific objectivity - genius, sheer genius!
>
> Why, if I were a more naive person, I might have immediately gone
> beavering off to #emacs, collected several hundred expressions of
> frustration, and brought them back here only to have them
> high-handedly dismissed.
>
> That general tactic of "I will disregard you until you put in an
> amount of work I have pre-defined to be effectively impossible",
> yes. An old favorite on this list, a hardy perennial.  Very effective
> for resisting any kind of innovation.
>
> This is how Emacs dies.  Not with a bang, but with a whimper.

More like the way in which this thread dies.  In a large billow of
smokescreen masking a non-glamorous exit.

Let me quote Lichtenberg: "Ein Buch ist ein Spiegel: wenn ein Affe
hineinsieht, so kann kein Apostel herausgucken." (a book is a mirror:
when a monkey gazes into it, no apostle will be looking back from it).

You'll find that this aphorism is somewhat applicable to the hostility
of mailing lists.

-- 
David Kastrup

Re: More metaproblem

[Eli Zaretskii]

> Date: Sat, 6 Dec 2014 06:35:57 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: kfogel@red-bean.com, eggert@cs.ucla.edu, monnier@iro.umontreal.ca,
> 	emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org>:
> > I challenge you to ask and then post the results here, including
> > similar results for other Free Software projects.
> 
> Wow.  You are truly a *master* of subtle obstructionism. The second
> clause in that sentence was a work of art, leaving you wiggle room to
> disregard any survey numbers I might to bring back on grounds of
> insufficient breadth of sample.

I didn't say anything about the sample size.  Please don't put words
in my mouth, I'm perfectly capable of expressing my intent myself.

All I asked for is to compare whatever level of dissatisfaction you
find on a feed which I never visit to something similar for other
projects.  I've seen enough talkback forums to know that the level of
flames there could be utterly unrelated to reality.

> And camouflaging this maneuver as an appeal to scientific
> objectivity - genius, sheer genius!
> 
> Why, if I were a more naive person, I might have immediately gone
> beavering off to #emacs, collected several hundred expressions of
> frustration, and brought them back here only to have them
> high-handedly dismissed.

What's to prevent me from interpreting this as a camouflaged attempt
to get off your high horse, because you have no real data to back up
your claims?

> That general tactic of "I will disregard you until you put in
> an amount of work I have pre-defined to be effectively impossible",
> yes. An old favorite on this list, a hardy perennial.  Very effective
> for resisting any kind of innovation.

The tactic to invent non-existing intentions to your opponents and
then label those inventions with derogatory labels is also
well-known.  Not very effective here, but known.

> This is how Emacs dies.  Not with a bang, but with a whimper.

Emacs doesn't die.  Look at the commit rate, if you really want to do
an objective analysis.  Not many live projects can compare with what
we have.

Re: More metaproblem

[Werner LEMBERG]

>> Wow.  You are truly a *master* of subtle obstructionism.  [...]
> 
> The tactic to invent non-existing intentions to your opponents and
> then label those inventions with derogatory labels is also
> well-known.  [...]

I strongly suggest that you two read a translation of Schopenhauer's
`Eristische Dialektik' (`The Art of Being Right: 38 Ways to Win an
Argument', 1831)...


    Werner

Re: More metaproblem

[Stephen Leake]

Karl Fogel <kfogel@red-bean.com> writes:

> The barrier to the documentation change is when people see senior devs
> pointing to etc/CONTRIBUTE as a fine place for dev documentation and
> think "Oh, so the project thinks that's okay?  They point to that as a
> solution, rather than as a problem?  I guess I'm in the wrong place."

I have not seen anyone (other than you) state this.

Can you please give _detailed_ reasons why ./CONTRIBUTE (I just moved
it) is inadequate?

Not just "I prefer web pages", but _why_.

Not just "files are _so_ last century; the web is hip".

It was out of date; that's being fixed, and was not mentioned as a
problem anyway.

> Perhaps I shouldn't have characterized that as "resistance"; it's more
> "active promotion of a sub-optimal thing as though it were perfectly
> fine, with implied demotion of better things that could replace it".

I have given reasons why local files in git are better than web pages;
please explain your reasons.

-- 
-- Stephe

Re: More metaproblem

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Sat, 06 Dec 2014 03:27:10 -0600
> 
> Can you please give _detailed_ reasons why ./CONTRIBUTE (I just moved
> it) is inadequate?
> 
> Not just "I prefer web pages", but _why_.
> 
> Not just "files are _so_ last century; the web is hip".

Seconded.

More importantly, with the Emacs repository being a publicly
accessible place on the Web, CONTRIBUTE should already appear in every
Google search, and so can be considered to be a "Web page" for all
practical purposes, at least as far as discoverability and exposure
are considered.

Re: More metaproblem

[Eric S. Raymond]

Stephen Leake <stephen_leake@stephe-leake.org>:
> Karl Fogel <kfogel@red-bean.com> writes:
> 
> > The barrier to the documentation change is when people see senior devs
> > pointing to etc/CONTRIBUTE as a fine place for dev documentation and
> > think "Oh, so the project thinks that's okay?  They point to that as a
> > solution, rather than as a problem?  I guess I'm in the wrong place."
> 
> I have not seen anyone (other than you) state this.

Potential developers look at things like this and they see a project
that has learned nothing and forgotten nothing since before 1996.

No one thing like this is a dealbreaker for any single person. It's
the accumulation of such details that acts as a KEEP OUT sign.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Eli Zaretskii]

> Date: Sat, 6 Dec 2014 06:41:47 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: emacs-devel@gnu.org
> 
> > > The barrier to the documentation change is when people see senior devs
> > > pointing to etc/CONTRIBUTE as a fine place for dev documentation and
> > > think "Oh, so the project thinks that's okay?  They point to that as a
> > > solution, rather than as a problem?  I guess I'm in the wrong place."
> > 
> > I have not seen anyone (other than you) state this.
> 
> Potential developers look at things like this and they see a project
> that has learned nothing and forgotten nothing since before 1996.
> 
> No one thing like this is a dealbreaker for any single person. It's
> the accumulation of such details that acts as a KEEP OUT sign.

Slogans.  No real data to support that.

Re: More metaproblem

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat, 6 Dec 2014 06:41:47 -0500
>> From: "Eric S. Raymond" <esr@thyrsus.com>
>> Cc: emacs-devel@gnu.org
>> 
>> > > The barrier to the documentation change is when people see senior devs
>> > > pointing to etc/CONTRIBUTE as a fine place for dev documentation and
>> > > think "Oh, so the project thinks that's okay?  They point to that as a
>> > > solution, rather than as a problem?  I guess I'm in the wrong place."
>> > 
>> > I have not seen anyone (other than you) state this.
>> 
>> Potential developers look at things like this and they see a project
>> that has learned nothing and forgotten nothing since before 1996.
>> 
>> No one thing like this is a dealbreaker for any single person. It's
>> the accumulation of such details that acts as a KEEP OUT sign.
>
> Slogans.  No real data to support that.

It's an impression.  That is real data.  It's not like we have anything
better to offer: even being able to point to projects that have a
not-just-for-old-fogies web presence (by the way, anybody who can point
to some significant project maintaining its web pages in AsciiDoc?) is
anecdotal evidence since that does not detail the work that needs to get
invested to get to a similar level starting from the current situation
of Emacs.  And it does nothing to figure out how hard it is to recruit
the people actually doing the work.

However, we are not going to come to a useful discussion when people
assume that the only reason other people may come to different
conclusions is because they are mentally inferior even while
acknowledging that one has not even bothered looking at the data they
suggested as supporting their conclusions.

In that case, there is simply no base for consensus since consensus
implies agreement about the same things.  Which is different from
electing a leader in the expectation that he will get himself educated
in due time for making or following through with decisions, or shoulder
the consequences.

In this case, this approach is simply not an option since the
consequences can't be borne out by a single person.  It's just too much
work for that approach.

There is, if at all, a shortage of workers rather than of saviors.

-- 
David Kastrup

Re: More metaproblem

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Sat, 06 Dec 2014 14:16:16 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Potential developers look at things like this and they see a project
> >> that has learned nothing and forgotten nothing since before 1996.
> >> 
> >> No one thing like this is a dealbreaker for any single person. It's
> >> the accumulation of such details that acts as a KEEP OUT sign.
> >
> > Slogans.  No real data to support that.
> 
> It's an impression.  That is real data.

I agree, but even that needs _some_ evidence.  Like a couple of blogs
or large postings (excluding the person who makes the claim), or some
article in some on-line journal, that show this tendency or express
similar views.  Coming up with this without _any_ evidence is not
serious.

> It's not like we have anything better to offer

We could analyze the hit rate of the project's Web pages, and see if
they diminish over the years, for example.  Or try looking for similar
claims and see  how many of them we had in the past.

Re: More metaproblem

[Eric S. Raymond]

Karl Fogel <kfogel@red-bean.com>:
> If we could work out the technical details to have a "www/" directory at
> the top level of the Emacs source tree, and have that be where both the
> home page http://www.gnu.org/software/emacs/ *and* soon-to-be-written
> new developer-oriented pages are maintained, would you be in favor of
> that?

Something at least roughly equivalent to this *needs to happen*.  

> Elisp code for people to use as examples.  Few projects should be as
> easy to contribute to as Emacs should be.

That is true.  The main barrier is not the codebase; it is guidance and
an uptake process that can best be described as shambolic.

> My request is simple and specific:
> 
> I'm asking the biggest contributors to Emacs (you, among others) to
> 
>   - Not oppose a revamp of the contributor documentation along the lines
>     I described;
> 
>   - Not oppose using a modern bug tracker -- one that supports email
>     manipulation but *also* supports manipulation via a web browser.
>     (Redmine, for example.)
> 
> Those two changes alone would lower the barrier to entry significantly.

Yes, they would.

We need to behave like a normal project with a normal interest in attracting
new developers, doing that in a normal way.  Practice in these areas has
long passed Emacs by.
 
> Senior developer resistance to those changes effectively means they can
> never take place.  Absence of such resistance doesn't guarantee that
> they will take place, but is certainly a necessary precondition.
> 
> Right now, any volunteer energy toward such changes is pre-quashed:
> anyone who might think of doing them, but who reads this list, would
> quickly come to the conclusion that it would be a huge fight, a
> months-long abuse fest, and give up in advance.

Alas, I certainly could not falsify that charge by what I went through
moving us to git.  The Emacs dev list has a culture and traditions
which, though not actually designed to suppress new contributors,
might as well have been.

> So I'd love to see that barrier go away, just to see what would happen.

My meta-plan is to identify barriers to new developers, one by one, 
and dynamite them.

Not being on git was a *biiiig* one. The disorganized and
undiscoverable state of Emacs's internal documentation is another,
which is one reason one of my next minor to-dos is cleaning out the /etc
attic.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Karl Fogel]

"Eric S. Raymond" <esr@thyrsus.com> writes:
>My meta-plan is to identify barriers to new developers, one by one, 
>and dynamite them.
>
>Not being on git was a *biiiig* one. The disorganized and
>undiscoverable state of Emacs's internal documentation is another,
>which is one reason one of my next minor to-dos is cleaning out the /etc
>attic.

  (setq beers_owed_esr (1+ beers_owed_esr))

Re: More metaproblem

[Eric S. Raymond]

Karl Fogel <kfogel@red-bean.com>:
>   (setq beers_owed_esr (1+ beers_owed_esr))

No booze for me, I can't stand the taste of alcohol.  A good dark 
Jamaican-style ginger beer, on the other hand... :-)
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Glenn Morris]

Karl Fogs wrote:

> That site & page are maintained by the FSF -- they're not in the Emacs
> tree anywhere.  In other words, whatever the procedures are for
> improving the Emacs home page (and creating a developer welcome page),
> they are completely different from the procedures for improving the
> Emacs code.  So, yay, now I have to learn *two* contribution paths.

The http://www.gnu.org/software/emacs/ Emacs web pages are maintained in
CVS. This is for technical reasons. CVS here functions mainly as a means
to get the stuff onto the gnu.org web server, rather than as a VCS. Yes,
amazingly, people have proposed changing that to something else. It
takes sysadmin time, which is in very short supply. And CVS works fine,
so it's not a priority.

Anyone who has write access to the Emacs code repo has write access to
the web repo. Changes go live almost immediately, so please be careful.

Instructions at:
http://savannah.gnu.org/cvs/?group=emacs

Re: More metaproblem

[Eric S. Raymond]

Glenn Morris <rgm@gnu.org>:
> Karl Fogs wrote:
> 
> > That site & page are maintained by the FSF -- they're not in the Emacs
> > tree anywhere.  In other words, whatever the procedures are for
> > improving the Emacs home page (and creating a developer welcome page),
> > they are completely different from the procedures for improving the
> > Emacs code.  So, yay, now I have to learn *two* contribution paths.
> 
> The http://www.gnu.org/software/emacs/ Emacs web pages are maintained in
> CVS.

Oh, holy jumping *fuck*.

And you still wonder why you can't get more help maintaining them?
There may be other reasons, but this is a sufficient one.  CVS, like
Texinfo and far too many of this project's inheritances from ancient
times, is a gigantic neon sign that says to new developers WE *LIVE*
TO INFLICT PROCESS PAIN ON YOU.

Let me expand on that.  It not only says WE *LIVE* TO INFLICT PROCESS
PAIN ON YOU, it also says GO AWAY, WE'RE STUCK IN 1990 AND WE LIKE IT
HERE.

Well, at least I can partly fix this. I'll get with Bob Proulx about
converting the repo.  Eventually it should almost certainly move into 
the source tree, but that's pending the big redesign of our
documentation structure.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Eli Zaretskii]

> Date: Fri, 5 Dec 2014 13:56:36 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Karl Fogel <kfogel@red-bean.com>, Eli Zaretskii <eliz@gnu.org>,
> 	eggert@cs.ucla.edu, monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> > The http://www.gnu.org/software/emacs/ Emacs web pages are maintained in
> > CVS.
> 
> Oh, holy jumping *fuck*.
> 
> And you still wonder why you can't get more help maintaining them?
> There may be other reasons, but this is a sufficient one.  CVS, like
> Texinfo and far too many of this project's inheritances from ancient
> times, is a gigantic neon sign that says to new developers WE *LIVE*
> TO INFLICT PROCESS PAIN ON YOU.

THIS IS NOT OUR CVS!!  This is how Savannah handles all projects, it's
not our decision.

You want to change that, too, be my guest.  But don't blame us,
because we didn't invent it and we don't maintain Savannah.

Re: More metaproblem

[Glenn Morris]

>> > The http://www.gnu.org/software/emacs/ Emacs web pages are maintained in
>> > CVS.
>> 
>> Oh, holy jumping *fuck*.
>> 
>> And you still wonder why you can't get more help maintaining them?

Oh look. An abusive jump-to-conclusions that demonstrates a complete
ignorance of the facts. How surprising.

Re: More metaproblem

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

  > >> Oh, holy jumping *fuck*.
  > >> 
  > >> And you still wonder why you can't get more help maintaining them?

  > Oh look. An abusive jump-to-conclusions that demonstrates a complete
  > ignorance of the facts. How surprising.

Both of those messages were harsh in their tone.  Glenn and Eric,
could you hold back from that?

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: More metaproblem

[Stephen Leake]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Glenn Morris <rgm@gnu.org>:
>> Karl Fogs wrote:
>> 
>> > That site & page are maintained by the FSF -- they're not in the Emacs
>> > tree anywhere.  In other words, whatever the procedures are for
>> > improving the Emacs home page (and creating a developer welcome page),
>> > they are completely different from the procedures for improving the
>> > Emacs code.  So, yay, now I have to learn *two* contribution paths.
>> 
>> The http://www.gnu.org/software/emacs/ Emacs web pages are maintained in
>> CVS.
>
> Oh, holy jumping *fuck*.

-10

Please be more polite.

I'm happy to use CVS as a web publishing platform. As the text you
did not quote said, it is _not_ being used as a CM system.

> And you still wonder why you can't get more help maintaining them?

I have not seen anyone refuse to help maintain them, for any reason.


> CVS, like
> Texinfo and far too many of this project's inheritances from ancient
> times, is a gigantic neon sign that says to new developers WE *LIVE*
> TO INFLICT PROCESS PAIN ON YOU.

No, just that we have limited resources, and there's no reason to change
what ain't broke.

Learning how to publish via CVS is no harder than learning how to
publish by any other means.

> Well, at least I can partly fix this. I'll get with Bob Proulx about
> converting the repo.  

Thanks for volunteering.

> Eventually it should almost certainly move into the source tree, but
> that's pending the big redesign of our documentation structure.

There are legitimate reasons to have separate FSF and Emacs web pages,
so I'm not sure which ones you are talking about here.

-- 
-- Stephe

Re: maintaining FSF Emacs web page

[Stephen Leake]

Karl Fogel <kfogel@red-bean.com> writes:

>>Volunteers are welcome to take similar care of the Emacs Web page.
>>I'm sure they will be most welcome if and when they come.
>
> Hmm, what is the path for such volunteers?
>
> That site & page are maintained by the FSF -- they're not in the Emacs
> tree anywhere.  In other words, whatever the procedures are for
> improving the Emacs home page (and creating a developer welcome page),
> they are completely different from the procedures for improving the
> Emacs code.  So, yay, now I have to learn *two* contribution paths.

One solution to this is to keep the FSF page very short, and have it
refer to a web page or other docs that we do maintain.

Currently, that would be http://www.emacswiki.org/

But that's not under any CM system, and there are at least some
developers here that don't want to use it.

I also work on monotone; their web page (http://www.monotone.ca/) is
a wiki that is automatically synced with a monotone repository, which
can also be edited by "normal" means. I find that very convenient.

Another choice is to simply keep the important docs as formatted text
files in the Emacs git repository, and leave the wiki as supplemental
but not required.

>>Of course we do: etc/CONTRIBUTE.  We just decided to move it to the
>>top-level directory.
>
> It should be a web page.  That's how things work now.

That may be what lots of people are used to, but we get to decide on how
we do things.

If we hear from potential new contributors that they are turned off by
having to read docs in Emacs instead of in a browser, there are several
possible responses:

- Emacs is a browser :)

- Emacs is all about editing files; get used to it

- Ok, maybe we should do more on the web.

> But my hypothesis is that anyone who tried to convert it to web page
> right now would face multiple obstacles, including not just technical
> obstacles but resistance to goal itself.

Yes.

I, for one, _much_ prefer editing text (markup or plain) to editing via
web browsers. I also prefer reading local files; Emacs is _very_ good at
searching and navigating among them (_much_ better than Firefox or
Chrome in a wiki).

I hope you are open to considering such arguments.

> If we could work out the technical details to have a "www/" directory at
> the top level of the Emacs source tree, and have that be where both the
> home page http://www.gnu.org/software/emacs/ *and* soon-to-be-written
> new developer-oriented pages are maintained, would you be in favor of
> that?

That implies that there is also a mechanism that mirrors that directory
to a web host somewhere (as monotone does). 

> (I don't mean volunteer to help, I just mean support the goal or anyway
> not oppose it.)

I would be ok with that, but _only_ if sufficient people step up to
support it, with reasonable hope that they wont disappear after an
initial effort.


-- 
-- Stephe

Re: maintaining FSF Emacs web page

[Karl Fogel]

Stephen Leake <stephen_leake@stephe-leake.org> writes:
>I, for one, _much_ prefer editing text (markup or plain) to editing via
>web browsers. I also prefer reading local files; Emacs is _very_ good at
>searching and navigating among them (_much_ better than Firefox or
>Chrome in a wiki).
>
>I hope you are open to considering such arguments.

Oh, that's all I was ever proposing; no disagreement here.  I was never
proposing *editing* via a web browser.  In a earlier post I gave the
same criteria you give -- I wrote:

  > - Raw source is readable as-is
  >
  > - Has free software tools to generate good HTML
  >   (and we then treat HTML as the default output format)
  >
  > - Markup syntax is not burdensome

>That implies that there is also a mechanism that mirrors that directory
>to a web host somewhere (as monotone does). 

Yes.  This is a pretty typical way of maintaining project web pages: a
post-commit / post-push trigger rebuilds the live web site HTML files.

>I would be ok with that, but _only_ if sufficient people step up to
>support it, with reasonable hope that they wont disappear after an
>initial effort.

Makes sense.  I wish I had time to help with the plumbing parts of this,
which are probably the hard parts (at least at first), but alas I don't.

Best,
-K

Re: maintaining FSF Emacs web page

[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 solution to this is to keep the FSF page very short, and have it
  > refer to a web page or other docs that we do maintain.

  > Currently, that would be http://www.emacswiki.org/

I see no benefit in that, only a problem.

Using CVS is easy, through VC.  Meanwhile, since we don't control the
contents of emacswiki.org, it is not the right good place to publish
the text that we do maintain.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: maintaining FSF Emacs web page

[Alex Schroeder]

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

>   > One solution to this is to keep the FSF page very short, and have it
>   > refer to a web page or other docs that we do maintain.
>   > Currently, that would be http://www.emacswiki.org/
> 
> I see no benefit in that, only a problem.
> 
> Using CVS is easy, through VC.  Meanwhile, since we don't control the
> contents of emacswiki.org, it is not the right good place to publish
> the text that we do maintain.

Is control important? I keep the wiki up and running. I can lock some 
pages and give out passwords if control is important. If the real issue is 
a fear of vandalism and spam, then there seems to be little reason to 
worry: people like me are keeping an eye on Emacs Wiki, keeping it free of 
vandalism and spam.

Re: maintaining FSF Emacs web page

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

  > Is control important?

We want to decide the message we communicate.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: More metaproblem

[Stephen Leake]

Karl Fogel <kfogel@red-bean.com> writes:

> My request is simple and specific:
>
> I'm asking the biggest contributors to Emacs (you, among others) to
>
>   - Not oppose a revamp of the contributor documentation along the lines
>     I described;

(refering to moving contributor docs to the web)

I'm not at all convinced that would lower any barriers.

The only problems around contributing I've actually seen mentioned on
this list are lack of documentation for contributors, or lack of
awareness of such documentation.

It turns out there _is_ documentation, in several files in the Emacs
repository.

It needs some cleaning up, which I'm working on (see my recent commits).

More importantly, it needs _advertising_.

Whenever someone on this list says "please follow the standard", they
should _also_ mention ./CONTRIBUTORS, or one of the more detailed files
in admin/notes. That will get people used to refering to those files,
raise awareness of them, and encourage people to keep them up to date.

We also need to mention it on the FSF web page (I hope to find out how
to accomplish that). And on the wiki, if we can find the appropriate
places.


Simply moving the docs to a web page will not help with awareness.

>   - Not oppose using a modern bug tracker -- one that supports email
>     manipulation but *also* supports manipulation via a web browser.
>     (Redmine, for example.)

I have on occasion wished I could manipulate the bug tracker via the
web. But that is not a barrier to contributing for me; the email
interface is simple and well documented.

-- 
-- Stephe

RE: More metaproblem

[Drew Adams]

> Whenever someone on this list says "please follow the standard",
> they should _also_ mention ./CONTRIBUTORS, or one of the more
> detailed files in admin/notes. That will get people used to
> refering to those files, raise awareness of them, and encourage
> people to keep them up to date.

Yes.

That's the same kind of thing we do for user questions about
Emacs Lisp coding conventions etc.: (a) answer the question,
but also (b) refer them to the relevant doc about it in the
manuals.

Would it hurt to put the information you refer to, which is
aimed at Emacs contributors, into the Emacs manual, as a
separate section?  A priori, that makes sense to me, but then
I don't see a logical separation between Emacs users and Emacs
contributors anyway.

IMO, it does not matter whether such info is detailed, boring,
internal stuff.  It would still be good to move it from other
files to the official doc, and give it the proper love that
such doc requires.

I think that doing this might have these benefits:

1. Put more of an accent on it, for everyone.  The content
   and form would need to be clear and complete, and kept
   up to date, but that should be the case anyway.

2. Let users know that they can contribute, and just
   what's involved (yes, in detail).

3. Encourage people to reference it, as they do now for
   questions about key-binding conventions etc.

And I do mean "move", not copy.  There should be a single
place where such info resides and is kept up to date.  My
thought is that that place should be the Emacs manual.

Just a thought.  Disclaimer: I'm not familiar with the
info I'm conjecturing about.  It just sounds to me like
this kind of info belongs in the manual, even if it is
not considered useful to the average Emacs user.

If you think that such info really does not belong in the
Emacs manual, then perhaps a separate manual for it makes
sense.

Re: More metaproblem

[Stephen Leake]

Drew Adams <drew.adams@oracle.com> writes:

>> Whenever someone on this list says "please follow the standard",
>> they should _also_ mention ./CONTRIBUTORS, or one of the more
>> detailed files in admin/notes. That will get people used to
>> refering to those files, raise awareness of them, and encourage
>> people to keep them up to date.
>
> Yes.
>
> That's the same kind of thing we do for user questions about
> Emacs Lisp coding conventions etc.: (a) answer the question,
> but also (b) refer them to the relevant doc about it in the
> manuals.
>
> Would it hurt to put the information you refer to, which is
> aimed at Emacs contributors, into the Emacs manual, as a
> separate section?  

There is such a section; (info "(emacs)Contributing). It just references
emacs-devel@gnu.org, http://savannah.gnu.org/projects/emacs/ and
etc/CONTRIBUTE.

I'll fix the latter reference.

As you say below, I don't think we should duplicate the information in
the two files, but I would not be averse to moving the info into the
manual, and leaving ./CONTRIBUTE as a reference. That would allow the
links I just added to ./CONTRIBUTE to be more clickable, since the
texinfo is pushed to the web at
http://www.gnu.org/software/emacs/manual/emacs.html, and urls in Emacs
info also bring up a web browser.

> A priori, that makes sense to me, but then
> I don't see a logical separation between Emacs users and Emacs
> contributors anyway.

I certainly moved gradually from user to contributor.

> IMO, it does not matter whether such info is detailed, boring,
> internal stuff.  It would still be good to move it from other
> files to the official doc, and give it the proper love that
> such doc requires.

I consider ./CONTRIBUTE to _be_ "official doc". Why do you think
otherwise?

> I think that doing this might have these benefits:
>
> 1. Put more of an accent on it, for everyone.  

That comes from _advertising_, not from format.

It makes it a little more accessible. But ./CONTRIBUTE is on the web
now: http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE

I just did a Google search for "Emacs contribute". The first two links
are:

http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html

    Excellent! I need to understand exactly how/when that is updated.

http://www.gnu.org/software/emacs/CONTRIBUTE

    a currently out of date copy; again, I need to understand exactly
    how/when that is updated.


followed by other not-so-relevant links.

How much more accessible does it need to be?

>    The content
>    and form would need to be clear and complete, 

That comes from editing skill (I have yet to hear if my edits are
acceptable). 

>    and kept up to date, but that should be the case anyway.

That comes from developer attention, which is mostly influenced by
advertising.

> 2. Let users know that they can contribute, 

That is certainly implied by the Free Software nature of Emacs.

Although the climate of other developers is a big factor once people
consider contributing.

> and just what's involved (yes, in detail).

I don't see why the format affects this.

Some have suggested that the current crop of potential contributors are
more comfortable reading web stuff than file stuff; do you agree with
that? 

> 3. Encourage people to reference it, as they do now for
>    questions about key-binding conventions etc.

I don't see why
http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
would be a better/simpler/easier reference than ./CONTRIBUTE.

If you need to read ./CONTRIBUTE, you already have the source on your
disk.

Exception: the short list of "other ways to contribute" should be on a
web page somewhere.

> Just a thought.  Disclaimer: I'm not familiar with the
> info I'm conjecturing about.  

Please take a moment to read it; it's only 339 lines, about 1/3 white
space. 

-- 
-- Stephe

RE: More metaproblem

[Drew Adams]

> > Would it hurt to put the information you refer to, which is
> > aimed at Emacs contributors, into the Emacs manual, as a
> > separate section?
> 
> There is such a section; (info "(emacs)Contributing). It just
> references
> emacs-devel@gnu.org, http://savannah.gnu.org/projects/emacs/ and
> etc/CONTRIBUTE.

Yes, I know.  That is not at all what I meant (and said), which was:

 "put the information you refer to, which is aimed at Emacs
  contributors, into the Emacs manual"

It's not about providing a reference to some local file or a
mailing list.  It's about *moving* the complete information to
the manual (the Emacs manual or a new, dedicated manual).

> As you say below, I don't think we should duplicate the information
> in the two files, but I would not be averse to moving the info
> into the manual, and leaving ./CONTRIBUTE as a reference.

If you agree that we should not duplicate the information, then
why would you leave ./CONTRIBUTE?  That's duplication, no?

The point is to let the manual be the single source of truth.
It is a mistake (asking for trouble), IMO, to have two or more
such sources.

But I'm probably missing something that you are trying to say here.

> > IMO, it does not matter whether such info is detailed, boring,
> > internal stuff.  It would still be good to move it from other
> > files to the official doc, and give it the proper love that
> > such doc requires.
> 
> I consider ./CONTRIBUTE to _be_ "official doc". Why do you think
> otherwise?

It is official.  But it is not in Info form, and it deserves
to be (users deserve it to be).  That's what I meant.  Perhaps
I should have said "move it from other files to where
the rest of the official is presented to users: in Info."

(And please don't bother to nitpick about there being still
other official doc that is also not in Info form.  That can
be ignored for now, or it can in turn be considered as a
candidate for moving to Info.)

> > I think that doing this might have these benefits:
> >
> > 1. Put more of an accent on it, for everyone.
> 
> That comes from _advertising_, not from format.
> 
> It makes it a little more accessible. But ./CONTRIBUTE is on the web
> now: http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE

On the web is not in Info.  (That's in fact part of the other,
parallel discussion initiated by ESR.  *Web doc does not
sufficient Emacs doc make.*)

> I just did a Google search for "Emacs contribute"...
> How much more accessible does it need to be?

My (personal) answer is that it should be in Info, not just
on the web somewhere, and not just in a file in the Emacs
distribution somewhere, and not just as a pointer to a mailing
list somewhere.

Imagine if all of the important Emacs documentation had only
the form/accessibility you are referring to.  Would you be
content to replace the Emacs manual (Info) with a link to a
web page or a local plain-text file?  I wouldn't want that.

What's good for the Emacs-manual gander is good for the
CONTRIBUTE goose.  Make that information into a manual (Info)
or part of the Emacs manual. 

> > The content and form would need to be clear and complete,
> 
> That comes from editing skill (I have yet to hear if my edits are
> acceptable).

By that I meant also that ALL of the information about
contributing should be moved to Info.  A lot of work goes
into making sure that the information in the manuals is clear
and complete.  I can't speak to whether this is also true for
other, non-Info kinds of "official" Emacs doc.  If it is, so
much the better - just move it to Info.

> > 2. Let users know that they can contribute,
> 
> That is certainly implied by the Free Software nature of Emacs.

I think you are missing the point of my suggestion.  Putting this
information in the Emacs manual would make it much more visible
to "ordinary" users (and much more navigable).  (IMHO)

Both of my points #1 and #2 are introduced by this phrase:

  "I think that doing this might have these benefits:"

where "doing this" refers to moving such information completely
to the Emacs manual (to Info form, at least, with mirroring on
the web).

> > and just what's involved (yes, in detail).
> 
> I don't see why the format affects this.

Again, the point was to move the complete, detailed information
to the manual (Info format), NOT to simply have a reference from
the manual, as now.  The difference is whether the details are
in Info format or not, so yes, the format "affects this" - it's
all about the format (and location).

> Some have suggested that the current crop of potential contributors
> are more comfortable reading web stuff than file stuff; do you agree
> with that?

Probably.  But it doesn't matter whether I agree, or care.
My point is that this information belongs with the rest of the
Emacs information for users: in the manual.

It is of course important that the manuals be mirrored on the
web.  And as I (and others) made clear in the sister thread,
web access to the information is necessary but not sufficient.
Manuals on the web do not provide the features that manuals
provide *in Emacs*, from Info.  Not even close.

> > 3. Encourage people to reference it, as they do now for
> >    questions about key-binding conventions etc.
> 
> I don't see why
> http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributin
> g.html would be a better/simpler/easier reference than ./CONTRIBUTE.

No one said it would be.  I think you have not understood my
suggestion well enough.

> If you need to read ./CONTRIBUTE, you already have the source on
> your disk.

Having the information on your disk is not enough.  Having it on
the web is not enough.  It should be available from Emacs, in
Info form.  It should be integrated with the other user doc.

> Exception: the short list of "other ways to contribute" should be on
> a web page somewhere.
> 
> > Just a thought.  Disclaimer: I'm not familiar with the
> > info I'm conjecturing about.
> 
> Please take a moment to read it; it's only 339 lines, about 1/3
> white space.

I'm talking also about details that explain conventions and
methods used for developing/maintaining Emacs.

(And (why not?) detailed information about Emacs internals -
such as the doc that exists for XEmacs.  But this is not
necessarily part of what I proposed in the immediate.)

It doesn't matter what I understand or think about the particular
detailed information.  Information about how to contribute and
develop Emacs should be available to users in Info form, IMO.
That's all.

I have no informed opinion about whether all of it belongs in
the Emacs manual or it should have its own, dedicated manual.
But *Info it should be* - and mirrored on the web in the same
way as the Emacs and Elisp manuals.

Re: More metaproblem

[Stephen Leake]

Drew Adams <drew.adams@oracle.com> writes:

>> As you say below, I don't think we should duplicate the information
>> in the two files, but I would not be averse to moving the info
>> into the manual, and leaving ./CONTRIBUTE as a reference.
>
> If you agree that we should not duplicate the information, then
> why would you leave ./CONTRIBUTE?  That's duplication, no?

I meant "change the content of ./CONTRIBUTE to refer to the manual". So
people who look for a file CONTRIBUTE will still find the information.

>> > IMO, it does not matter whether such info is detailed, boring,
>> > internal stuff.  It would still be good to move it from other
>> > files to the official doc, and give it the proper love that
>> > such doc requires.
>> 
>> I consider ./CONTRIBUTE to _be_ "official doc". Why do you think
>> otherwise?
>
> It is official.  But it is not in Info form, and it deserves
> to be (users deserve it to be).  That's what I meant.  Perhaps
> I should have said "move it from other files to where
> the rest of the official is presented to users: in Info."

But the information in ./CONTRIBUTE is _not_ for users; it is for
developers. 

> My (personal) answer is that it should be in Info, not just
> on the web somewhere, and not just in a file in the Emacs
> distribution somewhere, and not just as a pointer to a mailing
> list somewhere.
>
> Imagine if all of the important Emacs documentation had only
> the form/accessibility you are referring to.  Would you be
> content to replace the Emacs manual (Info) with a link to a
> web page or a local plain-text file?  I wouldn't want that.

As an Emacs _user_, I agree, I want the Emacs user manual in Info.

As an Emacs _developer_, it makes some sense to use Info, but it should
be in a separate manual (as you allow below).

Texinfo is _almost_ as easy to edit as plain text, but there is some
cost. What is the actual gain?

You have to know the file is there, or know how to look for it. That's
why is was move up from etc/; easier to find. It's also why it's
referenced from the Emacs manual.

However, I agree an "Emacs developers manual" in the top-level Info menu
would be even easier to find.

Whether it is in info or plain text (or some other format) is a
secondary issue.

We are only talking about 330 lines, that have been in plain text for a
long time. Is there really a big reason to change?

I hear you saying that you prefer Info. I'm still not clear _why_ you
prefer Info, for this specific information.

I think you would reply "everyone that uses Emacs simply _expects_ all
documentation to be in Info". I can see why that might be true. I fall
back on "developers are not everyone" and "having different conventions
for developers and users makes it clearer which is which". Not very
strong points, I'll admit.

For me, it really comes down to ease of maintenance and use. I find the
plain text format slightly easier to both maintain and use (partly
because I have a C-F12 function that does 'find-file-or-url-at-point').
But if someone else wants to put in the time to move it to texinfo, I
won't object.

If the file gets much longer, I would want to move it to texinfo.

>> > 2. Let users know that they can contribute,
>> 
>> That is certainly implied by the Free Software nature of Emacs.
>
> I think you are missing the point of my suggestion.  Putting this
> information in the Emacs manual would make it much more visible
> to "ordinary" users (and much more navigable).  (IMHO)

(info "(emacs)Contributing")

Feel free to submit patches.

>> > 3. Encourage people to reference it, as they do now for
>> >    questions about key-binding conventions etc.
>> 
>> I don't see why
>> http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributin
>> g.html would be a better/simpler/easier reference than ./CONTRIBUTE.
>
> No one said it would be.  I think you have not understood my
> suggestion well enough.

You said "encourage people to reference it".

Hmm, since we are talking about info, the proper reference would be
(info "(emacs)Contributing"). Much better.

If it's a (slightly) longer string, that (slightly) discourages me from
referencing it.

Perhaps if everyone expects all docs to be in Info, you would feel
reluctant to reference something that is not in Info? That makes some
sense. 

>> If you need to read ./CONTRIBUTE, you already have the source on
>> your disk.
>
> Having the information on your disk is not enough.  Having it on
> the web is not enough.  It should be available from Emacs, 

It is, if it is on your disk.

> in Info form.

That is the issue under discussion.


>> Exception: the short list of "other ways to contribute" should be on
>> a web page somewhere.
>> 
>> > Just a thought.  Disclaimer: I'm not familiar with the
>> > info I'm conjecturing about.
>> 
>> Please take a moment to read it; it's only 339 lines, about 1/3
>> white space.
>
> I'm talking also about details that explain conventions and
> methods used for developing/maintaining Emacs.

Where are they? The ones I'm aware of are referenced from the current
trunk version of ./CONTRIBUTE. I am deliberately ignoring the wiki.

-- 
-- Stephe

RE: More metaproblem

[Drew Adams]

> I meant "change the content of ./CONTRIBUTE to refer to the manual".
> So people who look for a file CONTRIBUTE will still find the
> information.

Good.

> >> > IMO, it does not matter whether such info is detailed, boring,
> >> > internal stuff.  It would still be good to move it from other
> >> > files to the official doc, and give it the proper love that
> >> > such doc requires.
> >>
> >> I consider ./CONTRIBUTE to _be_ "official doc". Why do you think
> >> otherwise?
> >
> > It is official.  But it is not in Info form, and it deserves
> > to be (users deserve it to be).  That's what I meant.  Perhaps
> > I should have said "move it from other files to where
> > the rest of the official is presented to users: in Info."
> 
> But the information in ./CONTRIBUTE is _not_ for users; it is for
> developers.

Developers are users.  Some users are developers.  There is no
reason not to provide such info for users in general (IMHO).
Especially if we want to encourage users to contribute.

> > My (personal) answer is that it should be in Info, not just
> > on the web somewhere, and not just in a file in the Emacs
> > distribution somewhere, and not just as a pointer to a mailing
> > list somewhere.
> >
> > Imagine if all of the important Emacs documentation had only
> > the form/accessibility you are referring to.  Would you be
> > content to replace the Emacs manual (Info) with a link to a
> > web page or a local plain-text file?  I wouldn't want that.
> 
> As an Emacs _user_, I agree, I want the Emacs user manual in Info.
> As an Emacs _developer_, it makes some sense to use Info, but it
> should be in a separate manual (as you allow below).

I don't have a problem with that.  My preference would probably
be to add it to the Emacs manual, a priori.  But I haven't heard
any argument to convince me that it should be in a separate
manual - perhaps I would change my mind if I did.

The argument that users are different from developers makes
little sense to me.  Might as well say that because some users
don't use the Calendar we should move all of the Calendar stuff
out of the Emacs manual into a separate one.  Or all of the
International stuff.  Or all of the Mail stuff.

Now there's a good candidate!  Move all of the Sending Mail,
Rmail, and Gnus stuff to a separate manual.  Yes, please. ;-)

> Texinfo is _almost_ as easy to edit as plain text, but there is some
> cost. What is the actual gain?

What is the gain of having this information in Info form?  See
my previous messages.  Should be a no-brainer.  And the gain
of having it in the Emacs manual is to invite Emacs users to
consider contributing, and how to do so.

> You have to know the file is there, or know how to look for it.

That's another argument for moving the information to the manual.

> That's why is was move up from etc/; easier to find. It's also
> why it's referenced from the Emacs manual.

Why just reference it when you can include it?  Why use a
plain-text file when you can use Info?  And it will automatically
end up as HTML on the web, in the same location as the other
Emacs information.

> However, I agree an "Emacs developers manual" in the top-level Info
> menu would be even easier to find.
> 
> Whether it is in info or plain text (or some other format) is a
> secondary issue.

OK.  I don't care which is considered primary and which secondary.
To me, both are good ideas: move it to Info, and put its node
link in the top-level `dir' menu or the top-level menu of the
Emacs manual.

> We are only talking about 330 lines, that have been in plain text
> for a long time. Is there really a big reason to change?

I imagine there are more than 330 lines for all of the "internal"
developer/contributor information.  At least I hope there are.

XEmacs has a nice internals manual, IIUC.  Doesn't GNU Emacs
deserve similar?

> I hear you saying that you prefer Info. I'm still not clear
> _why_ you prefer Info, for this specific information.

It is information for Emacs users on how to help develop Emacs.
We have some such info in the Elisp manual (the various
"conventions" nodes).  I think that other "developer" info
deserves a similar treatment, whatever manual it ends up in.

> I think you would reply "everyone that uses Emacs simply
> _expects_ all documentation to be in Info". 

I don't know whether they do.  But if you put it there they
will. ;-)  And why shouldn't they?

> I can see why that might be true. I fall back on "developers
> are not everyone" 

Not everyone uses Gnus, either.  Every developer is a user.
Some users contribute to development.  Some do so by filing
bugs.  Some by fixing bugs.  Some by testing bug fixes.
Some by maintaining releases & distribution.  Some by coming
up with new features (think how many features were originally
developed by users, in 3rd-party libraries - Emacs itself is
full of them).  

> and "having different conventions for developers and users
> makes it clearer which is which". Not very strong points,
> I'll admit.

It can only be clear in the sense of roles.  Now you wear
your user hat; now you wear your developer hat.  But yes,
the developer-oriented doc should be written with an Emacs
developer orientation, of course.  Just as the Elisp doc
is written with an Elisp user orientation.

> For me, it really comes down to ease of maintenance and use.

Use, fine.  Maintenance should not be a primary concern.
This is no different from maintaining and using any manual.

> I find the plain text format slightly easier to both maintain
> and use (partly because I have a C-F12 function that does
> 'find-file-or-url-at-point').  But if someone else wants to
> put in the time to move it to texinfo, I won't object.

I hope someone does.  I think Emacs would benefit.  Just
one opinion.

> > I'm talking also about details that explain conventions and
> > methods used for developing/maintaining Emacs.
> 
> Where are they? The ones I'm aware of are referenced from the
> current trunk version of ./CONTRIBUTE. I am deliberately
> ignoring the wiki.

Sorry; I don't know.  But if they were in the manual I would
be able to tell you.

Re: More metaproblem

[Eli Zaretskii]

> Date: Sun, 7 Dec 2014 15:00:38 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> > > It is official.  But it is not in Info form, and it deserves
> > > to be (users deserve it to be).  That's what I meant.  Perhaps
> > > I should have said "move it from other files to where
> > > the rest of the official is presented to users: in Info."
> > 
> > But the information in ./CONTRIBUTE is _not_ for users; it is for
> > developers.
> 
> Developers are users.  Some users are developers.  There is no
> reason not to provide such info for users in general (IMHO).
> Especially if we want to encourage users to contribute.

I suggest to put this issue on hold for a moment.  We don't yet have
the contents of that file in its final form.  I suggest to wait until
we do, and decide whether to move it into some manual later.  There's
no rush.

Re: More metaproblem

[Przemysław Wojnowski]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi.

IMHO if you want to know what should be in CONTRIBUTE and/or Info doc just
look at some of successful Github projects. A common thing is to have
description of:

1. How to build a project from source
(http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/ is a
good start).

2. How to run (automated) tests - IMHO a must if a project want to be
perceived as modern by young developers. Without automated tests young devs
will think that project stuck in 80's. Moreover, automated tests enable
refactoring, which is standard now. Writing tests is very good starting point
for new devs, because one can learn about the system and make it more
resistant to unintended changes at the same time.

3. What are coding conventions, if are not language-wide (K&R for C?, what
about elisp?). How about clean code
(http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)?
Can split a long function into couple cohesive ones or you don't care about
readability?

4. GH has fantastic pull requests that make contribution easier to do and less
public, which is encouraging. Here, sending patches to the list, is
technically harder (less of a problem) and discouraging (send a patch and
watch 100 emails humiliating you :-) ).

If you are an agile developer, then just take it as a feedback. If you are
not, the please ignore. Hope it helps.

Cheers,
Przemyslaw

W dniu 07.12.2014 o 23:07, Stephen Leake pisze:
[...]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBAgAGBQJUhha2AAoJEC3CE3LuBFUoNF0P+wZdvpxXkdLeFSqBPIWFbZkR
QobU1T805/cFoyOa9kFb43zL860QeYfboSVumdqhhDqbB4KftYyf36jajksvZ71F
yp2H+p+IBgy9xw+10pT6+X76GIe1h9ckvCTGKPMPW1IbSBpZnY6aPr4TMK3wgUh0
YdkzzIcC4btijaMhr9+LWfZWgWdK2ZKKMvJuI7r82ITDwugRH6Ls5zi/fLGKrIp2
jUXfuilCRd799yvDfTPotsX9rrdIl+c8rYkAUpeeVpnnvtTKUoyDk4UQhapC4TN2
H0B9bxt1w4gRGDQrmwz7GW+nJrytyANZSsirwFCOlHw1bpym8ckqz1+BEgCHJOjp
hnfItQXGkz+Vz9oU3HZEwdPc2dYqiU1ZZwexDLIRszJ74joyj4aEuT5y5eHY26Hk
nkUzSv8srneTfPJ75gIzPR6hl2H82fdCYXGRMAizfirCPsazhXc9OK5+1ljW8JnQ
c1lDK0gJY4cE2H9hd0gUIFIYOwZ3u/m7Sc8UQLLaDgYqR9+1S5rhQ7g/4axh5h9h
E5BpkvUlFqfG/+8JxKTpkYDaS9Ik8VVWMVGw43OF8J+LahU8PEzL2dMrwZLC+ItD
3tJW/QVUmU4OIq6uzy51mAhi+9cnBjPFTydhzoqZirSQbnjqvFb/FOrNHaCZTh6r
AmVQ9TYlhqx+5SNQDyBY
=KnDG
-----END PGP SIGNATURE-----

Re: More metaproblem

[Eli Zaretskii]

> Date: Mon, 08 Dec 2014 22:23:10 +0100
> From: Przemysław Wojnowski <esperanto@cumego.com>
> 
> 1. How to build a project from source
> (http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/ is a
> good start).

Is it different from INSTALL.REPO in the Emacs tree?

> 2. How to run (automated) tests - IMHO a must if a project want to be
> perceived as modern by young developers. Without automated tests young devs
> will think that project stuck in 80's. Moreover, automated tests enable
> refactoring, which is standard now. Writing tests is very good starting point
> for new devs, because one can learn about the system and make it more
> resistant to unintended changes at the same time.

Did you look in tests/ ?

> 4. GH has fantastic pull requests that make contribution easier to do and less
> public, which is encouraging. Here, sending patches to the list, is
> technically harder (less of a problem) and discouraging (send a patch and
> watch 100 emails humiliating you :-) ).

When did you see 100 humiliating emails in response to a patch?  I
think you have some other project/forum in mind.

Re: More metaproblem

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Mon, 08 Dec 2014 22:23:10 +0100
>> From: Przemysław Wojnowski <esperanto@cumego.com>
>> 
>> 1. How to build a project from source
>> (http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/ is a
>> good start).
>
> Is it different from INSTALL.REPO in the Emacs tree?

INSTALL.REPO is mentioned in CONTRIBUTE.

>> 2. How to run (automated) tests - IMHO a must if a project want to be
>> perceived as modern by young developers. Without automated tests young devs
>> will think that project stuck in 80's. Moreover, automated tests enable
>> refactoring, which is standard now. Writing tests is very good starting point
>> for new devs, because one can learn about the system and make it more
>> resistant to unintended changes at the same time.
>
> Did you look in tests/ ?

We should mention that in the Emacs Developer's Manual (new name for
CONTRIBUTE).

-- 
-- Stephe

Re: More metaproblem

[Przemysław Wojnowski]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

W dniu 09.12.2014 o 17:54, Eli Zaretskii pisze:
>> Date: Mon, 08 Dec 2014 22:23:10 +0100 From: Przemysław Wojnowski
>> <esperanto@cumego.com>
>> 
>> 1. How to build a project from source 
>> (http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/ is
>> a good start).
> 
> Is it different from INSTALL.REPO in the Emacs tree?
A bit. The blog has also good hints on installing deps:
sudo apt-get build-dep emacs24

>> 2. How to run (automated) tests - IMHO a must if a project want to be 
>> perceived as modern by young developers. Without automated tests young
>> devs will think that project stuck in 80's. Moreover, automated tests
>> enable refactoring, which is standard now. Writing tests is very good
>> starting point for new devs, because one can learn about the system and
>> make it more resistant to unintended changes at the same time.
> 
> Did you look in tests/ ?
Yes. It contains automated tests for elisp and IMHO instructions for new devs
should tell how to work with it.
What about tests for C code? IMHO even one test would be helpful, just to show
which test library should be used and how to run those tests.
AFAIK writing tests is standard way to join a project and gain knowledge about it.

>> 4. GH has fantastic pull requests that make contribution easier to do and
>> less public, which is encouraging. Here, sending patches to the list, is 
>> technically harder (less of a problem) and discouraging (send a patch
>> and watch 100 emails humiliating you :-) ).
> 
> When did you see 100 humiliating emails in response to a patch?  I think
> you have some other project/forum in mind.
It was just a metaphorical expression. I meant that it's discouraging to send
a patch seeing people fighting in other threads. Maybe for patches it's a bit
different - sorry, don't have time reading all emails on the list. :-|

Thanks for response,
Przemyslaw
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBAgAGBQJUiKMJAAoJEC3CE3LuBFUoUNkQAIB57tQ8X3R3anqWjHQWIOLc
6AK0uD+MklOQm6TNz9oSau7p9BeNJsVyz4nBVBHyjmV3tScZPzs5H7TM2zEr0o24
UIijVIgWiyMc7gPkalReV8UwikB0h6BieZxqSlqDJT2waHPVvxrD3JOyGXEzD+ci
LLrBtiH/kcXdEYkkZZEVMPp+jIY6x050kZuALt/QiGGBxZM6MvvC47EDPpXL6xDH
hua7Epwdb+eh+nvwVaA/1uLvXS02GUeRigmygX1sXhYBrTuftrDMN9UkE5PhPIxx
ghm0eRk9qZ2Z7bMPiO914ikER6grBC7CvUDeoGPl9GbO9262dw3GleSU8yjdP3Lf
068HNQ5CKDDu3ieO/+PaT2a7BZqkWDg8zs9NhCNLNiKa1GE5JlAJBSh11Pw8jueR
mtBHhC0wJ5626LEzIRxanh88lT4LiqFiYyHr0nxTJsPNA9L9VdXYouj15eSWeUHH
AGt9puKuNxwmbC/0reAK1T8WMdUqb4uJCg673HY5pSy2qaF0wicEQBjX6ztCvgZa
CLhYbDUy51cGfldbaHleZxE90u0A7V1dzQmfCxYNaVOABjW3RIo+ebJlLMHa/DbX
eJGm/NDtuL75EV7mNmzpTF9LNDHPKbbGSxEqLr1IevHot9uGio503fGMZgcYaP7X
4wMwMoneeHbvckeQlp2x
=mnyd
-----END PGP SIGNATURE-----

Re: More metaproblem

[Eli Zaretskii]

> Date: Wed, 10 Dec 2014 20:46:25 +0100
> From: Przemysław Wojnowski <esperanto@cumego.com>
> CC: emacs-devel@gnu.org
> 
> > Did you look in tests/ ?
> Yes. It contains automated tests for elisp and IMHO instructions for new devs
> should tell how to work with it.
> What about tests for C code?

Some of the tests test that as well.  There's no difference, really.

Re: More metaproblem

[Stefan Monnier]

> Some of the tests test that as well.  There's no difference, really.

There is.  Currently, we don't have any C-level tests, so if you want to
test C code, you have to do it via Elisp-level tests, which of course
only works if you can reliably trigger the C code from Elisp.

It would be good to start adding C-level tests.


        Stefan

Re: More metaproblem

[Przemysław Wojnowski]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

W dniu 08.12.2014 o 22:23, Przemysław Wojnowski pisze:
> Hi.
[...]
> 3. What are coding conventions, if are not language-wide (K&R for C?, what 
> about elisp?).
Coding standards are mentioned in CONTRIBUTE. Sorry, my bad.
I've found also the following:
https://github.com/bbatsov/emacs-lisp-style-guide
But don't know if you use it.

> How about clean code 
> (http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)?
>
> 
Can split a long function into couple cohesive ones or you don't care about
> readability?
What about this one? Is refactoring to small, cohesive functions accepted?
For example function abbrev--before-point from the first elisp file abbrev.el
is quite big and I can imagine it's hard to test automatically. It could be
split into couple smaller ones on single level of abstraction. Such functions
would be easier to test and understand.

Cheers,
Przemyslaw
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBAgAGBQJUiKh/AAoJEC3CE3LuBFUoHlkQAI1uB3u1g/S/fPD7dZIQaeEU
bRw6UbgmgFQJO+V2RJhkh0T+mfTvXUX9GoLVcVEgOdh7QBF435svgW4OXQt7S6tH
pXmXNhBWO7cqiKeoLyzJp3Il7E5mdvaqREGnxeuXQ0KBgipWW06/24U4oprudF6a
ntHjNyfSGlq8/hjR9uURQmNDvT5WS4FE3XtmOw+q0pWpnxh01eNHaepFXQY5qjOK
6MwhauveL5QmvMXbEIu7yYc+MYbWHscr1pRYBMjrM3GWJDjX0C/inriWiIlrZqXQ
cxq5jWXEh0wBEG3P89RCr3ppfgtwuHq3zZJNERJDrOR2fmtSw+vQXnD/8ds8Yw8Y
k9zkIR6H/rD8NVUMSlFzXGeDuA0sr4t/XH9l9cMt0sedkZ2B3/WUzYTRENmdJAro
mkoCZLTLjl0qP5YezRm3ONRwlwp8EVWLBSgC2AFqxP0/boMqIZ27NRrfoT8ohi/9
iWWKPjbZRsqC9xcvLFT+UxUJo/vNyFKBtxHKyxLB3M2K9jmCbQYZDRTAdj1BjmPj
mg+VtUDaEAmgiejHPh0ZCVNig+DCV6xBC6Klv3b9c0csXZgjKBFqgyb1PTKzlMOM
Y8vTaRSwONHTHv6uoY2FVHWS67TGYmjLpUT+VWDR+5L0PIFWwexEFH6ooUs2nT/Y
KK2Af4FdBQOevB0JS1lo
=z/B5
-----END PGP SIGNATURE-----

Re: More metaproblem

[Stefan Monnier]

> What about this one? Is refactoring to small, cohesive functions
> accepted?  For example function abbrev--before-point from the first
> elisp file abbrev.el is quite big and I can imagine it's hard to test
> automatically.  It could be split into couple smaller ones on single
> level of abstraction.  Such functions would be easier to test
> and understand.

Indeed, we have a good number of functions that are too large for
good taste.  I generally like breaking them up when I find a way to do
it cleanly.


        Stefan

Re: More metaproblem

[Stephen Leake]

Karl Fogel <kfogel@red-bean.com> writes:

> What most projects do is have a development web page. linked to from
> their main user-facing web page.  

Emacs was around long before "web pages". It has been slow to embrace
web pages, because it already has a culture that works well without
them.

Perhaps that needs to change to attract new blood, but I'm not sure.
Emacs has a _very_ different feel than "typical" development
environments; using a unique development environment for creating Emacs
can ensure that is maintained.

> The development page organizes all this stuff and provides links to
> source code repository, dev guidelines & documentation, etc.
>
> For Emacs, the main web page is http://www.gnu.org/software/emacs/.
>
> It links to two possible candidates for the "developer page":
>
>   https://savannah.gnu.org/projects/emacs
>   https://savannah.gnu.org/bzr/?group=emacs
>
> But neither of those automatically-generated pages provides what a real
> development web page provides.  Instead they just tell you how to get
> the development sources and where the mailing lists are.  They don't
> tell you to look in admin/notes/ (for example).

I agree this could be improved; it should have a "Contributing" section,
which should point to the current documentation.

What is the mechanism for editing that web page?

>> Feel free to contribute the missing documentation, and thanks in
>> advance.
>
> It's not just a matter of contributing documentation.  We don't even
> *have a place to put such documentation* right now.

As others have pointed out, we do have such a place, but most people are
not aware of it. That needs to change, and I'm working on implementing
the changes suggested so far.


-- 
-- Stephe

Re: More metaproblem

[Stefan Monnier]

>> https://savannah.gnu.org/projects/emacs
>> https://savannah.gnu.org/bzr/?group=emacs
[...]
> What is the mechanism for editing that web page?

I think the second is fully-automatically generated.
The first is under control of the project admins.  The current source
is:

    Emacs is the extensible, customizable, self-documenting real-time
    display editor.
    
    For information about Emacs, visit our
    [http://www.gnu.org/software/emacs/ webpage].  The development
    sources are hosted on Savannah, via Git for the main source and for
    GNU ELPA.
    
    You can access the main repository with
    
    +verbatim+
    git clone -b master git://git.sv.gnu.org/emacs.git
    -verbatim-
    or
    +verbatim+
    git clone -b emacs-24 git://git.sv.gnu.org/emacs.git
    -verbatim-
    
    Where "emacs-24" is the recommended branch if you want to help us
    test&debug the code before the next release.  "master" is if you're
    actively working on Emacs's own code.
    
    You can access the ELPA repository with (see the README file in
    there for how to get the "external" packages).
    
    +verbatim+
    git clone git://git.sv.gnu.org/emacs/elpa
    -verbatim-
    
    For developer access,
    [http://www.emacswiki.org/emacs/GitForEmacsDevs read these
    instructions].

If you want to send me an update, I can install it.

> As others have pointed out, we do have such a place, but most people are
> not aware of it. That needs to change, and I'm working on implementing
> the changes suggested so far.

Thank you,


        Stefan

Re: More metaproblem

[Karl Fogel]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>If you want to send me an update, I can install it.

Thank you, Stefan.

But having to send an update through one particular person is
sub-optimal in a multi-contributor free software project.  Imagine if it
were like that with the code.

Can we get a situation where committers can change that documentation
just as they would edit any other documentation?  (We might have
*social* controls on editing the front page -- that's fine.  I'm just
saying that a commit mechanism that involves a gateway human is not a
good long-term strategy.)

Best,
-K

Re: More metaproblem

[Stefan Monnier]

>> If you want to send me an update, I can install it.
> Thank you, Stefan.
> But having to send an update through one particular person is
> sub-optimal in a multi-contributor free software project.

We're only talking about the entry "project page" on Savannah (and it's
not even the whole page).  It's has to stay very short since the main
purpose of this page is to give you access to the other things on the page.
So there's not much room for lots of contributions and frequent
changes, really.  We can put a few well chosen links to web-pages which
can then change much more freely.

> Can we get a situation where committers can change that documentation
> just as they would edit any other documentation?

You'd have to take that up with the Savannah hackers, but it seems
highly unlikely.


        Stefan

Re: More metaproblem

[Karl Fogel]

Stephen Leake <stephen_leake@stephe-leake.org> writes:
>> It's not just a matter of contributing documentation.  We don't even
>> *have a place to put such documentation* right now.
>
>As others have pointed out, we do have such a place, but most people are
>not aware of it. That needs to change, and I'm working on implementing
>the changes suggested so far.

Bravo to you!  Thank you.

I think a web page as the gateway is important, though:

There needs to be place where a developer *who has not yet decided to
contribute to Emacs* can land and quickly get an impression of how much
work is involved, and what the nature of that work is.

If that impression is only available from a place like etc/CONTRIBUTE,
then we're effectively asking people to have made that decision before
they've gotten the information they need to be able to make it.

It can be maintained in the Emacs tree, but it needs to be published in
a Web-standard way outside that tree (i.e., browsing to it in the
web-based git repository browser would be a poor user experience).

>Emacs was around long before "web pages". It has been slow to embrace
>web pages, because it already has a culture that works well without
>them.
>
>Perhaps that needs to change to attract new blood, but I'm not sure.
>Emacs has a _very_ different feel than "typical" development
>environments; using a unique development environment for creating Emacs
>can ensure that is maintained.

Even people who use Emacs for almost everything rarely use it as their
primary web browser.  A few do, but most don't.  As I think across all
the Emacs-first developers I know -- people like me who use Emacs as
their shell, as their mailreader, as their primary development
environment, as their primary text composition, and as their organizer
via Org Mode -- they still use a dedicated browser like Firefox for
browsing the web.

(No doubt a few people here use Emacs as their primary web browser, but
I'm pretty sure that's the exception, even among heavy Emacs users.)

So for information that people typically expect to be on the Web, such
as developer guidelines for contributing to a free software project,
we'll be better off putting that on the Web.  Because the people who
need to read it the most, the people who are the most important to us --
proficient Emacs users who are *considering* becoming contributors but
who have not decided yet -- will expect to find it on the Web anyway,
and will most likely first read it in an environment other than Emacs.

One solution would be to write those docs in (say) Markdown and
autogenerate the HTML pages, so that reading them and editing them in
Emacs is easy, but we still get HTML for the web site.

-Karl

Re: More metaproblem

[Lars Magne Ingebrigtsen]

Karl Fogel <kfogel@red-bean.com> writes:

> There needs to be place where a developer *who has not yet decided to
> contribute to Emacs* can land and quickly get an impression of how much
> work is involved, and what the nature of that work is.

Contributing small patches to Emacs is easy.  You report a bug, include
the patch, and someone will look at it.

No instructions necessary beyond "git clone
git://git.savannah.gnu.org/emacs.git", really.

(See
http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/
for details.)

If, however, you mean complete instructions on how to be an Emacs
maintainer, that would be a very long document indeed, and I don't think
it matters one iota whether that's on the web or in ./CONTRIBUTORS.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: More metaproblem

[Karl Fogel]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:
>> There needs to be place where a developer *who has not yet decided to
>> contribute to Emacs* can land and quickly get an impression of how much
>> work is involved, and what the nature of that work is.
>
>Contributing small patches to Emacs is easy.  You report a bug, include
>the patch, and someone will look at it.
>
>No instructions necessary beyond "git clone
>git://git.savannah.gnu.org/emacs.git", really.
>
>(See
>http://lars.ingebrigtsen.no/2014/11/13/welcome-new-emacs-developers/
>for details.)
>
>If, however, you mean complete instructions on how to be an Emacs
>maintainer, that would be a very long document indeed, and I don't think
>it matters one iota whether that's on the web or in ./CONTRIBUTORS.

It's the continuum in between those that I think is ill-served right
now.

Re: More metaproblem

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

  > Contributing small patches to Emacs is easy.  You report a bug, include
  > the patch, and someone will look at it.

Perhaps we should present this information prominently in places
people will see it.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: publicizing Emacs contribute

[Stephen Leake]

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. ]]]
>
>   > Contributing small patches to Emacs is easy.  You report a bug, include
>   > the patch, and someone will look at it.
>
> Perhaps we should present this information prominently in places
> people will see it.

I think we all agree on that. The problem is to figure out what
"prominent places" are appropriate.

Currently, if you do a Google search for "Emacs contribute", you find:

http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html

    The relevant section of the Emacs manual
    
http://www.gnu.org/software/emacs/CONTRIBUTE

    The official file

(I assume these are from the last release; they are not the current git
 working copy.)

(Is there a Free Software web search engine on the web? I feel a little
 guilty using Google for this.)

What other "prominent places" would you suggest?


Getting an article in some developer magazines would be very good, I
think; people on the Ada newsgroup get very excited when an article in a
developer magazine mentions Ada. I don't read any, so I don't know if
there have been any Emacs related articles recently.

Anybody up for writing "Emacs vs Microsoft Visual <language du jour>"? :).

-- 
-- Stephe

Re: publicizing Emacs contribute

[Óscar Fuentes]

Stephen Leake <stephen_leake@stephe-leake.org> writes:

[snip]

> Anybody up for writing "Emacs vs Microsoft Visual <language du jour>"? :).

You'll better not compare Emacs with Visual Studio or some other modern
IDE for crowd-oriented languages. Emacs-as-the-IDE for C++/C#/Java is a
non-starter since long time ago, as far as the Tweeter Generation is
concerned. (For C#/Java (and possibly others) they are quite right,
IMO.)

Emacs still has lots of good things to offer. Let's advertise those.

Re: publicizing Emacs contribute

[Dmitry Gutov]

Óscar Fuentes <ofv@wanadoo.es> writes:

> You'll better not compare Emacs with Visual Studio or some other modern
> IDE for crowd-oriented languages. Emacs-as-the-IDE for C++/C#/Java is a
> non-starter since long time ago, as far as the Tweeter Generation is
> concerned. (For C#/Java (and possibly others) they are quite right,

I've read good things about omnisharp-emacs.

Re: publicizing Emacs contribute

[Óscar Fuentes]

Dmitry Gutov <dgutov@yandex.ru> writes:

> I've read good things about omnisharp-emacs.

Thanks for the pointer. IIUC it requires to install an unreleased
version of ASP.NET that won't run on my platform, so I can't check it.
Sigh.

Re: publicizing Emacs contribute

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

  > You'll better not compare Emacs with Visual Studio or some other modern
  > IDE for crowd-oriented languages. Emacs-as-the-IDE for C++/C#/Java is a
  > non-starter since long time ago, as far as the Tweeter Generation is
  > concerned. (For C#/Java (and possibly others) they are quite right,
  > IMO.)

You are welcome to your opinion, but I have a feeling you are
exaggerating the negative, so I won't follow your advice.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: publicizing Emacs contribute

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

  > What other "prominent places" would you suggest?

I can think of two.
In gnu.org/software/emacs.
In the Savannah Emacs project web pages.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: publicizing Emacs contribute

[Stephen Leake]

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. ]]]
>
>   > What other "prominent places" would you suggest?
>
> I can think of two.
> In gnu.org/software/emacs.
> In the Savannah Emacs project web pages.

Right.

It's actually on my list to update those; I should have mentioned them.

-- 
-- Stephe

Re: More metaproblem

[Eric S. Raymond]

Karl Fogel <kfogel@red-bean.com>:
> So for information that people typically expect to be on the Web, such
> as developer guidelines for contributing to a free software project,
> we'll be better off putting that on the Web.  Because the people who
> need to read it the most, the people who are the most important to us --
> proficient Emacs users who are *considering* becoming contributors but
> who have not decided yet -- will expect to find it on the Web anyway,
> and will most likely first read it in an environment other than Emacs.

Precisely.  See also my remarks about much Emacs documentation being an
information ghetto.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

Re: More metaproblem

[Stephen Leake]

Karl Fogel <kfogel@red-bean.com> writes:

> There needs to be place where a developer *who has not yet decided to
> contribute to Emacs* can land and quickly get an impression of how much
> work is involved, and what the nature of that work is.

The _first_ thing I do when considering a project is to download the
source code, and browse thru it. That tells me a lot about the culture,
and whether I could stand to edit the code.

The only things I get from project web pages are a sense of how many
developers there are, how involved they are, how long the project has
been around, what language and what CM system are used.

The mailing list archive and bug tracker are good sources of
information on the first few items.

Other information on a typical project web page is aimed at people who
might _use_ the project (ie a user guide/manual), as opposed to
contribute to it.

> If that impression is only available from a place like etc/CONTRIBUTE,
> then we're effectively asking people to have made that decision before
> they've gotten the information they need to be able to make it.

Having just edited CONTRIBUTE, I must disagree.

The sort of details that are in CONTRIBUTE are things that I would only
worry about _after_ I had decided to work on a project, based on the
above browse thru the code.

There is a brief list "things you can work on other than code"; it's
pretty standard, but it would make sense to have that on a prominent web
page. 

CONTRIBUTE mostly talks about Changelog formats and how to use git;
minor details (but frustrating when you don't know them).

I was put off by bzr; but the information about which CM system Emacs
uses is on the main Savannah web page, so there's no need to consult
CONTRIBUTE for that.

> It can be maintained in the Emacs tree, but it needs to be published in
> a Web-standard way outside that tree (i.e., browsing to it in the
> web-based git repository browser would be a poor user experience).

A direct link to CONTRIBUTE in the web-based repository browser would be
a good thing for the Savanah web page. Since CONTRIBUTE now
references the wiki, along with several other sources of information, it
might make sense that it be starting point.

Hmm. It would be nice if the web links in CONTRIBUTE were presented by
a non-Emacs browser as clickable links in that case. Currently, you
have to copy and paste to the address bar.

Of course, if you browse the web in Emacs, or just read the text file in
Emacs, they _are_ clickable!

So perhpas the first line of CONTRIBUTE should be "This file is best
read in Emacs" :).

But it's probably best to keep the wiki as the primary reference from
the Savannah web page, and have it explain about CONTRIBUTE.

I'll work on the wiki next, but it's much more of a mess than
admin/notes/*

Which is a big reason I prefer files in the repository over a wiki; the
repository is kept much cleaner, because people review it.

>>Emacs was around long before "web pages". It has been slow to embrace
>>web pages, because it already has a culture that works well without
>>them.
>>
>>Perhaps that needs to change to attract new blood, but I'm not sure.
>>Emacs has a _very_ different feel than "typical" development
>>environments; using a unique development environment for creating Emacs
>>can ensure that is maintained.
>
> Even people who use Emacs for almost everything rarely use it as their
> primary web browser.  A few do, but most don't.  As I think across all
> the Emacs-first developers I know -- people like me who use Emacs as
> their shell, as their mailreader, as their primary development
> environment, as their primary text composition, and as their organizer
> via Org Mode -- they still use a dedicated browser like Firefox for
> browsing the web.

True (I use Emacs as you do). But I don't see how that addresses the
question of where the information in CONTRIBUTE should reside.

> So for information that people typically expect to be on the Web, such
> as developer guidelines for contributing to a free software project,
> we'll be better off putting that on the Web.  

Every free software project I've worked on has the "how to use our CM
system" info in a file in the CM repository, not on the web. (that
includes monotone, emacs, opentoken, dvc).

So apparently we have very different experiences, or we are 
talking about different information.

> Because the people who need to read it the most, the people who are
> the most important to us -- proficient Emacs users who are
> *considering* becoming contributors but who have not decided yet --
> will expect to find it on the Web anyway, and will most likely first
> read it in an environment other than Emacs.

People who write elisp for Emacs must be used to reading the elisp
source.

That doesn't mean they have the repository checked out; the "binary"
install includes the elisp source, but not the full source tree.

Many people who use Emacs compile it from the release tarball, to get
the latest release.

For others, it's a pretty small step to either unpack the release
tarball or checkout the git repository.

So I don't see a significant barrier here.

> One solution would be to write those docs in (say) Markdown and
> autogenerate the HTML pages, so that reading them and editing them in
> Emacs is easy, but we still get HTML for the web site.

I would not mind doing that (that's how it works in monotone), but I
don't see how that addresses the original problem, which was that
several people who were contributing were unaware of the documentation
on the processes.

And it definitely takes resources to support; the machinery that does
this in monotone breaks occasionally.

-- 
-- Stephe

Re: More metaproblem

[Phillip Lord]

Karl Fogel <kfogel@red-bean.com> writes:
> What most projects do is have a development web page. linked to from
> their main user-facing web page.  The development page organizes all
> this stuff and provides links to source code repository, dev guidelines
> & documentation, etc.
>
> For Emacs, the main web page is http://www.gnu.org/software/emacs/.
>
> It links to two possible candidates for the "developer page":
>
>   https://savannah.gnu.org/projects/emacs
>   https://savannah.gnu.org/bzr/?group=emacs
>
> But neither of those automatically-generated pages provides what a real
> development web page provides.  Instead they just tell you how to get
> the development sources and where the mailing lists are.  They don't
> tell you to look in admin/notes/ (for example).
>
> Compare those with develompent pages for projects that are trying to
> make it easy for new developers to come on board:
>
>   http://subversion.apache.org/contributing.html
>   http://www.libreoffice.org/community/developers/
>
> (both of which are easy to find from their projects' respective main
> home pages, by the way.)
>
> I hope the contrast between those examples and the way Emacs currently
> is is sufficiently clear as to not require much elucidation.


A nicer example is here...

http://orgmode.org/
http://orgmode.org/worg/org-contribute.html

Interesting because org-mode is part of Emacs core.

Would be good to have the same thing for the rest of Emacs.

Phil

Re: More metaproblem

[Stephen J. Turnbull]

Phillip Lord writes:

 > > make it easy for new developers to come on board:
 > >
 > >   http://subversion.apache.org/contributing.html
 > >   http://www.libreoffice.org/community/developers/

 > A nicer example is here...
 > 
 > http://orgmode.org/
 > http://orgmode.org/worg/org-contribute.html

None of those examples are particularly relevant.  Emacs, despite
appearances, is not an app.  Rather, it is a platform.  And it is in
the forefront of the free software movement, which at least the first
two of those projects cannot claim.

Emacs's requirements for contribution, therefore, are likely to be
rather different.

Re: More metaproblem

[David Kastrup]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Phillip Lord writes:
>
>  > > make it easy for new developers to come on board:
>  > >
>  > >   http://subversion.apache.org/contributing.html
>  > >   http://www.libreoffice.org/community/developers/
>
>  > A nicer example is here...
>  > 
>  > http://orgmode.org/
>  > http://orgmode.org/worg/org-contribute.html
>
> None of those examples are particularly relevant.  Emacs, despite
> appearances, is not an app.  Rather, it is a platform.  And it is in
> the forefront of the free software movement, which at least the first
> two of those projects cannot claim.
>
> Emacs's requirements for contribution, therefore, are likely to be
> rather different.

LilyPond has a whole "Contributor's Guide"
<URL:http://lilypond.org/doc/v2.19/Documentation/contributor/>, of
course written in Texinfo like all of the documentation.  Contributing
to the documentation is covered in
<URL:http://lilypond.org/doc/v2.19/Documentation/contributor/documentation-work>.
This includes a primer of the basic Texinfo commands used in its
documentation.

-- 
David Kastrup

RE: More metaproblem

[Drew Adams]

> LilyPond has a whole "Contributor's Guide"
> <URL:http://lilypond.org/doc/v2.19/Documentation/contributor/>, of
> course written in Texinfo like all of the documentation.
> Contributing to the documentation is covered in
> <URL:http://lilypond.org/doc/v2.19/Documentation/contributor/documen
> tation-work>. This includes a primer of the basic Texinfo commands
> used in its documentation.

I second this approach.  See my other message about this.  Either
a separate manual (this approach) or (why not?) a new section in
the Emacs manual.

Re: More metaproblem

[Stephen Leake]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Phillip Lord writes:
>
>  > > make it easy for new developers to come on board:
>  > >
>  > >   http://subversion.apache.org/contributing.html
>  > >   http://www.libreoffice.org/community/developers/
>
>  > A nicer example is here...
>  > 
>  > http://orgmode.org/
>  > http://orgmode.org/worg/org-contribute.html
>
> None of those examples are particularly relevant.  Emacs, despite
> appearances, is not an app.  Rather, it is a platform.  And it is in
> the forefront of the free software movement, which at least the first
> two of those projects cannot claim.
>
> Emacs's requirements for contribution, therefore, are likely to be
> rather different.

+2

-- 
-- Stephe

Re: More metaproblem

[Stefan Monnier]

> I realize you both mean well, but have you actually thought about the
> effect of adding more edge cases to commenting rules that are already
> rather fussy?  (And undocumented.)

Agreed.  I keep the asteriks and don't see the need for this edge case.


        Stefan

Re: More metaproblem

[Stephen Leake]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> For Emacs to attract new developers, its code and the culture need to
> be discoverable.  As part of this, practice rules need to be *clear*,
> *documented*, and *minimal*.  Right now they fail all three tests.

+1

-- 
-- Stephe

Re: More metaproblem

[Eli Zaretskii]

> Date: Wed, 3 Dec 2014 16:14:47 -0500
> From: "Eric S. Raymond" <esr@thyrsus.com>
> Cc: Paul Eggert <eggert@cs.ucla.edu>, monnier@iro.umontreal.ca,
> 	emacs-devel@gnu.org
> 
> > > For commit 
> > > e820f16c06a5a6be4bc87910b349c7c3c6eca0f4, for example, your ChangeLog 
> > > entry was "* files.el (file-tree-walk): Lisp translation of ANSI 
> > > ftw(3).", and that one-liner should have been the git commit message, too.
> > 
> > Yes, but please lose the "*" part, it just wastes precious real estate.
> > 
> > >      In vc, abolish the dir-status method.
> > > 
> > >      *  vc.el, all backends: API simplification: Abolish dir-status.
> > >      It's replaced by dir-status-files.
> > 
> > Likewise here: no need to keep the asterisks.
> 
> I realize you both mean well, but have you actually thought about the
> effect of adding more edge cases to commenting rules that are already
> rather fussy?  (And undocumented.)

If you don't want to do the above, feel free to ignore.  I promise I
won't be mad at you, and won't revoke your write access.  It was just
a suggestion (that I personally follow, Paul does with his).  Many
people here don't follow them (though many do), so it's not a disaster
if you don't, either.

> The overhead from all these picky requirements adds to big ones like
> "you must execute a copyright assignment" in ways I don't think people
> here understand. What looks reasonable and easy to you, from long
> practice, is a wilderness of brambles to outsiders.
> 
> Once I've finished cleaning up and extending VC mode I'm going to
> clean out the dusty attic in /etc (RMS and I discussed this and
> basically agreed on a plan about 11 month ago).  If you don't see how
> that's relevant, stop and think until you get it.

The main requirement is to make a point of including ChangeLog-like
entries in the commit log message, all the rest is wishlist.  I'm
allowed to have that, am I?

> For Emacs to attract new developers, its code and the culture need to
> be discoverable.  As part of this, practice rules need to be *clear*,
> *documented*, and *minimal*.  Right now they fail all three tests.

Feel free to contribute the missing documentation, and thanks in
advance.

Re: master e820f16: Added file-tree-walk to files.el.

[Michael Heerdegen]

"Eric S. Raymond" <esr@thyrsus.com> writes:

>     Added file-tree-walk to files.el.

FWIW, I recently wrote quite the same as addition to my iterator
package.  Whereby I use a recursion predicate of it's own, and the
action is to be applied after defining the iterator:

--8<---------------cut here---------------start------------->8---
(defun gen-of-files-df (dir &optional exclude-dirs)
  (cl-callf or exclude-dirs #'ignore)
  (let ((files (if (funcall exclude-dirs dir)
                   '()
                 (directory-files dir t)))
        subgen file)
    (gen-delq
     nil
     (gen-make 
      (if (not subgen)
          (if (not files)
              'gen-done
            (setq file (pop files))
            (if (string-match-p
                 "\\`\\.+\\'" (file-name-nondirectory file))
                nil
              (when (and (file-directory-p file)
                         (not (file-symlink-p file)))
                (setq subgen (gen-of-files-df file exclude-dirs)))
              file))
        (setq file (gen-next subgen))
        (if (not (eq file 'gen-done))
            file
          (setq subgen nil)
          nil))))))
--8<---------------cut here---------------end--------------->8---


And I guess it would be cool to have a breadth-first file-tree walker as
well?


Regards,

Michael.

Re: master e820f16: Added file-tree-walk to files.el.

[Eric S. Raymond]

Michael Heerdegen <michael_heerdegen@web.de>:
> And I guess it would be cool to have a breadth-first file-tree walker as
> well?

A good distinguishing feature.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

RE: More metaproblem

[Drew Adams]

> > Developers are users.  Some users are developers.  There is no
> > reason not to provide such info for users in general (IMHO).
> > Especially if we want to encourage users to contribute.
> 
> I suggest to put this issue on hold for a moment.  We don't yet have
> the contents of that file in its final form.  I suggest to wait
> until we do, and decide whether to move it into some manual later.
> There's no rush.

OK; sounds good.  Thanks for considering it, at least.