# HG changeset patch
# User JD Walsh <jdwalsh03@gmail.com>
# Date 1414982926 18000
# Node ID f4448a464973ed818be6802f2cfe091228576d36
# Parent  0c81f22bc32bf7c15273c9161d4c7cb00167c9ae
Added details to developers.html page

diff -r 0c81f22bc32b -r f4448a464973 htdocs/developers.html
--- a/htdocs/developers.html	Tue Oct 28 18:03:04 2014 +0000
+++ b/htdocs/developers.html	Sun Nov 02 21:48:46 2014 -0500
@@ -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,230 @@
   </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>
+    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>
-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.
+For more details on these steps, see below.
 </p>
 
+<h4>Cloning a package</h4>
+
 <p>
-You can also submit a simple patch or a new modified file but that will
-increase the review and acceptance time a lot.
+Cloning a package requires knowing the package name and location. SourceForge
+maintains lists of packages that use <a
+href="http://sourceforge.net/p/octave/_list/hg">Mercurial repositories</a> and
+<a href="http://sourceforge.net/p/octave/_list/git">Git repositories</a>.
+
+<h4>Creating a patch</h4>
+
+<p>
+After cloning the most recent version of the package, make your desired changes
+to the package code. Once all changes are complete, in the main package
+folder:
 </p>
 
-<h3>New packages</h3>
+<ul>
+  <li>
+    Update the working directory,
+  </li>
+
+  <li>
+    Commit changes, and
+  </li>
+
+  <li>
+    Export the changes to a patch file.
+  </li>
+
+</ul>
+
+<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, you should mention it on the
-maintainers mailing list.
+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>
 
-<h3>Project history</h3>
+<h4>Making a package release</h4>
 
 <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.
+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>
+
+<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 +286,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>
