More metaproblem

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

[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: 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

[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

[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]

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

[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

[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

[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

[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

[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: 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

[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

[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

[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

[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: 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

[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

[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

[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]

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

[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]

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

[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

[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]

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

[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

[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

[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

[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]

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

[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

[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

[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

[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

[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

[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

[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

[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>:
>   (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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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

[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: 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

[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

[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

[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

[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

[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

[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

[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: 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

[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

[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

[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

[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

[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]

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

[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.

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

[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

[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

[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

[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

[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