__HEADER__([[[Developer's Notes]]])

<h2>Contributing Code to the Gnu Octave Repository</h2>


<h3>Requirements</h3>
To contribute your .m files, C++, C, or Fortran code to the GNU Octave
Repository (octave-forge) you need to
<ul>
    <li> have an account on SourceForge,
    <li> be registered as an octave-forge developer,
    <li> have <a href="http://www.cvshome.org/">CVS</a>
        installed on the computer from which you
        will submit contributions, and
    <li> have the secure shell,
         <a href="http://www.openssh.com/"><tt>ssh</tt></a>, installed
         on your computer.
</ul>
The first two requirements are easy but may take a few days.  
If you don't already have one, request a SourceForge (SF) account
<a href="http://sourceforge.net/account/register.php"> here</a>.
To register as a developer send a request 
to the octave-forge mailing list 
<a href="mailto:octave-dev@lists.sf.net">octave-dev@lists.sf.net</a>.
Include a bit of information about the code
you plan to submit. 
Finally, if your computer runs linux or
FreeBSD, chances are good that both <tt>ssh</tt> and CVS are already 
installed on your system. 
If they aren't, 
you will need to find prebuilt packages for them or download their
source codes and build them.

<h3>Create a SF home directory</h3>
<p>
If you've never submitted code to a SourceForge project before,
create your home directory by
logging onto the octave-forge account with <tt>ssh</tt>:
<pre>
   $ ssh -l <FONT COLOR="#800000"><i>sflogin</i></FONT>  octave.cvs.sourceforge.net
   Password:  <FONT COLOR="#800000"><i>your SF password</i></FONT>
</pre>
Although SF will only show you a message-of-the-day screen then log
you out, this process has the useful side effect of creating a home
directory for you if one doesn't already exist.  Some CVS commands will fail
if you do not have a home directory on SF.

<h3>Download the latest octave-forge distribution</h3>
CVS expects the 
code you plan to submit to reside in a directory within the existing
octave-forge directory structure.
You will therefore need to download a copy of the latest octave-forge
distribution to work in.  Change directories to a place you want
to put the code, then issue the CVS <i>checkout</i>
(abreviated as 'co') command:
<pre>
   $ cd <FONT COLOR="#800000"><i>working_directory</i></FONT>
   $ export CVS_RSH=ssh
   $ cvs -d:ext:<FONT COLOR="#800000"><i>sflogin</i></FONT>@octave.cvs.sourceforge.net:/cvsroot/octave co octave-forge
</pre>

<h3>Where does your code belong?</h3>

Put your file(s) in a subdirectory under the <tt>octave-forge/</tt>
directory.  Here are some guidelines to help you decide where your
code belongs:
<ul>
	<li> <b><tt>admin/</tt></b><br>
	Contains files and scripts used to administer the octave-forge
	website and build the release files.  Nothing in here is needed
	by octave-forge users.

	<li> <b><tt>doc/</tt></b><br>
	Documentation for octave in general.  Documentation for specific
	packages goes into the <tt>doc/</tt> subdirectory of the individual package 
	directories.  There are no standards for documentation at this
	time.

	<li> <b><tt>extra/</tt></b><br>
	Packages which:
	<ul>     <li> are too narrow in scope for <tt>main/</tt>, or
	    <li> act as alternatives for functions in <tt>main/</tt>, or
	    <li> do not follow octave conventions (because they want
	     to retain compatibility with matlab for example), or
	    <li> are primarily developed elsewhere, or
	    <li> require patches to Octave, or
	    <li> are designed for older versions of Octave, or
	    <li> haven't been tested enough.
</ul>
	<li> <b><tt>main/</tt></b><br>
	Packages which may eventually be included in the main octave 
	distribution.  As such, they should follow Octave conventions.  
	The octave-forge CVS tree should be the primary development/release 
	site.  All functions should work with the latest Octave 
	interpreter without any special compilation switches or patches
	applied.

	<li> <b><tt>nonfree/</tt></b><br>
	Packages which are not freely modifiable and redistributable 
	with modifications, or which depend on code which is not 
	free.  This includes functions which only permit non-commercial 
	use and functions which must be kept together as a package.  
	Functions in all other directories must be freely redistributable 
	with modifications.  Functions in non-free must be freely 
	redistributable for non-commercial use.  Functions of unknown
	license should not be included anywhere, since no license implies
	default license implies no rights to redistribute.

	<li> <b><tt>packages/</tt></b><br>
	This is the target directory, where the source packages are placed. It
	is also the directory where the test code is run for each of the
	packages and where the source RPMs are automatically built. There
	should be no reason for the user to add files to this directory

</ul>

<h3>Add a copyright notice</h3>
<p>
Each file in octave-forge must contain a copyright notice.  
If you wish to release your
code under the 
GNU <a href="http://www.gnu.org/licenses/gpl.html">GPL</a>
, insert the following text at the top of your file:
<pre>
## Copyright (C) <FONT COLOR="#800000"><i>year</i></FONT>   <FONT COLOR="#800000"><i>Your Name</i></FONT>   &lt;<FONT COLOR="#800000"><i>your@preferred.email</i></FONT>&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 2 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, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
</pre>

Here are other popular open source licenses:
<ul>
    <li> <a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser GPL</a>
    <li> <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License</a>
    <li> <a href="http://www.opensource.org/licenses/artistic-license.html">Artistic License</a>
    <li> <a href="http://www.opensource.org/licenses/bsd-license.html">BSD License</a>
</ul>
Consult 
<a href="http://www.opensource.org/licenses/index.html">opensource.org</a>.
for a comprehensive list of Open Source licenses.

<h3>Package structure</h3>
<p>
Octave has evolved into a source repository is octave pacakges rather
than a package in itself. Each sub-directory is considered to be a
package and should respect Octave's package managers file layout.
<dl>
<dt>package/NOINSTALL
<dd>	This is an optional file, whose presence tells octave-forge
	that this package should be ignored. This is typically for
	packages that are kept for historical reasons.
<dt>package/DESCRIPTION
<dd>	This is a required file containing information about the
	package. It must contain the following fields
    <table border="1">
      <tr><td>Name:</td>
          <td>Name of the package</td></tr>
      <tr><td>Version:</td>
          <td>Version of the package</td></tr>
      <tr><td>Date:</td>

          <td>Date of last update</td></tr>
      <tr><td>Author:</td>
          <td>Original author of the package</td></tr>
      <tr><td>Maintainer:</td>
          <td>Maintainer of the package</td></tr>
      <tr><td>Title:</td>

          <td>A one line description of the package</td></tr>
      <tr><td>Description:</td>
          <td>A one paragraph description of the package</td></tr>
      <tr><td>Categories:</td>
           <td>Optional keyword describing the package
            (if no INDEX file is given this is mandatory)</td></tr>
      <tr><td>Problems:</td>

          <td>Optional list of known problems</td></tr>
      <tr><td>Url:</td>
          <td>Optional list of homepages related to the package</td></tr>
      <tr><td>Depends:</td>
          <td>A list of other octave packages that this package
	      depends on. This can include dependencies on particular
	      versions, which a format.
<pre>
	Depends: package (>= 1.0.0)
</pre>
	      Possible operators are <, <=, ==, >= or >. If the part
	      of the dependency in () is missing, any version of the
	      package is acceptable. Multiple dependencies can be
	      defined either as a comma separated list or on separate
	      Depends lines.</td></tr>
      <tr><td>License:</td>
          <td>An optional short description of the used license 
              (e.g. GPL version 2 or newer). This is optional
              since the file COPYING is mandatory.</td></tr>
      <tr><td>SystemRequirements:</td>
          <td>These are the external install dependencies of the package
	      and are not checked by the package manager. This is here as a
              hint to the distribution packager. They follows the same
	      conventions as the Depends keyword.</td></tr>
      <tr><td>BuildRequires:</td>
      	  <td>These are the external build dependencies of the package
	      and are not checked by the package manager. This is here as
	      a hint to the distribution packager. They follows the same
	      conventions as the Depends keyword. Note that in
	      general, packaging systems such as rpm or deb and
	      autoprobe the install dependencies from the build
	      dependencies, and therefore the often a BuildRequires
	      dependency removes the need for a SystemRequirements
	      dependency.</td></tr>
    </table>
    The file format should be something like this:
    </p>
    <ul>
      <li>Lines starting with # are comments</li>

      <li>Lines starting with a blank character are continuations
        from the previous line.</li>
      <li>Everything else is of the form NameOfOption: ValueOfOption</li>
    </ul>
	The developer is free to add additional arguments to the
        DESCRIPTION file for their own purposes. Note that
        octave-forge contains an automatic build process of RPMs and
        DEBs from the octave packages, and this relies on the
        DESCRIPTION files being correctly formatted. One further
        detail to aid the packager is that the SystemRequirments and
        BuildRequires keywords can have distribution dependent
        section, and the automatic build process will use these. An
        example of the format of this is
<pre>
	BuildRequires: libtermcap-devel [Mandriva] libtermcap2-devel
</pre>
	where the first package name will be used as a default and if
        the RPMs are built on a Mandriva distribution, then the second
        package name will be used instead.
<dt>package/COPYING
<dd>	This is a required file containing the license of the package.
<dt>package/INDEX
<dd>	This is an optional file describing the functions provided by
	the package. If this file is not given then one with be
	created automatically from the functions in the package and
	the Categories keyword.
<dt>package/PKG_ADD
<dd>	An optional file that includes commands that are run when the
        package is added to the users path. Note that PKG_ADD
        directives in the source code of the package will also be
        added to this file by the octave package manager. Note that
        symbolic links are to be avoided in packages, as symbolic
        links do not exist on some file systems, and so a typical use
        for this file is the replacement of the symbolic link
<pre><i>
ln -s foo.oct bar.oct
</i></pre>
	with an autoload directive like
<pre><i>
autoload ('bar', which ('foo'));
</i></pre>
<dt>package/PKG_DEL
<dd>	An optional file that includes commands that are run when the
        package is removed from the users path. Note that PKG_DEL
        directives in the source code of the package will also be
        added to this file by the octave package manager.
<dt>package/Makefile
<dd>	This is an optional file that is for the use of Octave-Forge
        only. It allows the developer to have fine control over
        exactly what is included in the package and anything that
        needs to be done before or after the package is built. The
        default Makefile is
<pre>
<i>
include ../../Makeconf
include ../../pkg.mk

PKG_FILES = COPYING DESCRIPTION $(wildcard INDEX) $(wildcard PKG_ADD) \
	$(wildcard PKG_DEL) $(wildcard post_install.m) \
	$(wildcard pre_install.m)  $(wildcard on_uninstall.m) \
	$(wildcard inst/*) $(wildcard src/*) $(wildcard doc/*) \
	$(wildcard bin/*)

pre-pkg/%::
	# Do nothing prior to packaging

post-pkg/%::
	# Do nothing post packaging
</i>
</pre>
	which packages all of the required and existing optional files
	and directories discussed here. 
<dt>package/pre_install.m
<dd>	This is an optional script that is run prior to the
        installation of a package.
<dt>package/post_install.m
<dd>	This is an optional script that is run after the
        installation of a package.
<dt>package/on_uninstall.m
<dd>	This is an optional script that is run prior to the
        de-installation of a package.
<dt>package/doc
<dd>	An optional directory containing documentation for the
	package. The files in this directory will be directly
	installed in a sub-directory of the installed package for
	future reference. Note that any html files included in this
	directory will be included in the octave-forge package
	webpages. To include images or arbitrary files use a
	sub-directory html/ in this directory.
<dt>package/inst
<dd>	An optional directory containing any files that are directly
	installed by package. Typically this will include any m-files.
<dt>package/bin
<dd>	An optional directory containing files that will be added to
	the Octave EXEC_PATH when the package is loaded. This might
	contain external scripts, etc, called by functions within the
	package.
<dt>package/src
<dd>	An optional directory containing code that must be 'built' prior
	to the packages installation. If this directory contains a
	file autogen.sh, and package/Makefile does not exist, this
	script will be called prior to the packaging. The Octave
	package manager will execute "./configure" in this directory
	is this script exists, and will then call "make" if a file
	"Makefile" exists in this directory. "make install" will
	however not be called. If a file called "files" exist all
	files listed there will be copied to the "inst" directory, so
	they also will be installed. If the "src/files" file doesn't
	exist "src/*.m" and "src/*.oct" will be copied to
	"inst". There are two reasons for doing this rather than "make
	install":
    <ul>
      <li>At some point, it would be good to have a 'build' command
      that creates a binary version of a package. I don't mean a .dep
      or a .rpm, but an octave package, in which everything has been
      compiled. 
      <li>At some point in the future, somebody clever might tell us
      that the package system should run in a sandboxed environment
      for security reasons.
    </ul>
</dl>

<h3>Submit your code!</h3>
You are now ready to upload your code to the Gnu Octave Repository.
Do this with two CVS commands--one to add a new
entry for your file in the octave-forge catalog, and a second command
to actually upload the file:
<pre>
   $ cvs add <FONT COLOR="#800000"><i>files</i></FONT>
   $ cvs commit <FONT COLOR="#800000"><i>files</i></FONT>
</pre>

After hitting the carriage return at the end of the commit command,
CVS will open your default editor so that you can enter comments about
the commit. The first time you commit a file the comment might be
something as simple as `Initial commit into CVS.' However, for all
subsequent commits please add meaningful comments that explain why
changes were made to the file since all comments will appear in the
changelog.  Try to gather related changes into one commit command.
<p>
Aside:  the default editor can be defined like so:
<pre>
   $ export EDITOR=<FONT COLOR="#800000">vim</FONT>
</pre>
<p>

If you are uploading an entire package, then put your directory into the
octave-forge tree and do the following:
<pre>
   $ cd octave-forge/main
   $ cvs add <FONT COLOR="#800000"><i>package</i></FONT>
   $ cvs commit <FONT COLOR="#800000"><i>package</i></FONT>
   $ cd <FONT COLOR="#800000"><i>package</i></FONT>
   $ cvs add *
   $ cvs commit *
</pre>

You may find it easier to use the import command, especially if your
package contains subdirectories.  In this case, you should not put
your directory into the octave-forge tree.  Instead, change to the
root of your package tree and enter the following:
<pre>
   $ cd <FONT COLOR="#800000"><i>package</i></FONT>
   $ cvs -d:ext:<FONT COLOR="#800000"><i>sflogin</i></FONT>@octave.cvs.sourceforge.net:/cvsroot/octave import -m "<FONT COLOR="#800000"><i>package name</i></FONT>" octave-forge/<FONT COLOR="#800000"><i>main/package</i></FONT> <FONT COLOR="#800000"><i>sflogin</i></FONT> start
</pre>

You can then fetch the new package from octave-forge as follows:
<pre>
   $ cd octave-forge
   $ cvs -q update -d
</pre>

<p>
From time to time, you will need to synchronize with CVS:
<pre>
   $ cd octave-forge
   $ cvs -q update -d
</pre>
Each file will be listed with one of the following codes:
<ul>
<li> `?' for files you created didn't add and commit.
<li> `M' for files you modified but didn't commit.
<li> `C' for files which have unresolvable conflicts.  Look inside the file to
see what it was that couldn't be resolved.  It will be clearly marked, or you
can do a cvs diff on the file to highlight the conflict.
<li> `U' for files you haven't touched but are modified on the server.
<li> `P' for files you have modified in a way consistent with the modifications
on the server (?), e.g., because you submitted a patch for someone else to apply.
</ul>

<h3>Learn more about CVS</h3>
The few CVS commands shown here just scratch the surface of this
powerful versioning package.  If you become an active contributor
you will benefit from learning more CVS commands and understanding 
how CVS works.
The
<a href="http://cvsbook.red-bean.com/cvsbook.html">
CVS Book</a> is a great place to begin your exploration.

<h3>Join the developers' mailing list</h3>
Finally, consider joining the octave-forge developer's 
<a href="http://lists.sourceforge.net/lists/listinfo/octave-dev">
mailing list</a>.  It is very low traffic.  It is used to announce
pending releases of octave-forge and discuss issues related to
working with octave-forge.  Discussion of the functions in
octave-forge mostly occurs on the primary octave mailing lists.

__TRAILER__