Octave-Forge: Difference between revisions

From Octave
Jump to navigation Jump to search
m (→‎External links: link typo)
(Compiled a list of roles and responsibilities for Octave-Forge)
Line 1: Line 1:
Octave-Forge is a community project for collaborative development of GNU Octave extensions. If you have a large package that you want to open up to collaborative development, or a couple of m-files that you want to contribute to an existing package, Octave-Forge is the place to do it. Tiny helper functions (the equivalent of e.g., shell aliases) should go in the [[Tips and tricks]] page.
Octave-Forge is a community project for collaborative development of GNU Octave extensions, called “Octave packages”. If you have a large package that you want to open up to collaborative development, or a couple of m-files that you want to contribute to an existing package, Octave-Forge is the place to do it. Tiny helper functions (the equivalent of e.g., shell aliases) should go in the [[Tips and tricks]] page.
 
GNU Octave also needs the equivalent of CPAN so that packages such as epstk which have been developed elsewhere can be archived. [[Agora Octave]] is a fledgeling proposal to do that (talk to [[User:JordiGH|JordiGH]] about it). Before that is possible we need a packaging system which works for both Octave and Matlab (and maybe Scilab if you are feeling ambitious) without too much work on the either the developers or the users end, even for users working in a tool desert such as Windows. Feel free to expand on the definition of such a system on this page.


