GNU Emacs Contributing Guide

GNU Emacs Contributing Guide

[xfq]

Hi,

From time to time, questions about contributing to Emacs appears on this
list.  Examples are:
http://lists.gnu.org/archive/html/emacs-devel/2001-11/msg01087.html
http://lists.gnu.org/archive/html/emacs-devel/2004-03/msg00750.html
http://lists.gnu.org/archive/html/emacs-devel/2011-07/msg00910.html
http://lists.gnu.org/archive/html/emacs-devel/2013-01/msg00631.html
http://lists.gnu.org/archive/html/emacs-devel/2013-04/msg00077.html

And Stafan said that there is not a good welcome guide.[fn:2] So I wrote
a welcome guide[fn:1] to reduce this kind of questions and give
potential contributors a map on it.  Many ideas in this guide are from
etc/CONTRIBUTE and admin/notes.

The question now is, what is the future of this guide?  I have some
thoughts:
a) Continue maintaining this guide by myself;
b) Register a new project on Savannah;
c) Integrate in into Emacs website and let it maintained by Emacs Dev;
d) Convert it to Oddmuse text formatting rules and create a page on
Emacs Wiki;
e) Convert in to Texinfo (using ox-texinfo.el) format, and make it an
Emacs manual (or a node of an Emacs manual).

Maybe there are some other ideas, any suggestions?

Footnotes:

[fn:1] http://xfq.yuyii.com/contribute.html

[fn:2] http://lists.gnu.org/archive/html/emacs-devel/2013-04/msg00118.html

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

Re: GNU Emacs Contributing Guide

[Karl Fogel]

xfq <xfq.free@gmail.com> writes:
>And Stafan said that there is not a good welcome guide.[fn:2] So I wrote
>a welcome guide[fn:1] to reduce this kind of questions and give
>potential contributors a map on it.  Many ideas in this guide are from
>etc/CONTRIBUTE and admin/notes.
>
>The question now is, what is the future of this guide?  I have some
>thoughts:
>a) Continue maintaining this guide by myself;
>b) Register a new project on Savannah;
>c) Integrate in into Emacs website and let it maintained by Emacs Dev;
>d) Convert it to Oddmuse text formatting rules and create a page on
>Emacs Wiki;
>e) Convert in to Texinfo (using ox-texinfo.el) format, and make it an
>Emacs manual (or a node of an Emacs manual).

Thank you for putting this together!

IMHO (c) makes the most sense, as that seems like an appropriate place
for it.  If not, then (d) and we can just remember to point to it in the
wiki.  But the ideal place for it to be findable from would be
http://www.gnu.org/software/emacs/, which is what I assume you mean by (c).

I don't have edit rights on (c), as far as I know, so I hope someone
who does agrees with this.

-Karl

Re: GNU Emacs Contributing Guide

[Glenn Morris]

Karl Fogel wrote:

> I don't have edit rights on (c), as far as I know, so I hope someone

Anyone with commit rights to Emacs has commit rights to the web pages.

http://savannah.gnu.org/cvs/?group=emacs

Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Karl Fogel]

Glenn Morris <rgm@gnu.org> writes:
>> I don't have edit rights on (c), as far as I know, so I hope someone
>
>Anyone with commit rights to Emacs has commit rights to the web pages.
>
>http://savannah.gnu.org/cvs/?group=emacs

Thank you.  

Any objections if I integrate Xue Fuqiao's guide into those pages in
some reasonable way?  (Which I'm not defining here only because I'll
figure it out if/when we're generally agreed this is a Good Thing.)

I think the guide is a very good start.  I might make a few edits before
integrating, and would expect further edits over time, but I don't think
it needs to be perfect to be posted.  It contains a lot of useful
information.  One change I would probably make right away is to have the
document link to the mailing list threads Xue Fuqiao listed in his
original post on this topic.

Xue, what was the original format of the document?  LaTeX or Docbook?
(I think if we integrate it into the web site, we should probably just
use the HTML version as master, to keep things simple, but maybe there
is a reason to generate HTML from another format?)

-Karl

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Bastien]

Hi all,

Karl Fogel <kfogel@red-bean.com> writes:

> Xue, what was the original format of the document?  LaTeX or Docbook?
> (I think if we integrate it into the web site, we should probably just
> use the HTML version as master, to keep things simple, but maybe there
> is a reason to generate HTML from another format?)

Or maybe .org would be useful here, as it can export both to HTML and
Texinfo?

-- 
 Bastien-aka-don't-tell-me-you-didn't-see-this-coming

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Karl Fogel]

Bastien <bzg@gnu.org> writes:
>> Xue, what was the original format of the document?  LaTeX or Docbook?
>> (I think if we integrate it into the web site, we should probably just
>> use the HTML version as master, to keep things simple, but maybe there
>> is a reason to generate HTML from another format?)
>
>Or maybe .org would be useful here, as it can export both to HTML and
>Texinfo?

Well, that'd be fine with me, but although I use Org Mode, I don't do
exports from it and just saw that (apparently) something about Org Mode
exporting has changed recently in an incompatible way.  

I think I personally have the gumption to edit and check in an HTML
page, but not to deal with integrating more docs into a build system --
just a question of priorities, available dev time, etc.  But +1 on that
approach if someone would actually do it.

-K

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Bastien]

Karl Fogel <kfogel@red-bean.com> writes:

> I think I personally have the gumption to edit and check in an HTML
> page, but not to deal with integrating more docs into a build system --
> just a question of priorities, available dev time, etc.  But +1 on that
> approach if someone would actually do it.

Sure -- as a basic rule, the one who takes charge decides
what he's more comfortable working with.

-- 
 Bastien

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

On Tue, Apr 23, 2013 at 1:13 AM, Karl Fogel <kfogel@red-bean.com> wrote:
> Bastien <bzg@gnu.org> writes:
>>> Xue, what was the original format of the document?  LaTeX or
>Docbook?

Org (7.9.3f).  I haven't tried 8.x now.

> I think I personally have the gumption to edit and check in an HTML
> page, but not to deal with integrating more docs into a build system --
> just a question of priorities, available dev time, etc.  But +1 on that
> approach if someone would actually do it.

Agreed.  In the The GNU/FSF Web Site Guidelines[fn:1]:

  Offer a document in as many formats as the GNU Project has it. For an
  example, see The GNU Free Documentation License. This lets the user
  get the document in the format most useful to him.

Footnotes:

[fn:1] http://www.gnu.org/server/fsf-html-style-sheet.html

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

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Glenn Morris]

Karl Fogel wrote:

