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