== Installing packages ==
== Installing packages ==
You can find the list of packages on the [http://octave.sourceforge.net/packages.php Octave-Forge website]. The recommended method for package installation is using your system package manager. See also the [[FAQ]] for the most common issues.
You can find the list of packages on the [http://octave.sourceforge.net/packages.php Octave-Forge website]. The recommended method for package installation is using your system package manager, see also the [[FAQ]] for the most common issues. The official [[Windows Installer]] bundles several packages so they don't have to be installed separately.


If for some reason you need to install a package from the Octave Forge, simply type at the Octave prompt {{Codeline|pkg install -forge package_name}}. If your Octave version is too old (before 3.4.0), you'll have to download the package file manually, and use {{Codeline|pkg install package_file_name.tar.gz}}.
If for some reason you need to install a package from the Octave Forge, simply type at the Octave prompt {{Codeline|pkg install -forge package_name}}. If your Octave version is too old (before 3.4.0), you'll have to download the package file manually, and use {{Codeline|pkg install package_file_name.tar.gz}}.


== Contributing via the Agora website ==
== Collaborative development ==
'''<span style="color:#FF0000;">This is work in progress.</span>'''
 
Octave extensions are developed and released on SourceForge https://sourceforge.net/projects/octave/


You can upload your code to [[Agora]]. The code is classified according the following criteria.
=== Roles ===


* Single file
'''Package author'''
:: The file is full responsibility of the uploader.
* Writes individual function files (m-files, oct-files)
:: Octave and Agora do not check or support this submissions.
* Writes documentation, either for individual functions (function reference) or the package as a whole (package documentation / user manual)
* Writes [[Tests|tests]], either for individual function files or the the package as a whole
* Writes [https://www.gnu.org/software/octave/doc/interpreter/Demonstration-Functions.html demos] for individual function files


* Bundle of files
''' Package contributor'''
:: The file(s) is(are) full responsibility of the uploader.
* Contributes bug reports or feature requests, e. g., via the [https://savannah.gnu.org/bugs/?group=octave Octave bug tracker]
:: The bundle passes a structure check to see if it is compatible with the builtin Octave installer. This doesn't mean the bundle with install  flawlessly.
* Contributes patches to fix errors, e. g., via the [https://savannah.gnu.org/patch/?group=octave Octave patch tracker]
:: Octave and Agora do not check or support this submissions.


* Forge
'''Package maintainer'''
:: The file(s) is(are) responsibility of its maintainer and the Agora maintainers community.
* Maintains package content (m-files, C and fortran code, documentation, bundled libraries, other content) inside the source code repository, see [https://www.gnu.org/software/octave/doc/interpreter/Creating-Packages.html]. If the code is developed elsewhere, the repository must be pushed to Octave-Forge at release time.
:: This package will install using the builtin Octave installer.
* Keeps the package in good shape, e. g., installability on many systems, up-to-date INDEX, DESCRIPTION, NEWS … files
* Manages package licensing
* Works towards a reasonable test suite for the package and ensures passing tests at release time
* Releases new versions of the package, see [https://octave.sourceforge.io/developers.html]. It is recommended to use a Makefile at the top level of the repository to automate this task.
* Announces new package releases at both Octave mailing lists once they have been uploaded
* Answers bug reports and feature requests for the individual package. The maintainer has no obligation to provide a fix herself.
* Reviews patches for the individual package and decides whether they may be applied, e. g., coding style, help texts, tests, a new function matches the scope of the package
* Acts as a primary contact for downstream distributors


'''Forge release manager'''
* Answers the [https://sourceforge.net/p/octave/package-releases/ package release tickets]
* Reviews package release candidates (these are formal checks)
** The package lists at least one maintainer with valid contact information
** Up-to-date documentation
** Must install and work with the latest stable Octave release
** License compliance (must be released under a GPL compatible license)
** The corresponding source code revision must be tagged inside the Octave-Forge repository and it must be possible to reproduce the content of the release tarball from this revision. Aforementioned Makefile can help with this task.
** Content has been signed by the package maintainer or matching hash values have been provided via the package release ticket
** All functions (except private ones) must be documented using Texinfo
** The package must have all the required files [https://www.gnu.org/software/octave/doc/interpreter/Creating-Packages.html]
** If the package has a doc folder it should be written in Texinfo
** No Octave core functions should be shadowed
** No external dependencies should be directly included
* Uploads new releases


[[File:agora.png|center|380px]]
'''Forge leader'''
* Decides about entry of new packages to Octave-Forge
* Categorizes the list of maintained and unmaintained packages
* Administrates the SourceForge project
* Manages the project


The Forge packages have must comply with
'''Forge Community'''
* At least one package maintainer.
* Contributes new ideas to the project
* Must install and work with the latest Octave release.
* Makes strategic decisions
* The must be released under a [http://en.wikipedia.org/wiki/List_of_FSF-approved_software_licenses GPL compatible] license.
* All functions (except private ones) must be documented using [http://en.wikipedia.org/wiki/Texinfo Texinfo].
* The package must have all the [http://www.gnu.org/software/octave/doc/interpreter/Creating-Packages.html#Creating-Packages required files].
* If the package has a doc folder it should be written in [http://en.wikipedia.org/wiki/Texinfo Texinfo].


These packages are also recommended to comply with
* No shadowing of Octave core functions.
* No direct inclusion of external dependencies.


== Suggested new features ==
== Suggested new features ==


* Install directory  
* Install directory  
* Install from URL
* Install from URL / source code repository
* Build HTML / PDF docs
* Build HTML / PDF docs
* Index, host documentation and archive releases of packages such as epstk which have been developed elsewhere (equivalent of CPAN). Feel free to expand on the definition of such a system on this page.
* Rapid code sharing of individual function files, see [[Agora]].


== See also ==
== See also ==

Revision as of 12:36, 6 January 2017

Octave-Forge is a community project for collaborative development of GNU Octave extensions, called “Octave packages”. If you have a large package that you want to open up to collaborative development, or a couple of m-files that you want to contribute to an existing package, Octave-Forge is the place to do it. Tiny helper functions (the equivalent of e.g., shell aliases) should go in the Tips and tricks page.

Installing packages

You can find the list of packages on the Octave-Forge website. The recommended method for package installation is using your system package manager, see also the FAQ for the most common issues. The official Windows Installer bundles several packages so they don't have to be installed separately.

If for some reason you need to install a package from the Octave Forge, simply type at the Octave prompt pkg install -forge package_name. If your Octave version is too old (before 3.4.0), you'll have to download the package file manually, and use pkg install package_file_name.tar.gz.

Collaborative development

Octave extensions are developed and released on SourceForge https://sourceforge.net/projects/octave/

Roles

Package author

  • Writes individual function files (m-files, oct-files)
  • Writes documentation, either for individual functions (function reference) or the package as a whole (package documentation / user manual)
  • Writes tests, either for individual function files or the the package as a whole
  • Writes demos for individual function files

Package contributor

Package maintainer

  • Maintains package content (m-files, C and fortran code, documentation, bundled libraries, other content) inside the source code repository, see [1]. If the code is developed elsewhere, the repository must be pushed to Octave-Forge at release time.
  • Keeps the package in good shape, e. g., installability on many systems, up-to-date INDEX, DESCRIPTION, NEWS … files
  • Manages package licensing
  • Works towards a reasonable test suite for the package and ensures passing tests at release time
  • Releases new versions of the package, see [2]. It is recommended to use a Makefile at the top level of the repository to automate this task.
  • Announces new package releases at both Octave mailing lists once they have been uploaded
  • Answers bug reports and feature requests for the individual package. The maintainer has no obligation to provide a fix herself.
  • Reviews patches for the individual package and decides whether they may be applied, e. g., coding style, help texts, tests, a new function matches the scope of the package
  • Acts as a primary contact for downstream distributors

Forge release manager

  • Answers the package release tickets
  • Reviews package release candidates (these are formal checks)
    • The package lists at least one maintainer with valid contact information
    • Up-to-date documentation
    • Must install and work with the latest stable Octave release
    • License compliance (must be released under a GPL compatible license)
    • The corresponding source code revision must be tagged inside the Octave-Forge repository and it must be possible to reproduce the content of the release tarball from this revision. Aforementioned Makefile can help with this task.
    • Content has been signed by the package maintainer or matching hash values have been provided via the package release ticket
    • All functions (except private ones) must be documented using Texinfo
    • The package must have all the required files [3]
    • If the package has a doc folder it should be written in Texinfo
    • No Octave core functions should be shadowed
    • No external dependencies should be directly included
  • Uploads new releases

Forge leader

  • Decides about entry of new packages to Octave-Forge
  • Categorizes the list of maintained and unmaintained packages
  • Administrates the SourceForge project
  • Manages the project

Forge Community

  • Contributes new ideas to the project
  • Makes strategic decisions


Suggested new features

  • Install directory
  • Install from URL / source code repository
  • Build HTML / PDF docs
  • Index, host documentation and archive releases of packages such as epstk which have been developed elsewhere (equivalent of CPAN). Feel free to expand on the definition of such a system on this page.
  • Rapid code sharing of individual function files, see Agora.

See also

External links

Retrieved from "https://wiki.octave.org/wiki/index.php?title=Octave-Forge&oldid=9737"