README.source for the roundcube-plugins-extra package
=====================================================

roundcube-plugins-extra is a collection of plugins for the Roundcube webmail
that are not maintained by Roundcube upstreams. This package aggregates
plugins from different sources, using the "multiple upstream tarballs" feature
introduced in Debian package source format 3.0.

For more informations about "multiple upstream tarball", please look up the
relevant F.A.Q entry:

  https://wiki.debian.org/Projects/DebSrc3.0#How_to_use_multiple_upstream_tarball_in_3.0_.28quilt.29_format.3F

Version number
--------------

The upstream package version number should be the same as the upstream
version number of the roundcube package, followed with a '+' and a
revison number.  Assuming Roundcube 1.4.5 just landed into unstable, the
next roundcube-plugins-extra version should be 1.4.5+1-1.  When a plugin
is upgraded the version should become 1.4.6+1-1 if Roundcube 1.4.6 was
uploaded meanwhile, and 1.4.5+2-1 otherwise.  Bumping the "upstream"
version number on plugin upgrade is required as we need to upload new
.orig-$component.tar.gz.

How to add a new plugin
-----------------------

1. Add a new 'Plugin' paragraph in `debian/plugins.overview`.
2. Add the needed watch file to `debian/plugins/<plugin>/watch.
   The component should be the `Plugin` name. Do not rename the tarball with +dfsg,
   if you exclude files, otherwise the component tarball will not be found.
2. Call `debian/rules update` to download the new tarball and extract it.
4. Look at its files and document their license in `debian/copyright`.
   For excluding files in the tarball use:
   `Files-Excluded-<plugin>` in the first paragraph.
5. Mention the plugin in the extended description of the package
   in `debian/control`.

`debian/plugins`
----------------

The `debian/plugins.overview` describe the plugins shipped in `roundcube-plugins-extra`
in a machine-readable format.

It mimics the RFC822-like format of many Debian files.

Each plugin is described in a 'Plugin' paragraph with the following fields:

 * 'Plugin' contains the short name of the plugin,
 * 'Source' is the URL with the plugin tarball,
 * 'Version' contains the plugin version.

An example:

    Plugin: sieverules
    Source: http://www.tehinterweb.co.uk/roundcube/plugins/sieverules.tar.gz
    Version: 1.11

The plugin version MUST be incremented every time there is an upstream update,
otherwise there will be an issue on the next package upload.