> Any objections if I integrate Xue Fuqiao's guide into those pages in
> some reasonable way?  (Which I'm not defining here only because I'll
> figure it out if/when we're generally agreed this is a Good Thing.)

In principle, no, though without having read it yet I'm not sure it
makes sense to have both this _and_ etc/CONTRIBUTE (which is already on
the website). I imagine you just upload it and change the CONTRIBUTE link
to point to it.
(Also note that Xue Fuqiao has commit rights.)

> Xue, what was the original format of the document?  LaTeX or Docbook?
> (I think if we integrate it into the web site, we should probably just
> use the HTML version as master, to keep things simple, but maybe there
> is a reason to generate HTML from another format?)

Normally we use Texinfo. This will give HTML that matches the format of
the other pages. Normally the source would live somewhere in the normal
Emacs repo, and the HTML in the CVS repo. HTML only is fine for web-only
documents.


PS "incredible adventure"? Bah humbug.

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Karl Fogel]

Glenn Morris <rgm@gnu.org> writes:
>In principle, no, though without having read it yet I'm not sure it
>makes sense to have both this _and_ etc/CONTRIBUTE (which is already on
>the website). I imagine you just upload it and change the CONTRIBUTE link
>to point to it.
>(Also note that Xue Fuqiao has commit rights.)

Oh, silly me -- Xue can do this!  Why don't we ask Xue to integrate it
now, however he thinks best, and then any of us who want to make edits
on it (and/or tweak etc/CONTRIBUTE accordingly) can then do so.  This
document covers more more than etc/CONTRIBUTE does.  In the long run, I
think it makes sense for etc/CONTRIBUTE to be replaced by this doc, and
for the former to just point to the latter for link compatibility.

>Normally we use Texinfo. This will give HTML that matches the format of
>the other pages. Normally the source would live somewhere in the normal
>Emacs repo, and the HTML in the CVS repo. HTML only is fine for web-only
>documents.

This makes sense to me.

>PS "incredible adventure"? Bah humbug.

Oh it is, it is.

-K

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

On Tue, Apr 23, 2013 at 2:13 AM, Karl Fogel <kfogel@red-bean.com> wrote:

>>Normally we use Texinfo. This will give HTML that matches the format of
>>the other pages. Normally the source would live somewhere in the normal
>>Emacs repo, and the HTML in the CVS repo. HTML only is fine for web-only
>>documents.
>
> This makes sense to me.

Sounds fine to me, too.  I'll try ox-texinfo.el later.

