=pod

=head1 NAME

uscan-templates - Available templates for L<uscan(1)>.

=head1 USING TEMPLATES

Templates simplify the B<debian/watch> file. You just have to indicate the
template to use and the specific arguments. Example:

  Version: 5

  Template: GitHub
  Dist: https://github.com/guimard/llng-docker

Or:

  Version: 5

  Template: GitHub
  Owner: guimard
  Project: llng-docker

Other parameters can be added as usual. Example:

  Version: 5

  Template: GitHub
  Owner: guimard
  Project: llng-docker
  Version-Mangle: auto

=head1 AVAILABLE TEMPLATES

Here is the list of available templates:

=over

=item * L</Bioconductor>

=item * L</CRAN>

=item * L</GitHub>

=item * L</GitLab>

=item * L</Metacpan>

=item * L</Npmregistry>

=item * L</Pypi>

=back

=head2 Bioconductor

This template fetches a Bioconductor R package's source from bioconductor.org,
the main mirror.

=head3 Specific parameters

=over

=item * B<Package>: name of the package.

=back

=head3 Example

  Version: 5

  Template: Bioconductor
  Package: IRanges

=head2 CRAN

This template fetches a CRAN (Complete R Archive Network) package's source from
cran.r-project.org, the main mirror.

=head3 Specific parameters

=over

=item * B<Package>: name of the package.

=back

=head3 Example

  Version: 5

  Template: CRAN
  Package: vegan

=head2 GitHub

This template uses GitHub API to find archives to download.

=head3 Specific parameters

=over

=item * B<Dist>: URL to the project

=item * B<Owner> I<< <owner> >> (ignored if "Dist" is used)

=item * B<Project> I<< <project> >> (ignored if "Dist" is used)

=item * B<Release-Only> I<< <yes> >>: when set, search only in "/releases" instead of "/tags"

=item * B<Version-Type> I<< (default: B<ANY_VERSION>) >>: by default, templates
use B<ANY_VERSION> macro to find valid version. You can override this here
using a valid macro name I<(ANY_VERSION or STABLE_VERSION or SEMANTIC_VERSION)>

=item * B<Custom-Version> I<< (capturing version regexp) >>:
Use a custom version regexp.
Syntax is the same used for versions in B<Matching-Pattern>.
Example:

  Custom-Version: v(0\.7\.\d+)

This parameter takes precedence over B<Version-Type> and can use its valid macro names, like in

  Custom-Version: version_@ANY_VERSION@

=back

=head3 Example

Using the B<Dist> parameter:

  Version: 5

  Template: GitHub
  Dist: https://github.com/guimard/llng-docker

Using the B<Owner> and B<Project> parameters:

  Version: 5

  Template: GitHub
  Owner: guimard
  Project: llng-docker

=head2 GitLab

This template uses B<Mode: gitlab> to download package.

=head3 Specific parameters

=over

=item * B<Dist>: URL to the project

=item * B<Release-Only> I<< <yes> >>: when set, search only in "/releases" instead of "/tags"

=item * B<Version-Type> I<< (default: B<ANY_VERSION>) >>: by default, templates
use B<ANY_VERSION> macro to find valid version. You can override this here
using a valid macro name I<(ANY_VERSION or STABLE_VERSION or SEMANTIC_VERSION)>

=item * B<Custom-Version> I<< (capturing version regexp) >>:
Use a custom version regexp.
Syntax is the same used for versions in B<Matching-Pattern>.
Example:

  Custom-Version: v(0\.7\.\d+)

This parameter takes precedence over B<Version-Type> and can use its valid macro names, like in

  Custom-Version: version_@ANY_VERSION@

=back

=head3 Example

  Version: 5

  Template: GitLab
  Dist: https://salsa.debian.org/debian/devscripts

=head2 Metacpan

This template uses L<MetaCPAN::Client(3pm)> to download package.

=head3 Specific parameters

=over

=item * B<Dist>: distribution name I<(with "::" or "-")>

=item * B<Version-Type> I<< (default: B<ANY_VERSION>) >>: by default, templates
use B<ANY_VERSION> macro to find valid version. You can override this here
using a valid macro name I<(ANY_VERSION or STABLE_VERSION or SEMANTIC_VERSION)>

=back

=head3 Example

  Version: 5

  Template: Metacpan
  Dist: MetaCPAN-Client

=head2 Npmregistry

=head3 Specific parameters

=over

=item * B<Dist>: distribution name

=item * B<Version-Type> I<< (default: B<ANY_VERSION>) >>: by default, templates
use B<ANY_VERSION> macro to find valid version. You can override this here
using a valid macro name I<(ANY_VERSION or STABLE_VERSION or SEMANTIC_VERSION)>

=back

=head3 Example

  Version: 5

  Template: Npmregistry
  Dist: @lemonldapng/handler

=head2 Pypi

This template uses pypi.debian.net to download the tarball.

=head3 Specific parameters

=over

=item * B<Dist>: name of the project

=item * B<Version-Type> I<< (default: B<ANY_VERSION>) >>: by default, templates
use B<ANY_VERSION> macro to find valid version. You can override this here
using a valid macro name I<(ANY_VERSION or STABLE_VERSION or SEMANTIC_VERSION)>

=back

=head3 Example

  Version: 5

  Template: Pypi
  Dist: bitbox02

=head1 Adding templates

If you want to add a template in uscan, you can find the documentation here:

  $ perldoc /usr/share/perl5/Devscripts/Uscan/Templates.pod

Then build a merge-request into the L<devscripts project|https://salsa.debian.org/debian/devscripts>.

=head1 Authors

=over

=item * Xavier Guimard E<lt>yadd@debian.orgE<gt>

=back
