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

[Glenn Morris <rgm@gnu.org>]

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?