BTW what's the next step after converting it into Texinfo format?  Put
it in `trunk/doc/misc'?  I'm not familiar with makeinfo and the
Makefiles of Emacs...

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

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

By the way, should I change "Copyright (C) Xue Fuqiao" to "Free Software
Foundation, Inc."?

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

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Stefan Monnier]

> By the way, should I change "Copyright (C) Xue Fuqiao" to "Free Software
> Foundation, Inc."?

As soon as you decide you want to contribute it to Emacs, yes, and at
the latest when installing it into Emacs's repository.


        Stefan

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Stefan Monnier]

>>> I don't have edit rights on (c), as far as I know, so I hope someone
>> Anyone with commit rights to Emacs has commit rights to the web pages.
>> http://savannah.gnu.org/cvs/?group=emacs
> Any objections if I integrate Xue Fuqiao's guide into those pages in
> some reasonable way?  (Which I'm not defining here only because I'll
> figure it out if/when we're generally agreed this is a Good Thing.)

I think it's OK.  Tho it might be worth splitting it into a few, more
targeted parts.  E.g. one could be "how to submit a patch" and another
could be a "primer for new committer".  They should be as short as
possible, to try and make sure even the unmotivated read it.

One detail: I'm not completely comfortable with the GSoC section.
While GSoC is a nice source of funding I (and I believe the FSF as well)
has some reservations about it in general (e.g. the restrictions on
nationals of stigmatized countries like Cuba, Iran, ...), so I'm not
sure I like advertising it on our web site (although I have advertised
it on this very list just a few days ago).


        Stefan

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

On Tue, Apr 23, 2013 at 11:32 AM, Stefan Monnier
<monnier@iro.umontreal.ca> wrote:
>> Any objections if I integrate Xue Fuqiao's guide into those pages in
>> some reasonable way?  (Which I'm not defining here only because I'll
>> figure it out if/when we're generally agreed this is a Good Thing.)

> I think it's OK.  Tho it might be worth splitting it into a few, more
> targeted parts.  E.g. one could be "how to submit a patch" and another
> could be a "primer for new committer".  They should be as short as
> possible, to try and make sure even the unmotivated read it.

I don't have time splitting it now, tho.  I'll contribute it to Emacs
and let others (and me) to do this work later.

> One detail: I'm not completely comfortable with the GSoC section.
> While GSoC is a nice source of funding I (and I believe the FSF as well)
> has some reservations about it in general (e.g. the restrictions on
> nationals of stigmatized countries like Cuba, Iran, ...), so I'm not
> sure I like advertising it on our web site (although I have advertised
> it on this very list just a few days ago).

OK, I'll remove it.  It does not provide much useful information, and
guys who want to participate GSoC can get information on GNU guidelines
for Summer of Code projects and google-melange.

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

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

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

Here is the very first version in Texinfo format.  There are some
issues:

1. no EDITION
2. no @copying
3. no @documentencoding
4. no introduction in Top node
5. TODO of this guide can be moved to etc/TODO

I don't have time resolving them now, can anyone familiar with
Texinfo help?

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

[-- Attachment #2: contribute-fsf.texi --]
[-- Type: application/x-texinfo, Size: 37045 bytes --]

RE: GNU Emacs Contributing Guide

[Drew Adams]

> >The question now is, what is the future of this guide?  I have some
> >thoughts:
> >
> >a) Continue maintaining this guide by myself;
> >b) Register a new project on Savannah;
> >c) Integrate in into Emacs website and let it maintained by 
> >   Emacs Dev;
> >d) Convert it to Oddmuse text formatting rules and create a page
> >   on Emacs Wiki;
> >e) Convert in to Texinfo (using ox-texinfo.el) format, and make it
> >   an Emacs manual (or a node of an Emacs manual).
> 
> Thank you for putting this together!

1+
 
> IMHO (c) makes the most sense, as that seems like an appropriate
> place for it.  If not, then (d) and we can just remember to point 
> to it in the wiki.  But the ideal place for it to be findable
> from would be http://www.gnu.org/software/emacs/, which is what
> I assume you mean by (c).

An Info manual and a web page are both important, and the wiki can point to the
latter.  IOW:

1. I like option (e).  And link to it from the Emacs manual.
2. And also (c).  IOW, put it on the web somewhere too.

If (c) is done then the wiki can point to it elsewhere on the web (and to
specific parts of it) without any need for (d).

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Jonathan Leech-Pepin]

Hello Xue,

Assuming you're working from a .org file (since you mentioned
ox-texinfo.el).  If not this will likely not be of any relevance.

> Here is the very first version in Texinfo format.  There are some
> issues:
>
> 1. no EDITION

There is no direct support for exporting variables to texinfo.  If
working directly from the org file at all times, you can replace it
with an Org macro which will serve a similar purpose.

To export the variables to .texi you could do the following:

1. Allow texinfo snippets

   (add-to-list 'org-export-snippet-translation-alist
                '("info" . "texinfo"))

2. Use the following in the document

   #+TEXINFO: @set EDITION <edition>
   #+MACRO: edition @@info:@value{EDITION}@@

   Then use {{{edition}}} anywhere you wish the variable to be
   inserted.

> 2. no @copying

To create a @copying section in the texinfo document you need to
create a headline in the org file with a :copying: property set to a
non-nil value.  It will be inserted at the right location on export
(regardless of where it is found in the org document) and will not
appear anywhere else.

Do not include any subheadings, the exporter will try to export them
as @section/@subsection... which will cause issues.

> 3. no @documentencoding

This is fixed as of commit 'fea4b5c'.  Previously it would only
include @documentencoding if `org-texinfo-coding-system' was set.  Now
it will default to `buffer-file-coding-system'.

> 4. no introduction in Top node

At the moment the closest option (I intend to improve it) is that any
text before the first headline will be in the @top node, however it
will appear after the menu (as opposed to before it).

> 5. TODO of this guide can be moved to etc/TODO
>
> I don't have time resolving them now, can anyone familiar with
> Texinfo help?
>
> --
> Best regards, Xue Fuqiao.
> http://www.gnu.org/software/emacs/

--
Regards,
Jon

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

On Tue, Apr 23, 2013 at 10:08 PM, Jonathan Leech-Pepin
<jonathan.leechpepin@gmail.com> wrote:
> Hello Xue,

Hello,

>  If working directly from the org file at all times, you can replace
> it with an Org macro which will serve a similar purpose.

Thanks, I will work directly from the Texinfo file in the future.

I made some changes just now, this is the latest version.  Can it be
added to the repository now?

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

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

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

On Wed, Apr 24, 2013 at 6:48 AM, Xue Fuqiao <xfq.free@gmail.com> wrote:
> I made some changes just now, this is the latest version.  Can it be
> added to the repository now?

Sorry, I forgot to attach it.

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

[-- Attachment #2: contribute-fsf.texi --]
[-- Type: application/x-texinfo, Size: 36585 bytes --]

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Glenn Morris]

Hi,

Some comments. I only commented on the things I disagreed with, so this
is probably going to come across as negative, sorry. I also think I'm
probably not in the best position to assess a document about motivating
people to get involved in Emacs (if that is the intent).

My main comment is that it seems rather disjointed, and tries to cover
way, way too much. You've got stuff ranging from basic info about how to
post on a mailing list, to very dry technical details about stylistic
conventions used in Emacs, to "there's this thing called grep" basic
UNIX stuff. As it stands, I don't think I see a place for it as an Emacs
manual, it's just too unfocused.

A lot of it is copied (without attribution) from GNU standards, Emacs
files such as README, etc/CONTRIBUTE, admin/notes, and many other
places. This is just lots and lots of pointless duplication. It would be
much better to just refer to those documents, unless your aim is to
replace all of them with one uber-document, which would be a huge job
and not very valuable IMO. I have to say that I prefer the style of
etc/CONTRIBUTE as a shorter document that just tries to tell you the
basics of what you need to know to start getting involved.

I do think that it would be valuable to have some kind of hacking Emacs
guide, that tells you everything you need to know about how to commit to
Emacs, but I think that should be a separate document.

There's that as one document, and the contributing to the Emacs
community stuff that you start with as another, and then Emacs coding
conventions etc which are largely covered elsewhere already IMO.

  @set AUTHOR Xue Fuqiao

Unused?

  updated for Emacs version @value{EMACSVER}.

Is EMACSVER really relevant? If not, it's simpler to do without it.

  People involved with the Emacs community have differing political,
  social, economic and ethnic backgrounds. We work across timezones,
  languages, and cultures. The success of Emacs depends on participation
  from people like you. Find out how you can get involved to help make a
  difference in the lives of users everywhere in the future.

I'm sorry, but I really dislike this language. It seems irrelevant,
obvious, and over-the-top. The preceding sentence ("GNU Emacs is a
collaborative project and we encourage contributions from anyone", lifted
from etc/CONTRIBUTE) says all that needs to be said IMO.

  Emacs have a community of enthusiastic volunteers trying to support
  our users around the globe.

s/have/has
s/trying to support/supporting

  Join us for an incredible adventure!

Sorry, this sounds silly to me. It's hacking on a text editor. If you
enjoy hacking on text editors, you might find it enjoyable. If you
don't, you probably won't. It's not finding the source of the Nile.
(Ignore me if I'm just too negative and everyone else thinks this is fine.)

  You can find questions from mailing lists (like @uref{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs,help-gnu-emacs} and
  @uref{https://lists.gnu.org/mailman/listinfo/help-emacs-windows,help-emacs-windows}), newsgroups (like comp.emacs and
  gnu.emacs.help), websites (like @uref{http://stackoverflow.com/questions/tagged/?tagnames=emacs&sort=newest,Stack Overflow}), and IRC channels
  (like @verb{~#emacs~} and @verb{~#gnus~} on Freenode).

Maybe you want to mention that gnu.emacs.help == help-gnu-emacs
  
  Rather than trying to figure out the user's problem by yourself
  every time, first search to see if it has come up before.  Try to
  search the Emacs manuals before anything else.  If the manuals
  don't have your answers, you can use other sources. 

"Do the work people are too lazy to do for themselves."

  If you find out the solution, consider adding it to the Emacs FAQ.

The Emacs FAQ is kind of useless IMO.  This advice seems oddly out of
place, because while anyone can do the previous steps you've outlined
till now, this one needs commit rights.

  Be nice.  If you feel that a post has crossed the line, report
  it to the Emacs maintainers.

No. This is a) obvious, and not special to Emacs, so hardly needs to be
mentioned IMO; and b) I do not want to get mails from people complaining
that someone was mean to them on Stack Overflow or wherever. Report it
to whoever moderates the communication medium you are using (if a
mailing list, this is the list owner). If no-one does, ignore the
offending party and move on.

   Subscribing to the
   @uref{http://lists.gnu.org/mailman/listinfo/emacs-devel,emacs-devel}
   mailing list is a good idea. It's a mailing list for communications
   among Emacs developers.

There's zero need to subscribe to this unless you are interested in
Emacs development. If you just want to _use_ Emacs, then you can ignore
this list.

  Don't post chain letters, marketing messages or other types of
  non-topical spam.

Obviously. What does this have to do with contributing to Emacs?

  Or validate web pages of Emacs.

Not clear what this means.

  If you would like to help pretest Emacs releases to assure they work
  well, or if you would like to work on improving Emacs, please contact
  the maintainers at @email{emacs-devel@@gnu.org,emacs-devel@@gnu.org}. A
  pretester should be prepared to investigate bugs as well as report them.

There is zero need to mail this list if you want to pretest Emacs.
Just do it.

  If you know HTML/CSS, you can contribute to the web pages of
  Emacs and GNU ELPA.

There is very little to do here IMO. Most of the Emacs web-pages are
static or generated from Texinfo.

  If you know C, you can contribute to a number of low-level
  libraries

Seems an odd statement.

  and help us write Emacs primitives.

Could be phrased better.

  Porting to new platforms is also useful.

This comes up almost never, and is unlikely to be suitable for casual
contributors, so hardly seems worth mentioning.

  If you think of new features to add to @verb{~etc/TODO~}, please
  suggest them too.

Not the best way to phrase it. If people think of new features, they
should be reported as wishlist bugs. (But what we really need are people
to implement ideas, not sit around brainstorming.)

  Before contributing a new feature to Emacs, you should check to
  make sure that the feature isn't already available.  (See @uref{http://lists.gnu.org/archive/html/emacs-devel/2013-04/msg00180.html,this thread}.) 

I have no idea why you link to that thread.

  For example, typing @verb{~M-x apropos <RET> humor <RET>~} lists
  all functions and variables containing the string @verb{~humor~}; typing
  @verb{~M-x list-packages~} command connects to the GNU ELPA
  (@uref{http://elpa.gnu.org}) ("Emacs Lisp Package Archive") server and
  fetches the list of additional packages that it offers.  These are
  GNU packages that are available for use with Emacs, but are
  distributed separately.  It is also possible that the package is on
  your system, but has not been loaded.  To see which packages are
  available for loading, look through your computer's Lisp directory.

In all honesty, this could be summarized as "do a web search before
spending time implementing something that already exists".

  Think carefully about whether your change requires updating the
  documentation.  If it does, you can either do this yourself or add
  an item to the NEWS file.

Now you've suddenly jumped to stuff that is only relevant to people with
commit rights.

  If you document your change in NEWS, please mark the NEWS entry
  with the documentation status of the change: if you submit the
  changes for the manuals, mark it with @verb{~+++~}; if it doesn't need to
  be documented, mark it with @verb{~---~}; if it needs to be documented,
  but you didn't submit documentation changes, leave the NEWS entry
  unmarked.

Now you are just copying stuff from NEWS.

  @footnote{These marks are checked by the Emacs maintainers to make
  sure every change was reflected in the manuals.}

If you are committing stuff to that file, you ARE the Emacs maintainers.
Ie, everyone should think about documentation, rather than farming it out
to some other sucker.

  They should follow our usual standards for web pages:

I honestly can't think of a single case in the past ten years where
someone has contributed a web page to Emacs, so I just can't see how
this relevant to anyone. I assume it is mainly cribbed from
http://www.gnu.org/server/fsf-html-style-sheet.html, so why not just
refer to that rather than copying it?

  @node Some Coding Conventions

May as well just refer to the relevant section of the elisp manual
rather than reproduce pieces of it.

  You can design themes, icons and web pages for Emacs.

Themes ok, but what icons do we need?
Again, I don't think web-pages design is needed (maybe this is my
failing and there is lots that could be done here).

  Proof-reading the manuals and man pages.  That's also a great way
  to learn more about Emacs.  This is usually done together with
  reading the NEWS file to make sure that the manual has been
  updated.

I'd lose the second sentence.
 
  Generally the manual gives a bit less details but more background/context.

Not sure I agree.

  In Emacs tradition, we treat "point" as a proper name when it
  refers to the current editing location.  It should not have an
  article.  Thus, it is incorrect to write, "The point does not
  move".  It should be, "Point does not move".  If you see "the
  point" anywhere in Emacs documentation or comments, referring to
  point, please fix it.

This is just cribbed from admin/notes/documentation.
Unless you want this to be the absolute definitive reference for Emacs
coding, I can't see the point in mentioning such a dry, technical detail
here.

  Antinews is useful.

(I disagree.) Again, this is just cribbed from admin/notes/documentation.
I cannot see the point in mentioning this here. (One poor sucker has to
try and update it just before a release, apart from that it's largely
irrelvant.)

  Emacs should not recommend, promote, or grant legitimacy to the use of
  any non-free program. We can’t stop some people from writing
  proprietary programs, or stop other people from using them, but we can
  and should refuse to advertise them to new potential customers, or to
  give the public the idea that their existence is ethical.

I cannot see the relevance of this (copied from GNU standards) to your
guide.

  Never introduce new terminology in the middle of a complex
  description, where each successive sentence builds upon what the
  preceding ones said.  Always use @emph{exactly} the same words as in
  the preceding sentences.

This is just copied from a recent emacs-devel posting. Not sure it
really fits.

  Good spelling is encouraged.

No, correct spelling and grammar is required, just like correct code is.
But if you implement some new feature and your English is not best, it
is much better if you at least try to document it, and ask for help with
polishing, rather than leave someone else to do all the work.

  Sentences should start with an uppercase letter.

This is just the normal rule of English.

  Don't mention in Antinews too many features absent in old versions.

I imagine this is just copied from somewhere. It has no relevance to
99.99+% of people, so why mention it at all.

  To indicate possession, write Emacs's rather than Emacs'.  See
  @uref{http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00649.html}

True, but tedious. Is this intended to be the "definitive guide to how
to write Emacs documentation"? I don't think this fits in the same
document as "how to answer mailing list questions".

  When you have all these pieces, bundle them up in a mail message and
  send it to the developers. Sending it to
  @email{bug-gnu-emacs@@gnu.org,bug-gnu-emacs@@gnu.org} (which is the
  bug/feature list) is recommended, because that list is coupled to a
  tracking system that makes it easier to locate patches. If your patch
  is not complete and you think it needs more discussion, you might want
  to send it to @email{emacs-devel@@gnu.org,emacs-devel@@gnu.org}
  instead. If you revise your patch, send it as a followup to the
  initial topic.

Copied from etc/CONTRIBUTE, missing the introductory sentence about
"several pieces", therefore doesn't really make sense.

  If installing changes written by someone else, make the ChangeLog entry
  in their name, not yours. There is no need to make change log entries
  for files such as NEWS, MAINTAINERS, and FOR-RELEASE.

Not relevant to people without commit rights, ie to people just
submitting patches.

  If your version of diff does not support these options, then get
  the latest version of GNU Diff.

I cannot believe this will be relevant for anyone.

  or, as a last resort, uuencoded gzipped text.

Irrelevant in this day and age.

   GNU Emacs Common Lisp Emulation.  See @ref{Top,,,cl,}.

Hardly seems relevant for casual contributors.

  CC Mode.
   [...]
  @uref{http://cedet.sourceforge.net/,CEDET}.  CEDET is a
   [...]
  @item  @uref{http://www.emacswiki.org/emacs/Icicles,Icicles}.

I can't see the point of mentioning these.

  Tags Tables.  See @ref{Tags,,,emacs,}.

Can't see the relevance of this either.

   @uref{http://developer.gnome.org/gtk3/unstable/,GTK+ 3 Reference
   Manual}, since GTK+ is the default X toolkit in GNU Emacs.

Can't see the point. Obviously you read that if you are working with the
Emacs Gtk toolkit integration, and don't need to be told it exists, and
if you aren't, you don't.

  @uref{http://www.libtiff.org/libtiff.html,Using The TIFF Library}

  @uref{http://giflib.sourceforge.net/intro.html,Introduction to GIFLIB}

Irrelevant IMO.

  @item GNU build system. It helps Emacs developers make Emacs source
  code portable to many Unix-like
  systems.@footnote{@uref{http://www.gnu.org/software/autoconf
  /manual/index.html}}@footnote{@uref{http://www.gnu.org/software/automake/manual/automake.html}}@footnote{@uref{http://www.gnu.org/software/gnulib/manual/}}

Irrelevant unless you are working on that stuff, else obvious.

   @item 
  @uref{http://ximbiot.com/cvs/manual/stable,HTML Cederqvist for CVS
  stable release}.  The web pages of Emacs are kept in a CVS repository.

Irrelevant to almost everybody.

  @item @uref{http://www.gnu.org/software/make/manual/,GNU Make Manual}.
  Make is a tool which controls the generation of executables and other
  non-source files of Emacs from the source files.

Irrelevant unless you are working on that stuff, else obvious.

  @uref{http://gcc.gnu.org/onlinedocs/,GCC online documentation}. The
  GNU Comp iler Collection (GCC) is a compiler system produced by the
  GNU Project supporting various programming languages.

Irrelevant/obvious.

  @item @uref{http://www.gnu.org/software/guile/manual/,GNU Guile
  Reference Manual}. Guile, a dialect of Scheme, is the native language of
  the GNU standard extension language interpreter.

Irrelevant unless you are working on that stuff, else obvious.

  @item @uref{http://www.gnu.org/software/grep/manual/,GNU Grep Manual}.
  The @verb{~grep~} command searches one or more input files for lines
  containing a match to a specified pattern. It is a very useful tool and
  often used when developing Emacs.

This is the point at which I begin to think I'm coming at this from
totally the wrong perspective, because I really can't see the point of
linking to the grep manual in a "how to contribute to Emacs" guide.

  @menu
  * How to report a bug?::        
  * How to comment on a bug?::    
  * How to close a bug?::         
  * How to set bug meta-data?::   
  @end menu

Pretty sure all this is just copied from elsewhere.
I'm not sure of the value of having everything in one massive document.

  If you want to Cc someone, use an @verb{~X-Debbugs-CC~} header instead.

Irrelevant for the vast majority of people.

  @node Copyright
  @chapter Copyright

Mainly copied from etc/CONTRIBUTE.

  Every non-trivial file distributed through the Emacs repository
  should be self-explanatory in terms of copyright and license.

  The definition of triviality is a little vague[...]

   Legal advice says that we could, if we wished, put a license notice[...]

I don't think any of these details belong here.

  @node Emacs repositories
  @chapter Emacs repositories
  There are three official Emacs repositories: @uref{http://bzr.savannah.gnu.org/lh/emacs/,Bazaar}, @uref{http://web.cvs.savannah.gnu.org/viewvc/?root=emacs,CVS}, and @uref{http://git.savannah.gnu.org/cgit/emacs.git,Git}.

I disagree. The offical repo is Bazaar. (There is a read-only Git
mirror, and the web pages live in CVS for technical reasons, and are not
relevant to most people.)

    * Building Emacs::              

Read INSTALL? Do you really want to cover this here as well?

  @node Emacs Directory Tree

Copied from README and <subdir>/README. Seems like totally pointless
duplication.

  @item 
  Each commit should correspond to a single change (whether spread
  over multiple files or not). 

Copied from admin/notes/commits. Why not just reference it rather than
duplicate it?

  @item 
  For historical interest only, here is an old-style advice for CVS logs:

Seriously, why are you copying even this old stuff?

  @item
  elpa
  The GNU Emacs package archive, at elpa.gnu.org, is managed using a
  Bzr branch named "elpa", hosted on Savannah.  To check it out:

Copied from admin/notes/elpa.

  @item 
  You should identify each release with a pair of version numbers, a
  major version and a minor.

Who is this for?

  @item 
  Non-source files that might actually be modified by building and
  installing the program should @emph{never} be included in the
  distribution.

Who is this for?

  @item
  +1
  The shortest way in the geek world to say "I agree with this" or
  "This is a great idea".

Annoying as hell, adds nothing, don't do it.

  @item
  DVCS

Hardly seems relevant. I'm not sure what the point of any of these items
are, to be honest. GSoC, IDE, IRC, UTC?! Why are you trying to explain
these terms here?

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Stefan Monnier]

> I do think that it would be valuable to have some kind of hacking Emacs
> guide, that tells you everything you need to know about how to commit to
> Emacs, but I think that should be a separate document.

Indeed, I think a "guide for the new committer" would be great.


        Stefan

Re: Integrating new "GNU Emacs Contributing Guide" into Emacs web pages.

[Xue Fuqiao]

On Thu, Apr 25, 2013 at 3:02 PM, Glenn Morris <rgm@gnu.org> wrote:
>
> Hi,

Hi,

> Some comments. I only commented on the things I disagreed with, so this
> is probably going to come across as negative, sorry.

No need to be sorry.  Pointing out my faults can make me grow up, thank
you.

> I also think I'm probably not in the best position to assess a
> document about motivating people to get involved in Emacs (if that is
> the intent).

Yes, that's the intent.

> My main comment is that it seems rather disjointed, and tries to cover
> way, way too much. You've got stuff ranging from basic info about how to
> post on a mailing list, to very dry technical details about stylistic
> conventions used in Emacs, to "there's this thing called grep" basic
> UNIX stuff. As it stands, I don't think I see a place for it as an Emacs
> manual, it's just too unfocused.

> A lot of it is copied (without attribution)

That's true.  Since I began to write this guide about two weeks ago, I
haven't had time refining it yet.

> from GNU standards, Emacs files such as README, etc/CONTRIBUTE,
> admin/notes, and many other places. This is just lots and lots of
> pointless duplication. It would be much better to just refer to those
> documents, unless your aim is to replace all of them with one
> uber-document, which would be a huge job and not very valuable IMO. I
> have to say that I prefer the style of etc/CONTRIBUTE as a shorter
> document that just tries to tell you the basics of what you need to
> know to start getting involved.

I think we should include *some* (at least more than etc/CONTRIBUTE)
basics.  If etc/CONTRIBUTE is that useful, there won't be much questions
about contributing to Emacs.  (The style of etc/CONTRIBUTE is good, tho.)

BTW (sorry if it's off-topic) I think it is also a problem with Emacs
manual.  It is written with 1980's mindset, many nodes are in a verbose
way and can be edited out as improvement.  (Like `real-time display',
this feature is in most modern editors today.)

