Developers

If you want to contribute to an existing package, please contact the package maintainer directly. Contact information is given in the   list of packages.

If you want to contribute a new package, ask in  Octave Discourse for help.

Code

The source code for each Octave Forge package is on its own individual mercurial or git repository. To clone all package repositories locally, we provide a meta-repository  octave-forge.

The code of this website can be found in the repository  project-web.

Contributing to Octave Forge

GNU Octave (a.k.a. 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.

For contributions to Octave core please see its  Octave Developers Page. To contribute to Octave Forge, please read on.

Contributing to Octave Forge in general

If you'd like to make a general contribution, please contact the  maintainers mailing list.

Taking over maintenance of existing packages

Currently unmaintained packages are listed at our  packages page. However, this list might not be up-to-date. If you think you could help with maintenance of a particular package, please step forward and contact the last known package maintainer or the  maintainers mailing list.

Contributing to existing packages

Each Octave Forge package (with exception of some old packages) has its own code repository. Most use  Mercurial although a few prefer  Git. To contribute to a community-maintained package (those listed in the first group at the packages page):

1. Clone the package
2. Create a patch
3. Submit it to the bug tracker or to the patch tracker

To contribute to an external package (those listed in the second group at the packages page), contact the package maintainer for the suitable procedure. External packages might use an external repository for primary package development. In this case the repository at Octave Forge only gets updated during package release and you should look elsewhere for the current development branch of the package.

Clone the package

The  package list and the overview page of each package contain links to web interfaces of the respective code repositories. There, a command line example for cloning the repository is given.

Create a patch

After cloning the most recent version of the package, make your desired changes to the code. Many packages provide a maintainer Makefile and you can run the modified package locally with the command make run to test your changes in an interactive Octave session. Once all changes are complete:

1. Update the working directory
   hg pull && hg update / git pull
2. Commit changes
   hg commit / git commit
3. Export the changes to a patch file
   hg export -r tip / git format-patch -1 HEAD

Submit the patch

Submit it to either the  bug tracker if it fixes a bug, or to the  patch tracker if it adds new functionality. Then wait for it to be reviewed. If the package maintainer is known, please add her/his address in the field Mail Notification CC to speed up the review.

Alternatively, you may host a clone of the package repository wherever desired and request a pull on the patch tracker. This is especially useful for larger changes. It is also possible to submit a new modified file, but creating a patch as described above greatly increases the review and acceptance time.

Contributing new packages

If you want to contribute with a new package, mention this on the  maintainers mailing list. You should decide if you want your package to be community-maintained or external.

The general structure of a package is described in the  Octave manual. Additionally, in Octave Forge packages:

• Often a script src/bootstrap, e.g. to create src/configure, is included.
• General package documentation in the texinfo format may be included.
• A Makefile at the toplevel directory of the package is suggested, in particular to simplify the release procedure. A  template Makefile is available.
• The INDEX file needs special attention to enable checking for symbol uniqueness among packages and Octave.
  • Class methods, even for classdef based classes, should be listed as @class_name/method_name.
  • Namespaced functions or methods should be listed without a + prefix:

    namespace.[sub_namespace. ...]function
    namespace.[sub_namespace. ...]@class_name/method_name

  • If the package contains namespaces or classdef based classes, an INDEX file should be present.
  • If an INDEX file is present, it should contain all function names, at least one method of each class, and at least one namespaced function of each namespace.
• The duplicate checker at Octave Forge should be used to check if a symbol of the package is already defined by another package or by Octave. After installing your package and the generate_html package, you can use this interface:

  pkg load generate_html
  check_duplicates ("pkgname");

Octave Forge maintains an  example package, which provides possible solutions for some common problems. It is a work in progress. There are no releases for this package.

Making a package release

The details of the release procedure depend to some degree on the structure of the package.

• Check the Version number and Release date in the package DESCRIPTION file, update the NEWS and INDEX file, and the version in the configure.ac file, if present.
• Commit and push to the Octave Forge repository.
• For community packages, the released changeset will be tagged by the Octave Forge administrator who puts the release online. In external packages, the package maintainer is responsible for tagging the released changeset with release-x.y.z; this should be only done after the release has been accepted.
• Make sure you have the latest released version of the generate_html package

  pkg install -forge generate_html

• If possible, use the  template Makefile of Octave Forge to generate the tarballs for the package and its online documentation with make release. You may also customize this Makefile for your package or copy from a Makefile of another package with similar structure.
• The following steps are necessary in release generation, and are typically performed by make release:
  • Running any bootstrap file of your package.
  • Removing any created directories and files that should not be in the release.
  • Creating a tarball of the package and noting its md5 checksum. For Mercurial:

    cd your-package-directory
    hg commit  # if not already done
    hg archive --exclude '.hg*' somewhere/pkgname-x.y.z.tar.gz
    md5sum somewhere/pkgname-x.y.z.tar.gz

  • Testing that everything worked fine by installing the generated tarball:

    pkg install somewhere/pkgname-x.y.z.tar.gz

  • Generating HTML documentation with function references:

    pkg load generate_html
    generate_package_html ('pkgname', 'pkgname-html', 'octave-forge')

    As documented for  generate_package_html (), custom package documentation in the texinfo format can be included into the online documentation.
  • Generating a tarball of the documentation and noting its md5 checksum:

    tar cvzf pkgname-html.tar.gz pkgname-html
    md5sum pkgname-html.tar.gz

• Post the package and documentation tarballs to the  package release tracker, noting their md5 checksums. Once they are reviewed, accepted, and uploaded to the server, you can make an announcement at the mailing list.

For more information

• The Octave Wiki has a detailed page about developing for Octave using Mercurial, including a simple description of Mercurial queues.
• The Octave Wiki also contains detailed commit message guidelines.
• There is a wealth of useful information in the GNU Octave documentation. In particular,
  • Appendix B describes the creation of test and demo functions,
  • Appendix C offers tips and standards on writing clean code, and
  • Appendix D, 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.
• The  maintainers mailing list is another potential source of information for developers. Please only use this list if participating in Octave or package development.

Project history

Before 2007, Octave Forge did not even have packages since Octave did not had a package manager yet; all of Octave Forge was a single extension to Octave. Development of packages were concerted and releases were synced. Because of this, all development happened in a single repository, it was a single project.

Before February 2010, 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  legacy SVN repository was also available for admin.

As the number of packages increased it became too difficult to coordinate development of the packages, and with the introduction of a package manager in Octave there was no need for that either. This led to the creation of individual packages, released at different times as each package manager saw fit. They were still all under a single giant SVN repository (although with SVN one can easily clone only a subdirectory).

The non-free section was eventually removed, and two prerequisites were defined for inclusion of code in Octave Forge: a GPL compatible license and non-dependency on GPL incompatibility code.

Eventually subversion became a burden as some packages preferred to have their main development happen somewhere else. Between 2013 and 2016, individual packages migrated their history from subversion to a DVCS such as mercurial and git. History of whole package development was migrated to the new repositories.