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 existing packages
- Clone the package;
- Create a patch;
- Submit it to the correct tracker: the bug tracker if it fixes a bug, otherwise the patch tracker.
To contribute to an external package, contact the package administrator for the suitable procedure.
Cloning a package
Creating a patch
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:
- Update the working directory;
- Commit changes;
- Export the changes to a patch file.
See more details in the Basics of Generating a Changeset of the Octave manual.
Submitting a patchSubmission is the same for both types of repository and identical to the process for Octave core. Submit the patch to either the patch tracker or the bug tracker, 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 creating a patch as described above greatly increases the review and acceptance time.
Contributing new packages
This is a draft, discussion is invited.
If you want to contribute with a new package, mention this on the Octave maintainers mailing list.
You should decide if you want your package to be a community or external package.
For a package to be hosted at Octave Forge there are certain requirements.
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.
The INDEX file needs special attention to enable checking for
symbol uniqueness among packages and Octave.
- Namespaced functions should be listed as ‘namespace.function’ (without a ‘+’ prefix).
- Class methods, even for classdef based classes, should be listed as ‘@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.
- If the package contains functions which for some reason should not be advertised, they can be listed under the category ‘Internal’ in the INDEX file. In the future, this category will be handled specially in generating the online documentation.
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
> pkg load generate_html > check_duplicates ("pkgname");
Making a package release
This is a draft, discussion is invited.
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
> 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.
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
> 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
$ 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 Octave-maintainers mailing list is another potential source of information for developers. Please only use this list if participating in Octave or package development.
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.
This became unmanageable which 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.
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, are still in SVN.