> I do think that it would be valuable to have some kind of hacking Emacs
> guide, that tells you everything you need to know about how to commit to
> Emacs, but I think that should be a separate document.

Agreed.  Maybe it can be based on this document:
http://www.emacswiki.org/emacs/HackerGuide

> There's that as one document, and the contributing to the Emacs
> community stuff that you start with as another, and then Emacs coding
> conventions etc which are largely covered elsewhere already IMO.

Agreed, that's a great problem I'm trying to resolve.  (But not now.
I'm really busy these days.)

>   @set AUTHOR Xue Fuqiao
>
> Unused?

Yes, it can be removed.

>   updated for Emacs version @value{EMACSVER}.
>
> Is EMACSVER really relevant? If not, it's simpler to do without it.

I didn't think much here.  Maybe this document is not similiar to
emacs.texi/elisp.texi/faq.texi.

>   People involved with the Emacs community have differing political,
>   social, economic and ethnic backgrounds. We work across timezones,
>   languages, and cultures. The success of Emacs depends on participation
>   from people like you. Find out how you can get involved to help make a
>   difference in the lives of users everywhere in the future.
>
> I'm sorry, but I really dislike this language. It seems irrelevant,
> obvious, and over-the-top. The preceding sentence ("GNU Emacs is a
> collaborative project and we encourage contributions from anyone", lifted
> from etc/CONTRIBUTE) says all that needs to be said IMO.

This sentence is originally "GNU is a collaborative project and we
encourage contributions from anyone", but I think it is not quite
relavant to Emacs.  I take your advice.

>   Emacs have a community of enthusiastic volunteers trying to support
>   our users around the globe.
>
> s/have/has
> s/trying to support/supporting

Thanks.

>   Join us for an incredible adventure!
>
> Sorry, this sounds silly to me. It's hacking on a text editor. If you
> enjoy hacking on text editors, you might find it enjoyable. If you
> don't, you probably won't. It's not finding the source of the Nile.
> (Ignore me if I'm just too negative and everyone else thinks this is fine.)

Maybe "Happy hacking!"?

>   You can find questions from mailing lists (like @uref{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs,help-gnu-emacs} and
>   @uref{https://lists.gnu.org/mailman/listinfo/help-emacs-windows,help-emacs-windows}), newsgroups (like comp.emacs and
>   gnu.emacs.help), websites (like @uref{http://stackoverflow.com/questions/tagged/?tagnames=emacs&sort=newest,Stack Overflow}), and IRC channels
>   (like @verb{~#emacs~} and @verb{~#gnus~} on Freenode).
>
> Maybe you want to mention that gnu.emacs.help == help-gnu-emacs

We can mention https://savannah.gnu.org/mail/?group=emacs here and add
information about IRC and StackOverflow (not sure whether it is
considered as advertising).

>   Rather than trying to figure out the user's problem by yourself
>   every time, first search to see if it has come up before.  Try to
>   search the Emacs manuals before anything else.  If the manuals
>   don't have your answers, you can use other sources.
>
> "Do the work people are too lazy to do for themselves."
>
>   If you find out the solution, consider adding it to the Emacs FAQ.
>
> The Emacs FAQ is kind of useless IMO.

You've mentioned it here:
http://debbugs.gnu.org/cgi/bugreport.cgi?bug=13401#14

But this is exactly the reason why we should improve it.  (Or obsolete
it?)

>  This advice seems oddly out of place, because while anyone can do the
> previous steps you've outlined till now, this one needs commit rights.

Can we move it later in this guide?

>   Be nice.  If you feel that a post has crossed the line, report
>   it to the Emacs maintainers.
>
> No. This is a) obvious, and not special to Emacs, so hardly needs to be
> mentioned IMO; and b) I do not want to get mails from people complaining
> that someone was mean to them on Stack Overflow or wherever. Report it
> to whoever moderates the communication medium you are using (if a
> mailing list, this is the list owner). If no-one does, ignore the
> offending party and move on.

Sounds fine to me, I'll improve it.

>    Subscribing to the
>    @uref{http://lists.gnu.org/mailman/listinfo/emacs-devel,emacs-devel}
>    mailing list is a good idea. It's a mailing list for communications
>    among Emacs developers.
>
> There's zero need to subscribe to this unless you are interested in
> Emacs development. If you just want to _use_ Emacs, then you can ignore
> this list.

Maybe a better version:

  If you are interested in the development of GNU Emacs, you can
  subscribe to the
  @uref{http://lists.gnu.org/mailman/listinfo/emacs-devel,emacs-devel}
  mailing list. It's a mailing list for communications among Emacs
  developers.


>   Don't post chain letters, marketing messages or other types of
>   non-topical spam.
>
> Obviously. What does this have to do with contributing to Emacs?

It can be moved to: https://savannah.gnu.org/mail/?group=emacs.  (If
Savane supports.)


>   Or validate web pages of Emacs.
> Not clear what this means.

A validator is a software program that can check your web pages against
the web standards.  See: http://validator.w3.org/

>   If you would like to help pretest Emacs releases to assure they work
>   well, or if you would like to work on improving Emacs, please contact
>   the maintainers at @email{emacs-devel@@gnu.org,emacs-devel@@gnu.org}. A
>   pretester should be prepared to investigate bugs as well as report them.
>
> There is zero need to mail this list if you want to pretest Emacs.
> Just do it.

It is copied from doc/emacs/trouble.texi.  Maybe we can remove it.

>   If you know HTML/CSS, you can contribute to the web pages of
>   Emacs and GNU ELPA.
>
> There is very little to do here IMO. Most of the Emacs web-pages are
> static or generated from Texinfo.

Agreed.  But since it does not occupy much space, IMHO it can be
reserved.

>   If you know C, you can contribute to a number of low-level
>   libraries
>
> Seems an odd statement.
>
>   and help us write Emacs primitives.
>
> Could be phrased better.

Do you have a better suggestion?  (Sorry for my poor English.)

>   Porting to new platforms is also useful.
>
> This comes up almost never, and is unlikely to be suitable for casual
> contributors, so hardly seems worth mentioning.

+1

>   If you think of new features to add to @verb{~etc/TODO~}, please
>   suggest them too.
>
> Not the best way to phrase it. If people think of new features, they
> should be reported as wishlist bugs. (But what we really need are people
> to implement ideas, not sit around brainstorming.)

I'll improve it.

>   Before contributing a new feature to Emacs, you should check to
>   make sure that the feature isn't already available.  (See @uref{http://lists.gnu.org/archive/html/emacs-devel/2013-04/msg00180.html,this thread}.)
>
> I have no idea why you link to that thread.

This is an example of duplicated implementations of the same feature.

>   For example, typing @verb{~M-x apropos <RET> humor <RET>~} lists
>   all functions and variables containing the string @verb{~humor~}; typing
>   @verb{~M-x list-packages~} command connects to the GNU ELPA
>   (@uref{http://elpa.gnu.org}) ("Emacs Lisp Package Archive") server and
>   fetches the list of additional packages that it offers.  These are
>   GNU packages that are available for use with Emacs, but are
>   distributed separately.  It is also possible that the package is on
>   your system, but has not been loaded.  To see which packages are
>   available for loading, look through your computer's Lisp directory.
>
> In all honesty, this could be summarized as "do a web search before
> spending time implementing something that already exists".

Sounds fine.  This guideline is the answer to questions like "how to
find a (existing) feature?".

>   Think carefully about whether your change requires updating the
>   documentation.  If it does, you can either do this yourself or add
>   an item to the NEWS file.
>
> Now you've suddenly jumped to stuff that is only relevant to people with
> commit rights.

Agreed.  The structure of this document needs many changes.

>   If you document your change in NEWS, please mark the NEWS entry
>   with the documentation status of the change: if you submit the
>   changes for the manuals, mark it with @verb{~+++~}; if it doesn't need to
>   be documented, mark it with @verb{~---~}; if it needs to be documented,
>   but you didn't submit documentation changes, leave the NEWS entry
>   unmarked.
>
> Now you are just copying stuff from NEWS.

A pointer is better, can you give a suggestion?

>   @footnote{These marks are checked by the Emacs maintainers to make
>   sure every change was reflected in the manuals.}
>
> If you are committing stuff to that file, you ARE the Emacs maintainers.
> Ie, everyone should think about documentation, rather than farming it out
> to some other sucker.

Sorry but I can't understand this paragraph, do you mean the paragraph
above should be removed?

>   They should follow our usual standards for web pages:
>
> I honestly can't think of a single case in the past ten years where
> someone has contributed a web page to Emacs, so I just can't see how
> this relevant to anyone. I assume it is mainly cribbed from
> http://www.gnu.org/server/fsf-html-style-sheet.html, so why not just
> refer to that rather than copying it?

I'll do some cleanup here.

>   @node Some Coding Conventions
>
> May as well just refer to the relevant section of the elisp manual
> rather than reproduce pieces of it.

+1

>   You can design themes, icons and web pages for Emacs.
>
> Themes ok, but what icons do we need?

Different icons for different themes.

> Again, I don't think web-pages design is needed (maybe this is my
> failing and there is lots that could be done here).

Well, most work can (and should) be done by GNU Webmaster team.  But
AFAIK the whole elpa.gnu.org (web page) is maintained by us, so it can
be improved by Emacs developers.

>   Proof-reading the manuals and man pages.  That's also a great way
>   to learn more about Emacs.  This is usually done together with
>   reading the NEWS file to make sure that the manual has been
>   updated.
>
> I'd lose the second sentence.

Why?  Sorry but I cannot agree with you here.

>   Generally the manual gives a bit less details but more background/context.
>
> Not sure I agree.

I'll remove it.

>   In Emacs tradition, we treat "point" as a proper name when it
>   refers to the current editing location.  It should not have an
>   article.  Thus, it is incorrect to write, "The point does not
>   move".  It should be, "Point does not move".  If you see "the
>   point" anywhere in Emacs documentation or comments, referring to
>   point, please fix it.
>
> This is just cribbed from admin/notes/documentation.
> Unless you want this to be the absolute definitive reference for Emacs
> coding, I can't see the point in mentioning such a dry, technical detail
> here.
>
>   Antinews is useful.
>
> (I disagree.) Again, this is just cribbed from admin/notes/documentation.
> I cannot see the point in mentioning this here. (One poor sucker has to
> try and update it just before a release, apart from that it's largely
> irrelvant.)

I'll add a pointer to admin/notes/ and do some cleanup here, thanks.

>   Emacs should not recommend, promote, or grant legitimacy to the use of
>   any non-free program. We can’t stop some people from writing
>   proprietary programs, or stop other people from using them, but we can
>   and should refuse to advertise them to new potential customers, or to
>   give the public the idea that their existence is ethical.
>
> I cannot see the relevance of this (copied from GNU standards) to your
> guide.

It's about documentation writing.  However, I'll remove it since there
is already a pointer to the GNU Coding Standards.

>   Never introduce new terminology in the middle of a complex
>   description, where each successive sentence builds upon what the
>   preceding ones said.  Always use @emph{exactly} the same words as in
>   the preceding sentences.
>
> This is just copied from a recent emacs-devel posting. Not sure it
> really fits.

Although it is not specific to Emacs, I think it is a useful tip for doc
writing.

>   Good spelling is encouraged.
>
> No, correct spelling and grammar is required, just like correct code is.
> But if you implement some new feature and your English is not best, it
> is much better if you at least try to document it, and ask for help with
> polishing, rather than leave someone else to do all the work.

I'll improve it, thanks.

>   Sentences should start with an uppercase letter.
>
> This is just the normal rule of English.

But many people do not respect it.

>   Don't mention in Antinews too many features absent in old versions.
>
> I imagine this is just copied from somewhere. It has no relevance to
> 99.99+% of people, so why mention it at all.

admin/notes/documentation.  I'll remove it.

>   To indicate possession, write Emacs's rather than Emacs'.  See
>   @uref{http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00649.html}
>
> True, but tedious.

I don't think so.  I think it's useful, not tedious.  Maybe the @uref
can be removed.

>   When you have all these pieces, bundle them up in a mail message and
>   send it to the developers. Sending it to
>   @email{bug-gnu-emacs@@gnu.org,bug-gnu-emacs@@gnu.org} (which is the
>   bug/feature list) is recommended, because that list is coupled to a
>   tracking system that makes it easier to locate patches. If your patch
>   is not complete and you think it needs more discussion, you might want
>   to send it to @email{emacs-devel@@gnu.org,emacs-devel@@gnu.org}
>   instead. If you revise your patch, send it as a followup to the
>   initial topic.
>
> Copied from etc/CONTRIBUTE, missing the introductory sentence about
> "several pieces", therefore doesn't really make sense.

I'll remove them and make a pointer to etc/CONTRIBUTE.

>   If installing changes written by someone else, make the ChangeLog entry
>   in their name, not yours. There is no need to make change log entries
>   for files such as NEWS, MAINTAINERS, and FOR-RELEASE.
>
> Not relevant to people without commit rights, ie to people just
> submitting patches.

My guide is not for every Emacs user.  However, it will be better if we
put the guidelines that needs write access into one node.

>   If your version of diff does not support these options, then get
>   the latest version of GNU Diff.
>
> I cannot believe this will be relevant for anyone.

Why?

>   or, as a last resort, uuencoded gzipped text.
>
> Irrelevant in this day and age.

Maybe we can also remove it from etc/CONTRIBUTE.

>    GNU Emacs Common Lisp Emulation.  See @ref{Top,,,cl,}.
>
> Hardly seems relevant for casual contributors.
>
>   CC Mode.
>    [...]
>   @uref{http://cedet.sourceforge.net/,CEDET}.  CEDET is a
>    [...]
>   @item  @uref{http://www.emacswiki.org/emacs/Icicles,Icicles}.
>
> I can't see the point of mentioning these.
>
>   Tags Tables.  See @ref{Tags,,,emacs,}.
>
> Can't see the relevance of this either.

They are very useful for programming in Emacs Lisp.

>    @uref{http://developer.gnome.org/gtk3/unstable/,GTK+ 3 Reference
>    Manual}, since GTK+ is the default X toolkit in GNU Emacs.
>
> Can't see the point. Obviously you read that if you are working with the
> Emacs Gtk toolkit integration, and don't need to be told it exists, and
> if you aren't, you don't.
>
>   @uref{http://www.libtiff.org/libtiff.html,Using The TIFF Library}
>
>   @uref{http://giflib.sourceforge.net/intro.html,Introduction to GIFLIB}
>
> Irrelevant IMO.

I'll remove them.

>   @item GNU build system. It helps Emacs developers make Emacs source
>   code portable to many Unix-like
>   systems.@footnote{@uref{http://www.gnu.org/software/autoconf
>   /manual/index.html}}@footnote{@uref{http://www.gnu.org/software/automake/manual/automake.html}}@footnote{@uref{http://www.gnu.org/software/gnulib/manual/}}
>
> Irrelevant unless you are working on that stuff, else obvious.
>
>    @item
>   @uref{http://ximbiot.com/cvs/manual/stable,HTML Cederqvist for CVS
>   stable release}.  The web pages of Emacs are kept in a CVS repository.
>
> Irrelevant to almost everybody.
>
>   @item @uref{http://www.gnu.org/software/make/manual/,GNU Make Manual}.
>   Make is a tool which controls the generation of executables and other
>   non-source files of Emacs from the source files.
>
> Irrelevant unless you are working on that stuff, else obvious.

E.g., I want to add this document to Emacs repo, but it needs knowledge
of GNU Make and GNU Texinfo (makeinfo).

>   @uref{http://gcc.gnu.org/onlinedocs/,GCC online documentation}. The
>   GNU Comp iler Collection (GCC) is a compiler system produced by the
>   GNU Project supporting various programming languages.
>
> Irrelevant/obvious.
>

"I want to build Emacs, but I don't know what does
`--enable-link-time-optimization' and `--enable-gcc-warnings' mean."

>   @item @uref{http://www.gnu.org/software/guile/manual/,GNU Guile
>   Reference Manual}. Guile, a dialect of Scheme, is the native language of
>   the GNU standard extension language interpreter.
>
> Irrelevant unless you are working on that stuff, else obvious.

I'll remove it.

>   @item @uref{http://www.gnu.org/software/grep/manual/,GNU Grep Manual}.
>   The @verb{~grep~} command searches one or more input files for lines
>   containing a match to a specified pattern. It is a very useful tool and
>   often used when developing Emacs.
>
> This is the point at which I begin to think I'm coming at this from
> totally the wrong perspective, because I really can't see the point of
> linking to the grep manual in a "how to contribute to Emacs" guide.

I'll remove it.  (I link to the grep manual because grep is really
useful when developing Emacs, and I think (info "(emacs) Grep
Searching") is poorly written.)

>   @menu
>   * How to report a bug?::
>   * How to comment on a bug?::
>   * How to close a bug?::
>   * How to set bug meta-data?::
>   @end menu
>
> Pretty sure all this is just copied from elsewhere.
> I'm not sure of the value of having everything in one massive document.

admin/notes/bugtracker

>   If you want to Cc someone, use an @verb{~X-Debbugs-CC~} header instead.
>
> Irrelevant for the vast majority of people.

I'll remove it.

>   @node Copyright
>   @chapter Copyright
>
> Mainly copied from etc/CONTRIBUTE.
>
>   Every non-trivial file distributed through the Emacs repository
>   should be self-explanatory in terms of copyright and license.
>
>   The definition of triviality is a little vague[...]
>
>    Legal advice says that we could, if we wished, put a license notice[...]
>
> I don't think any of these details belong here.

I'll remove them.

>   @node Emacs repositories
>   @chapter Emacs repositories
>   There are three official Emacs repositories: @uref{http://bzr.savannah.gnu.org/lh/emacs/,Bazaar}, @uref{http://web.cvs.savannah.gnu.org/viewvc/?root=emacs,CVS}, and @uref{http://git.savannah.gnu.org/cgit/emacs.git,Git}.
>
> I disagree. The offical repo is Bazaar. (There is a read-only Git
> mirror, and the web pages live in CVS for technical reasons, and are not
> relevant to most people.)

I had thought about it before I wrote this sentence.  I think "official"
means it is provided by the emacs group in Savannah.

>     * Building Emacs::
>
> Read INSTALL? Do you really want to cover this here as well?

No, just a quick guide.  (It could say, "See INSTALL for detail".)

>   @node Emacs Directory Tree
>
> Copied from README and <subdir>/README. Seems like totally pointless
> duplication.

I'll change it to pointer(s).

>   @item
>   Each commit should correspond to a single change (whether spread
>   over multiple files or not).
>
> Copied from admin/notes/commits. Why not just reference it rather than
> duplicate it?

I'll change it.

>   @item
>   For historical interest only, here is an old-style advice for CVS logs:
>
> Seriously, why are you copying even this old stuff?

I'll remove it.

>   @item
>   elpa
>   The GNU Emacs package archive, at elpa.gnu.org, is managed using a
>   Bzr branch named "elpa", hosted on Savannah.  To check it out:
>
> Copied from admin/notes/elpa.

I'll remove it.

>   @item
>   You should identify each release with a pair of version numbers, a
>   major version and a minor.
>
> Who is this for?

I'll remove it.

>   @item
>   Non-source files that might actually be modified by building and
>   installing the program should @emph{never} be included in the
>   distribution.
>
> Who is this for?

For the guys who write build rules for Emacs.

>   @item
>   +1
>   The shortest way in the geek world to say "I agree with this" or
>   "This is a great idea".
>
> Annoying as hell, adds nothing, don't do it.

I'll remove it.

>   @item
>   DVCS
>
> Hardly seems relevant. I'm not sure what the point of any of these items
> are, to be honest. GSoC, IDE, IRC, UTC?! Why are you trying to explain
> these terms here?

Sorry, some terms here are my testing stuff.  I forgot to remove them.

BTW we can add a troubleshooting node, and even a refcard for Emacs
hackers.

It seems that there's too much stuff to fix.  Maybe we create a
contribute-guide branch...  (So we can do drafting, formatting,
submitting, reviewing, approving, distributing, repositing, tracking...
I can't fix all of them in the near future.)  And I'm thinking about
whether the new guide is linear or branching.

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