Ubuntu Manpage: license-reconcile - reconcile debian/copyright against source

NAME

       license-reconcile - reconcile debian/copyright against source

SYNOPSIS

       license-reconcile --help|--man

       license-reconcile [--copyright-file=file] [--no-check-copyright] [--suggest-stanzas] [--no-format-spec]
       [--quiet] [--display-mapping] [--directory=directory] [--filters=module1 module2 ...]
       [--config-file=file] [--changelog-file=file] [files...]

DESCRIPTION

       license-reconcile attempts to match license and copyright information in a directory with the information
       available in "debian/copyright".  It gets most of its data from "licensecheck" so should produce
       something worth looking at out of the box.  However for a given package it can be configured to succeed
       in a known good state, so that if on subsequent upstream updates it fails, it points out what needs
       looking at.  By default the tests run are as follows:

       - Does the copyright file have an approved format specification as its first line?
       - Can the copyright file be parsed?
       - Does every file in the source match at least one clause in the copyright file?
       - Can every file, license and copyright datum extracted from the source be contained in the corresponding
       matching paragraph from the copyright file? The data for this comparison comes from a number filter
       objects. See "Filters" for more information.
       - Is every file in the source assigned copyright and a license by some part of the "debian/copyright"
       file.

GETTING STARTED

out of the box
From the top level of the source directory of Debian packaged software, just run "license-reconcile".

setting a config file
Normally to make any progress it will be necessary to have a config file. The default file is
"debian/license-reconcile.yml". A different config file can be set with the --config-file=file. The
config file is interpreted using Config::Any but for the purposes of this documentation# we assume the
format is YAML.

overriding incorrect results
Suppose you are really lucky. For just one file, "a/b", the default filters which are wrappers around
"licensecheck", have got it wrong. They have for some reason decided that the file has a GPL-3 license,
when inspection shows it is in the public domain. This is causing a false positive break against your
carefully crafted "debian/copyright" file. You can fix this with the following config fragment:

Rules:
rules:
-
Glob: a/b
License: public-domain
Copyright: 1556, Nostrodamus

See Debian::LicenseReconcile::Filter::Rules for more information on how to configure this filter.

providing a catch all license and copyright
You can make the filters provide a default license, but providing a suitable rule in the Default section
of the config file:

Default:
rules:
-
License: All software is property of the proletariat license
Copyright: 1984, Ministry of Algorithms

The Default filter uses exactly the same code as the Rules filter, but by default runs last. So it has
all the same functionality but the lowest precedence.

controlling the sequence of filters.
By default the filters run are: Rules, Std, Shebang, ChangeLog and Default. You can vary the filters
using the --filters=module option. Setting "--filters Rules" would mean that only the
Debian::LicenseReconcile::Filter::Rules filter would be used. Once you specify one filter you must
specify them all.

filter aliasing
The Default filter is an alias for Rules. This means it runs the same code but has a separate config.
Default is defined as "Default~Rules". In general "X~Y" means use the code from Y but get the config from
X.

writing your own filter.
You can write your own filters by inheriting from Debian::LicenseReconcile::Filter. You need to define
the "get_info" method.

OPTIONS

   --copyright-file=file
       Specify an alternative copyright file. Defaults to "debian/copyright".

   --no-format-spec
       Don't check the first line of the copyright file against permitted format specifications.

   --no-check-copyright
       Don't check the copyright clauses.

   --quiet
       Don't give any explanations, simply a success or a fail via the exit status.

   --display-mapping
       Display mapping from the directory onto the copyright clauses.

   --directory=directory
       The directory whose copyright and licenses will be verified. This defaults to ".".

   --filters=module1  --filters=module2 ....
       A sequence of filters which will inspect the source package and return license and copyright information.
       Each module name must sit below the Debian::LicenseReconcile::Filter and inherit  from  it.  The  default
       value is "Rules Std Shebang ChangeLog Default".

   --config-file=file
       A  file  used  to  provide  filter  specific  configuration data. The file is read by Config::Any and the
       relevant section is passed to each filter constructor via the "config" parameter.

   <--changelog-file=>file
       The Debian changelog file which defaults to "debian/changelog". The Rules filter uses  this  to  get  the
       current version and the ChangeLog filter gets its data from it.

   --suggest-stanzas
       If set print out the license and copyright data in DEP-5 format.

Filters

       By  default  the  filters  are  processed  in the order below. Once a file has been returned by a filter,
       subsequent filters will ignore it.

       - Rules
       - ChangeLog
       - Std
       - Shebang
       - Default

       Each filter constructor will be passed the following parameters:

       - directory - the directory from which to find license and copyright data.
       - files_remaining - an array ref of files which have not been analyzed.
       - config - a data structure representing the portion of the config file relevant to this filter.
       - changelog - a Parse::DebianChangelog object.
       - licensecheck - a Debian::LicenseReconcile::LicenseCheck object.

FILE ARGUMENTS

       Any arguments after the arguments are assumed to  be  files.  If  specified  only  these  files  will  be
       reconciled.

LIMITATIONS

       The  DEP-5  specification  is subtly different from the file glob specification.  Since the File::FnMatch
       module is the only practical implementation there is little that can be done.  The  consequence  is  that
       attempting  to  specify  that  a  file  name  should contain '[' and later a ']' in "debian/copyright" is
       unlikely to work correctly.

       In copyright parsing years cannot be expressed in an abbreviated two digit form.  This is probably a good
       thing, but it it will surely cause an issue at some point.

EXAMPLES

       Two Debian projects are currently using license-reconcile, to verify the "debian/copyright" file.

       license-reconcile|https://anonscm.debian.org/cgit/pkg-perl/packages/license-reconcile.git/tree/debian/license-reconcile.yml
       must obviously be clean by its own standards. At some point this check will be added to the build tests.
       ksh|http://anonscm.debian.org/cgit/collab-maint/ksh.git/tree/debian/license-reconcile.yml is using
       license-reconcile since version 93u+20120801-2.

AUTHOR

       Nicholas Bamber, "<nicholas at periapt.co.uk>"

LICENSE AND COPYRIGHT

       Copyright 2012, 2015, Nicholas Bamber.

       This program is free software; you can redistribute it and/or modify it under the terms  of  either:  the
       GNU General Public License as published by the Free Software Foundation; or the Artistic License.

       See http://dev.perl.org/licenses/ for more information.

perl v5.24.1                                       2017-01-28                              LICENSE-RECONCILE(1p)