Contributing to Octave Forge

-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 image, control, +signal, and statistics packages are part of Octave Forge.

-For contributions to Octave core please see -it's page. -To contribute to Octave Forge, please read on. +For contributions to Octave core please see its Octave Developers +Page. To contribute to Octave Forge, please read on.

Contribute to existing packages

Contributing to existing packages

-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 -here and -here. +Each Octave Forge package (with exception of some old packages) has its own +repository. Most use Mercurial + although a few prefer Git. In both cases, +to contribute to an Octave Forge package: +

+ +

+ Set up the version control system for the package (unless already in use), +
+ Clone the package, +
+ Create a patch, and +
+ Submit it to the correct tracker: the bug tracker + if it fixes a bug, otherwise the + patch tracker. +

+ +

+For more details on these steps, see below. +

+ +

Setting up Mercurial

+ +

+Mercurial is part of the software repository for most Linux distributions. For +other systems, go to Mercurial +downloads. Specific installation details depend on the operating system, +version, and flavor chosen.

-The rest of the process is the same as Octave core. After cloning, create -a patch, submit it to the -patch tracker, -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 .hgrc in the home directory. On Windows, it is +typically stored in the home directory as Mercurial.ini. If the file does +not exist, create an empty text document with the correct name and location, and +add the following lines: +

+ +

+[ui]
+username = Your Name <you@email.com>
+

+ +

Setting up Git

+ +

+Git is part of the software repository for most Linux distributions. For other +systems, go to Git downloads. +Specific installation details depend on the operating system, version, and +flavor chosen.

-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:

New packages

+$ git config --global user.name "Your Name"
+$ git config --global user.email you@email.com
+

+ +

Cloning a package with Mercurial

-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 Mercurial repositories. Each +Mercurial repository is stored at http://hg.code.sf.net/p/octave/packagename where packagename + is the name given on the repository list. To clone a package, type the +command

Project history

+$ hg clone http://hg.code.sf.net/p/octave/packagename octave-packagename
+

-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. +

+ +

Cloning a package with Git

+ +

+Like with Mercurial, the first step is finding the package name and location. +SourceForge maintains a list of Git repositories. Each Git +repository is stored at http://git.code.sf.net/p/octave/packagename where packagename is the name +given on the repository list. To clone a package, type the command +

+ +

+$ git clone http://git.code.sf.net/p/octave/packagename octave-packagename
+

+ +

+This will download the most recent version of the package into the current +directory. +

+ +

Creating a patch with Mercurial

+ +

+After cloning the most recent version of the package, make your desired changes +to the package code. Make sure new files include a +copyright notice. Once all changes are complete, in the main package +folder: +

+ Update the working directory with +
```
+$ hg up
+
```
+
+ Commit changes with +
```
+$ hg ci
+
```
+ 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 + "(bug #XXXXX + )" in the first line of the commit message, where + XXXXX is reference number of the bug. +
+ Export the changes to a file with the command +
```
+$ hg export -r tip -o patchname.patch
+
```
+ where patchname is the desired name for the patch file. +

+ +

Creating a patch with Git

+ +

+After cloning the most recent version of the package, make your desired changes +to the package code. Make sure new files include a +copyright notice. Moving or renaming files must be done using +

+ +

+$ git mv filename newlocation
+

+ +

+and removing them must be done using +

+ +

+$ git rm filename
+

+ +

+for Git to recognize those changes. Once all changes are complete, in the main +package folder: +

+ +

+ Add any newly created files with +
```
+$ git add .
+
```
+
+ Commit changes with +
```
+$ git commit -m "commitmessage"
+
```
+ The commitmessage 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 "(bug #XXXXX)" in the first line of the commit + message, where XXXXX is reference number of the bug. +
+ Export the changes to a file with the command +
```
+$ git format-patch -1 --stdout mypatch.patch
+
```
+ where mypatch is the desired name for the patch file. +

+ +

Submitting a patch

+ +Submission 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 that +greatly increases the review and acceptance time. +

+ +

Contributing new packages

+ +

+If you want to contribute with a new package, mention this on the +Octave +maintainers mailing list. +

+ +

Making a package release

+ +

+The details are very much dependent on the structure of the package. +

+ +

+ 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" +
+ tag the commit with
```
hg tag "release-x.y.z"
```
+
+ run any bootstrap or autogen.sh script in the package. +

+ produce a tarball of the package and take note of its md5 checksum: +

+$ cd your-package-directory
+$ hg archive --exclude '.hg*' somewhere/pkgname-x.y.z.tar.gz
+$ md5sum somewhere/pkgname-x.y.z.tar.gz
+

+ test everything worked fine by installing the generated tarball +
```
+> pkg install somewhere/pkgname-x.y.z.tar.gz
+
```
+
+ make sure you have the latest version of the generate_html package +
```
+> pkg install -forge generate_html
+
```
+

+ generate the function reference HTML files with the command +

+> pkg load generate_html
+> generate_package_html ("pkgname", "pkgname-html", "octave-forge")
+

+ produce a tarball of the HTML, take note of its checksum and encode it with uuencode +
```
+$ tar cvzf pkgname-html.tar.gz pkgname-html
+$ md5sum pkgname-html.tar.gz
+
```
+
+ Post the package, html docs and md5 checksums to the package release + tracker 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. +

+ + +

Copyright notices

+ +

+Each file in Octave Forge must contain a copyright notice. Most of Octave Forge +is released under the GNU GPL +. If you wish to do the same, insert the following text at the top of your +file: +

+ +

+## Copyright (C) year Your Name <you@email.com>
+##
+## 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 <http://www.gnu.org/licenses/>.
+

+ +

+There are other popular open source licenses: +

+ +

+Consult +opensource.org for a +comprehensive list of Open Source licenses. +

+ + +

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 development. +

+ +

Project history

+ +

+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.

@@ -115,74 +505,12 @@

-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.

Making a package release

- -

-The details of this is very much dependent on the structure of the package. -

- -

- 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" -
- tag the commit with
```
hg tag "release-x.y.z"
```
-
- run any bootstrap or autogen.sh script in the package. -

- produce a tarball of the package and take note of its md5 checksum: -

-$ cd your-package-directory
-$ hg archive --exclude '.hg*' somewhere/pkgname-x.y.z.tar.gz
-$ md5sum somewhere/pkgname-x.y.z.tar.gz
-

- test everything worked fine by installing the generated tarball -
```
pkg install somewhere/pkgname-x.y.z.tar.gz
```
-
- make sure you have the latest version of the generate_html package -
```
pkg install -forge generate_html
```
-

- generate the function reference HTML files with the command -

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

- produce a tarball of the HTML, take note of its checksum and encode it with uuencode -
```
-$ tar cvzf pkgname-html.tar.gz pkgname-html
-$ md5sum pkgname-html.tar.gz
-    
```
-
Post the package, html docs and md5 checksums to the package -release tracker 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. -

- -