# HG changeset patch
# User JD Walsh <jdwalsh03@gmail.com>
# Date 1414850916 14400
# Node ID 544d051b45e48724f358750028d1b49dd7265af4
# Parent  0c81f22bc32bf7c15273c9161d4c7cb00167c9ae
Added more details to `developers.html' page

diff -r 0c81f22bc32b -r 544d051b45e4 htdocs/developers.html
--- a/htdocs/developers.html	Tue Oct 28 18:03:04 2014 +0000
+++ b/htdocs/developers.html	Sat Nov 01 10:08:36 2014 -0400
@@ -14,7 +14,7 @@
   <link rel="shortcut icon" href="favicon.ico" />
   </head>
   <body onload="javascript:fix_top_menu();">
-  <div id="top-menu" class="menu"> 
+  <div id="top-menu" class="menu">
    <table class="menu">
       <tr>
         <td style="width: 90px;" class="menu" rowspan="2">
@@ -28,7 +28,7 @@
       </tr>
       <tr>
         <td class="menu">
-          
+
  <a href="index.html" class="menu">Home</a> &middot;
  <a href="packages.php" class="menu">Packages</a> &middot;
  <a href="developers.html" class="menu">Developers</a> &middot;
@@ -45,59 +45,449 @@
   </div>
 <div id="content">
 
-
 <h2>Contributing to Octave Forge</h2>
 
 <p>
-GNU Octave (aka Octave core) provides the core language, while Octave Forge
-provides packages for it.  For example, the image, control, signal, and
-statistics packages are part of Octave Forge.
+GNU Octave (a.k.a. Octave core) provides the core language, while Octave Forge
+provides packages for it.  For example, the <i>image</i>, <i>control</i>,
+<i>signal</i>, and <i>statistics</i> packages are part of Octave Forge.
 </p>
 
 <p>
-For contributions to Octave core please see
-<a href="http://www.gnu.org/software/octave/get-involved.html">it's page</a>.
-To contribute to Octave Forge, please read on.
+For contributions to Octave core please see its <a
+href="http://www.gnu.org/software/octave/get-involved.html">Octave Developers
+Page</a>. To contribute to Octave Forge, please read on.
 </p>
 
-<h2>Contribute to existing packages</h2>
+<h3>Contributing to existing packages</h3>
 
 <p>
-Each Octave Forge packages (with exception of some old packages) have their
-repository.  Most use mercurial although a few prefer git.  If you wish to
-contribute to an Octave Forge, you must first clone the package first.  You
-can see the list of repositories
-<a href="http://sourceforge.net/p/octave/_list/hg">here</a> and
-<a href="http://sourceforge.net/p/octave/_list/git">here</a>.
+Each Octave Forge package (with exception of some old packages) has its own
+repository. Most use <a href="http://en.wikipedia.org/wiki/Mercurial">Mercurial
+</a> although a few prefer <a
+href="http://en.wikipedia.org/wiki/Git_%28software%29">Git</a>. In both cases,
+to contribute to an Octave Forge package:
+</p>
+
+<ul>
+  <li>
+    Set up the version control system for the package (unless already in use),
+  </li>
+  <li>
+    Clone the package,
+  </li>
+  <li>
+    Create a patch, and
+  </li>
+  <li>
+    Submit it to the correct tracker: the <a href="http://savannah.gnu.org/bugs/?func=additem&group=octave">bug tracker
+    </a> if it fixes a bug, otherwise the <a href="http://savannah.gnu.org/patch/?func=additem&group=octave">
+    patch tracker</a>.
+  </li>
+</ul>
+
+<p>
+For more details on these steps, see below.
+</p>
+
+<h4>Setting up Mercurial</h4>
+
+<p>
+Mercurial is part of the software repository for most Linux distributions. For
+other systems, go to <a href="http://mercurial.selenic.com/downloads">Mercurial
+downloads</a>. Specific installation details depend on the operating system,
+version, and flavor chosen.
 </p>
 
 <p>
-The rest of the process is the same as Octave core.  After cloning, create
-a patch, submit it to the
-<a href="https://savannah.gnu.org/patch/?func=additem&group=octave">patch tracker</a>,
-and wait for it to be reviewed.  If you prefer, you can also host your clone
-of the package wherever you prefer and ask for a pull a request on the patch
-tracker.
+Once Mercurial is installed, it may be necessary to create a configuration file
+containing a user name. On Linux distributions, this configuration file is
+stored in a file named </i>.hgrc</i> in the home directory. On Windows, it is
+typically stored in the home directory as <i>Mercurial.ini</i>. If the file does
+not exist, create an empty text document with the correct name and location, and
+add the following lines:
+</p>
+
+<pre>
+[ui]
+username = <span style="color: #800000;"><i>Your Name</i></span> &lt;<span
+style="color: #800000;"><i>you&#64;email.com</i></span>&gt;
+</pre>
+
+<h4>Setting up Git</h4>
+
+<p>
+Git is part of the software repository for most Linux distributions. For other
+systems, go to <a href="http://git-scm.com/downloads">Git downloads</a>.
+Specific installation details depend on the operating system, version, and
+flavor chosen.
 </p>
 
 <p>
-You can also submit a simple patch or a new modified file but that will
-increase the review and acceptance time a lot.
+Once Git is installed, it may be necessary to set up a user name. This is done
+with the commands:
 </p>
 
-<h3>New packages</h3>
+<pre>
+$ git config --global user.name &quot;<span style="color:
+#800000;"><i>Your Name</i></span>&quot;
+$ git config --global user.email <span style="color:
+#800000;"><i>you&#64;email.com</i></span>
+</pre>
+
+<h4>Cloning a package with Mercurial</h4>
 
 <p>
-If you want to contribute with a new package, you should mention it on the
-maintainers mailing list.
+Cloning a package requires knowing the package name and location. SourceForge
+maintains a list of packages that use Mercurial at <a
+href="http://sourceforge.net/p/octave/_list/hg">Mercurial repositories</a>. Each
+Mercurial repository is stored at <tt>http://hg.code.sf.net/p/octave/<span
+style="color: #800000;"><i>packagename</i></span></tt> where <tt>packagename
+</tt> is the name given on the repository list. To clone a package, type the
+command
 </p>
 
-<h3>Project history</h3>
+<pre>
+$ hg clone http://hg.code.sf.net/p/octave/<span style="color:
+#800000;"><i>packagename</i></span> octave-<span style="color:
+#800000;"><i>packagename</i></span>
+</pre>
 
 <p>
-Octave Forge was originally an Octave distribution.  There was no individual
-packages and everything was a single repository, everything released at the
-same time.  The original distribution had 3 parts, main, extra, and non-free.
+This will download the most recent version of the package into the current
+directory.
+</p>
+
+<h4>Cloning a package with Git</h4>
+
+<p>
+Like with Mercurial, the first step is finding the package name and location.
+SourceForge maintains a list of <a
+href="http://sourceforge.net/p/octave/_list/git">Git repositories</a>. Each Git
+repository is stored at <tt>http://git.code.sf.net/p/octave/<span style="color:
+#800000;"><i>packagename</i></span></tt> where <tt>packagename</tt> is the name
+given on the repository list. To clone a package, type the command
+</p>
+
+<pre>
+$ git clone http://git.code.sf.net/p/octave/<span style="color:
+#800000;"><i>packagename</i></span> octave-<span style="color:
+#800000;"><i>packagename</i></span>
+</pre>
+
+<p>
+This will download the most recent version of the package into the current
+directory.
+</p>
+
+<h4>Creating a patch with Mercurial</h4>
+
+<p>
+After cloning the most recent version of the package, make your desired changes
+to the package code. <b>Make sure new files include a <a href="#copyright">
+copyright notice</a>.</b> Once all changes are complete, in the main package
+folder:
+<ul>
+  <li>
+    Update the working directory with
+<pre>
+$ hg up
+</pre>
+  </li>
+
+  <li>
+    Commit changes with
+<pre>
+$ hg ci
+</pre>
+    This will start an editor asking for a commit message. The message should be
+    a one-line description, followed (if necessary) by an empty line, and then
+    a more detailed description. If the patch fixes a reported bug, put
+    &quot;<tt>(bug &#35;<span style="color: #800000;"><i>XXXXX
+    </i></span>)</tt>&quot; in the first line of the commit message, where
+    <tt>XXXXX</tt> is reference number of the bug.
+  </li>
+
+  <li>
+    Export the changes to a file with the command
+<pre>
+$ hg export -r tip -o <span style="color:
+#800000;"><i>patchname</i></span>.patch
+</pre>
+    where <tt>patchname</tt> is the desired name for the patch file.
+  </li>
+
+</ul>
+</p>
+
+<h4>Creating a patch with Git</h4>
+
+<p>
+After cloning the most recent version of the package, make your desired changes
+to the package code. <b>Make sure new files include a <a href="#copyright">
+copyright notice</a>.</b> Moving or renaming files must be done using
+</p>
+
+<pre>
+$ git mv <span style="color: #800000;"><i>filename</i></span> <span
+style="color: #800000;"><i>newlocation</i></span>
+</pre>
+
+<p>
+and removing them must be done using
+</p>
+
+<pre>
+$ git rm <span style="color: #800000;"><i>filename</i></span>
+</pre>
+
+<p>
+for Git to recognize those changes. Once all changes are complete, in the main
+package folder:
+</p>
+
+<ul>
+
+  <li>
+    Add any newly created files with
+<pre>
+$ git add .
+</pre>
+  </li>
+
+  <li>
+    Commit changes with
+<pre>
+$ git commit -m &quot;<span style="color:
+#800000;"><i>commitmessage</i></span>&quot;
+</pre>
+    The <tt>commitmessage</tt> should be a one-line description, followed (if
+    necessary) by an empty line, and then a more detailed description. If the
+    patch fixes a reported bug, put &quot;<tt>(bug &#35;<span style="color:
+    #800000;"><i>XXXXX</i></span>)</tt>&quot; in the first line of the commit
+    message, where <tt>XXXXX</tt> is reference number of the bug.
+  </li>
+
+  <li>
+    Export the changes to a file with the command
+<pre>
+$ git format-patch -1 --stdout <span style="color:
+#800000;"><i>mypatch</i></span>.patch
+</pre>
+    where <tt>mypatch</tt> is the desired name for the patch file.
+  </li>
+
+</ul>
+</p>
+
+<h4>Submitting a patch</h4>
+
+Submission the same for both types of repository and identical to the process
+for Octave core. Submit the patch to either the <a
+href="http://savannah.gnu.org/patch/?func=additem&group=octave">patch tracker
+</a> or the <a href="http://savannah.gnu.org/bugs/?func=additem&group=octave">
+bug tracker</a>, and wait for it to be reviewed. Another option is to host a
+clone of the package wherever desired and request a pull on the patch tracker.
+It is also possible to submit a simple patch or a new modified file but that
+greatly increases the review and acceptance time.
+</p>
+
+<h3>Contributing new packages</h3>
+
+<p>
+If you want to contribute with a new package, mention this on the
+<a href="https://lists.gnu.org/mailman/listinfo/octave-maintainers">Octave
+maintainers mailing list</a>.
+</p>
+
+<h4>Making a package release</h4>
+
+<p>
+The details are very much dependent on the structure of the package.
+</p>
+
+<ul>
+
+  <li>
+    bump the Version number and Release date in the package DESCRIPTION file,
+    update the NEWS and INDEX file, and the version in configure.ac file.
+    Commit with &quot;maint: release x.y.z&quot;
+  </li>
+
+  <li>
+    tag the commit with <pre>hg tag &quot;release-x.y.z&quot;</pre>
+  </li>
+
+  <li>
+    run any bootstrap or autogen.sh script in the package.
+  </li>
+
+  <li>
+    produce a tarball of the package and take note of its md5 checksum:
+<pre>
+$ cd your-package-directory
+$ hg archive --exclude '.hg*' somewhere/pkgname-x.y.z.tar.gz
+$ md5sum somewhere/pkgname-x.y.z.tar.gz
+</pre>
+  </li>
+
+  <li>
+    test everything worked fine by installing the generated tarball
+<pre>
+&gt; pkg install somewhere/pkgname-x.y.z.tar.gz
+</pre>
+  </li>
+
+  <li>
+    make sure you have the latest version of the generate_html package
+<pre>
+&gt; pkg install -forge generate_html
+</pre>
+  </li>
+
+  <li>
+    generate the function reference HTML files with the command
+<pre>
+&gt; pkg load generate_html
+&gt; generate_package_html (&quot;pkgname&quot;, &quot;pkgname-html&quot;, &quot;octave-forge&quot;)
+</pre>
+  </li>
+
+  <li>
+    produce a tarball of the HTML, take note of its checksum and encode it with uuencode
+<pre>
+$ tar cvzf pkgname-html.tar.gz pkgname-html
+$ md5sum pkgname-html.tar.gz
+</pre>
+  </li>
+
+  <li>
+    Post the package, html docs and md5 checksums to the <a href="https://sourceforge.net/p/octave/package-releases/">package release
+    tracker</a> asking for review and upload it on the server. Once it's
+    accepted, an Octave Forge admin will upload it and make an announcement on
+    the mailing list.
+  </li>
+
+</ul>
+</p>
+
+<a name="copyright"></a>
+<h2>Copyright notices</h2>
+
+<p>
+Each file in Octave Forge must contain a copyright notice. Most of Octave Forge
+is released under the GNU <a href="http://www.gnu.org/licenses/gpl.html">GPL
+</a>. If you wish to do the same, insert the following text at the top of your
+file:
+</p>
+
+<pre>
+## Copyright (C) <span style="color: #800000;"><i>year</i></span> <span
+style="color: #800000;"><i>Your Name</i></span> &lt;<span style="color:
+#800000;"><i>you&#64;email.com</i></span>&gt;
+##
+## This program is free software; you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or
+## (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program; if not, see &lt;http://www.gnu.org/licenses/&gt;.
+</pre>
+
+<p>
+There are other popular open source licenses:
+</p>
+
+<ul>
+
+  <li>
+    <a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser GPL</a>
+  </li>
+
+  <li>
+    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
+    License</a>
+  </li>
+
+  <li>
+    <a href="http://www.opensource.org/licenses/artistic-license.html">Artistic
+    License</a>
+  </li>
+
+  <li>
+    <a href="http://www.opensource.org/licenses/bsd-license.html">BSD
+    License</a>
+  </li>
+
+</ul>
+
+<p>
+Consult
+<a href="http://www.opensource.org/licenses/index.html">opensource.org</a> for a
+comprehensive list of Open Source licenses.
+</p>
+
+
+<h2>For more information</h2>
+
+<ul>
+
+  <li>
+    The Octave Wiki has a detailed page about developing for Octave using <a href="http://wiki.octave.org/Mercurial">Mercurial<a>, including a simple
+    description of Mercurial queues.
+  </li>
+
+  <li>
+    The Octave Wiki also contains detailed <a href="http://wiki.octave.org/Commit_message_guidelines">commit message
+    guidelines</a>.
+  </li>
+
+  <li>
+    There is a wealth of useful information in the <a href="http://www.gnu.org/software/octave/doc/interpreter/index.html">GNU
+    Octave documentation</a>. In particular,
+    <ul>
+
+      <li>
+        <a href="http://www.gnu.org/software/octave/doc/interpreter/Test-and-Demo-Functions.html">Appendix B</a> describes the creation of test and demo
+        functions,
+      </li>
+
+      <li>
+        <a href="http://www.gnu.org/software/octave/doc/interpreter/Tips-and-Standards.html">Appendix C</a> offers tips and standards on writing
+        clean code, and
+      </li>
+
+      <li>
+        <a href="http://www.gnu.org/software/octave/doc/interpreter/Contributing-Guidelines.html">
+        Appendix D</a>, while primarily aimed at Octave core developers, gives
+        good information on creating source files and changesets (patches). It
+        also describes the use of Mercurial queues.
+      </li>
+
+    </ul>
+  </li>
+
+  <li>
+    The <a href="https://lists.gnu.org/mailman/listinfo/octave-maintainers">
+    Octave-maintainers mailing list</a> is another potential source of
+    information for developers. <b>Please only use this list if participating in
+    Octave development.</b>
+  </li>
+
+</ul>
+
+<h2>Project history</h2>
+
+<p>
+Octave Forge was originally an Octave distribution.  There were no individual
+packages and everything was a single repository, with everything released at the
+same time. The original distribution had 3 parts: main, extra, and non-free.
 An extra directory in the repository was also available for admin.
 </p>
 
@@ -115,74 +505,12 @@
 </p>
 
 <p>
-With the increase of use of distributed VCS, packages were slowly removed from
-the SVN repository and moved into individual mercurial repositories.  Not all
-packages have migrated, and only older packages, usually unmaintained exist
-there now.
+With the increase of use of distributed version control systems, packages were
+slowly removed from the SVN repository and moved into individual Mercurial
+repositories.  Not all packages have migrated, but only older packages, usually
+unmaintained, exist there now.
 </p>
 
-<h3>Making a package release</h3>
-
-<p>
-The details of this is very much dependent on the structure of the package.
-</p>
-
-<ul>
-  <li>
-    bump the Version number and Release date in the package DESCRIPTION file,
-    update the NEWS and INDEX file, and the version in configure.ac file.
-    Commit with "maint: release x.y.z"
-  </li>
-  <li>
-    tag the commit with <pre>hg tag "release-x.y.z"</pre>
-  </li>
-  <li>
-    run any bootstrap or autogen.sh script in the package.
-  </li>
-  <li>
-    produce a tarball of the package and take note of its md5 checksum:
-    <pre>
-$ cd your-package-directory
-$ hg archive --exclude '.hg*' somewhere/pkgname-x.y.z.tar.gz
-$ md5sum somewhere/pkgname-x.y.z.tar.gz
-    </pre>
-  </li>
-
-  <li>
-    test everything worked fine by installing the generated tarball
-    <pre>pkg install somewhere/pkgname-x.y.z.tar.gz</pre>
-  </li>
-
-  <li>
-    make sure you have the latest version of the generate_html package
-    <pre>pkg install -forge generate_html</pre>
-  </li>
-
-  <li>
-    generate the function reference HTML files with the command
-    <pre>
-pkg load generate_html
-generate_package_html ("pkgname", "pkgname-html", "octave-forge")
-    </pre>
-  </li>
-
-  <li>
-    produce a tarball of the HTML, take note of its checksum and encode it with uuencode
-    <pre>
-$ tar cvzf pkgname-html.tar.gz pkgname-html
-$ md5sum pkgname-html.tar.gz
-    </pre>
-  </li>
-
-  <li> Post the package, html docs and md5 checksums to the <a href="https://sourceforge.net/p/octave/package-releases/">package 
-release tracker</a> asking for review and upload it on the server. Once its accepted, an Octave Forge admin will upload and make
-the announcement on the mailing list.
-  </li>
-
-</ul>
-</p>
-
-
 <div id="sf_logo">
   <a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=2888&amp;type=1"
      width="88" height="31" style="border: 0;" alt="SourceForge.net Logo"/></a>
