Meta Data
Generating Licensing Documents
Licensing
LICENSE?NOTICE?NOTICE and a copyright notice?NOTICE and a LICENSE?NOTICE needed?NOTICE for my Apache Licensed Project?Is there an Example...
Learning
DRY rules.
Each license, notice and organisation should be described once, and then
referenced by id. For complex projects, this reduces duplication
and eases maintenance.
IDs need to be unique (within the document) but otherwise you are free.
Yes, but...
Whisker adopts the convention that name attributes
(for example, on license elements) are used
for presentation, so it is strong recommended that a suitably
human-readable title is chosen.
Where possibly, pick the standard name for this license: either the title within the text, or the name adopted by a standards organisation for example The Open Source Initiative.
Whisker adopts the convention that url attributes
(for example, on license elements) are used to present
a reference location for a reader. It is recommended that a
standard URL is given, where possible, for example from the
The Open Source Initiative.
Yes
Where possible, we recommend reusing the name adopted by a standards organisation, for example The Open Source Initiative.
Whisker documentation often talks about a primary license,
a primary organisation and so on.
The meta-data contains elements like primary-license and
primary-notice. Though the intended meaning might accord
with intuition, a more precise description may help to deepen
understanding of software licensing.
By primary, we mean the
main license, notice or organisation associated with the project.
Take, for example, a project here at Apache.
In this case, the primary license would be
The Apache License, Version 2
(AL2)
and the primary organisation
The Apache Software Foundation.
The primary license should cover most of the original content contributed
by the project to the software distributed. Apache, for example,
insists that
original source is
AL2 licensed.
The primary organisation should be the legal entity
issuing the primary license. Apache, for example, uses
contributor license agreements,
grants and
AL2 Section 5
to allow the foundation to issue open source licenses.
The primary license covers most of the original content contributed
by the project to the software distributed. Apache, for example,
insists that
original source is
AL2 licensed.
The primary organisation should be the legal entity
issuing the primary license. Apache, for example, uses
contributor license agreements,
grants and
AL2 Section 5
to allow the foundation to issue open source licenses. Alternatively
(as practiced by
GNU,
for example)
copyright may be assigned to the organisation by its contributions.
Whisker uses organisation to identify and describe groups or individuals who license the third party works distributed. This includes a wide variety of entities, for example
To reduce duplication and increase comprehension, Whisker often groups results by organisation.
See here for examples.
No
As far as Whisker is concerned, a wide variety of entities are organisations, as well as some individual maintainers.
Read more here and see comments on informal groups.
As far as Whisker is concerned, each individual maintainer is an organisation.
See this example.
Read more here.
As far as Whisker is concerned, each corporation (whether non-profit or for-profit) is an organisation.
See this example.
Read more here.
As far as Whisker is concerned, each group or collective is an organisation. You might want to check that the licensor has the rights required to issue the license, though, before adding it to your distribution.
See this example.
Read more here.
No particular reason
Apologies to those tripped up by this choice
Yes, in the meta data reference
The DTD is aimed at IDE users and developers, and is not prescriptive but descriptive.
For the present, schema validation is not enforced. If it were, probably a language like Relax NG would be chosen.
A DTD is available in the meta data reference, which should be of some use.
There are currently no known plugins. If you know of a plugin please let us know or contribute a patch for this documentation.
.
As in <within dir='.'>
Read how directories are modeled here
Directories are modeled by a flat list of within
elements.
Read why here
See how the root directory is modelled here
Simplicity
Within a file system, the containment relationship between
directories typically forms a natural tree. Modern file systems
typically allow cyclic links only with special links (for example,
symbolic links in
*nix).
Including these links would allow directory containment
to become a graph. XML element containment forms a natural
tree structure, but representing a graph in XML requires
links to break this structure.
This would introduce more complexity
and more ways to make mistakes but little gain.
Read how directories are modeled here
See how the root directory is modelled here
Resources are grouped
by-organisationwith-licensewithin a directory.
The directory structure is not represented by
nesting within elements. These elements are simply listed.
See the samples for examples.
Yes
Add a template license and parameterise.
Read how here.
Read the rational for templates here.
See this example.
Read more about license families here.
Templates are not strictly necessary.
Just pasting every complete license into the text would work,
though the meta-data would be less concise than using templates.
There is some additional work involved with drawing up each template,
so you might think that this is not a worthwhile tradeoff.
But there are reasons why using templates today may benefit a project tomorrow.
License families share important legal qualities. In the future, it should be possible to automate some licensing policy checks but only if licenses are categorised in a form which enables automated reasoning. Using a template for all members of a family is likely to help.
Read more about license families here.
An (optional) copyright notice,
included in a LICENSE document but positioned above the license text
(rather than being part of it). For example, conventionally a copyright notice
is positioned above the
MIT License text.
Learn about copyright notices here.
Read about the different between a NOTICE
and a copyright notice here.
Read about when you need to add a primary copyright notice here.
Read about how you need add a primary copyright notice here.
Add a copyright-notice child to the primary-license.
See the example here.
Learn about copyright notices here.
Read about the different between a NOTICE
and a copyright notice here.
Read about when you need to add a primary copyright notice here.
Template licenses
(for example the
BSD License 2 Clause)
typically includes a
parameterised copyright notice. Licenses
with a NOTICE
(for example the
Apache License, Version 2)
usually include the copyright notice in the NOTICE.
Some other licenses (for example the MIT License) conventionally include a copyright notice above the text: to use these licenses with Whisker, add a primary copyright notice and use the plain license text.
Learn about copyright notices here.
Read about the different between a NOTICE
and a copyright notice here.
Read about how you need add a primary copyright notice here.
Template licenses
(for example the
BSD License 2 Clause)
typically includes a
parameterised copyright notice. Licenses
with a NOTICE
(for example the
Apache License, Version 2)
usually include the copyright notice in the NOTICE. When using these
licenses with Whisker, to set a copyright claim use the parameter or
notice rather than
the copyright-notice element.
Some other licenses (for example the MIT License) conventionally include a copyright notice above the text: to use these licenses with Whisker, add a copyright notice and use the plain license text.
Learn about copyright notices here.
Read about the different between a NOTICE
and a copyright notice here.
If the copyright claim belongs in the LICENSE document then
use a copyright-notice.
If the copyright claim belongs in the NOTICE
document then include it within a notice.
Learn about copyright notices here.
Read about the different between a NOTICE
and a copyright notice here.
Yes
See
Whisker should generate a NOTICE document only when
needed.
Examples include:
If you have a use case where an unnecessary NOTICE is generated,
or when a NOTICE isn't generated when it is needed please open an
issue or let us know
on list.
Yes - use the source element.
Learn about the source element
here.
Learn about source clauses here.
No
Whisker is just an efficient way to maintain licensing documentation for complex applications. It is no substitute for accurate legal legwork.
Learn about copyright and software licensing here.
Most definitely no
This documentation guides users assumed to have a practical understanding of the relevant laws in appropriate jurisdictions. In order to explain how Whisker can help, we need to agree some terms with the reader.
Learn about copyright and software licensing here.
Intellectual property laws are complex, and vary from country to country. Anyone looking for legal advice should consult the best lawyer they can. We cannot help.
In some general sense, a license is a permission. We're thinking in particular about copyright or patent permissions.
Whisker focuses on tracking explicit licenses, and so almost always when we talk about a license, we're thinking about a written document conditionally granting some copyright and patents permissions for a work.
Learn about copyright and software licensing here.
We adopt the convention LICENSE for the principle licensing
document. Read more about this convention here.
LICENSE?
We adopt the convention that LICENSE means the principle licensing
document for the project.
Learn about copyright and software licensing here.
NOTICE?
A NOTICE is informational documentation, whose retention
is required by a license condition.
Some licenses (for example the
Apache License, Version 2)
may require the retention of a document named NOTICE (or at least its contents).
By NOTICE we mean information that MUST be preserved
to satisfy some condition of a license. Take care not to confuse NOTICE with
copyright notice or
LICENSE.
A phrase or symbol informing a reader about a underlying claim of copyright ownership.
For example "Copyright (c) 2525 Apache Software Foundation"
Though copyright laws differ from country to country, copyright notices are may well be considered important, and may be governed by statue.
Take care not to confuse copyright notice with
NOTICE.
Learn about copyright and software licensing here.
NOTICE and a copyright notice?
A NOTICE is informational documentation, whereas a copyright notice
informs a reader about a legal claim of ownership. A license may be conditional
on the redistribution of the contents of a NOTICE but typically
a copyright notice is governed directly by statue.
A NOTICE document often contains
copyright notices, but is not limited to just this sort of content.
Read more on NOTICE documents here.
Read more on copyright notices here.
Learn about copyright and software licensing here.
NOTICE and a LICENSE?
A NOTICE is informational documentation, whereas a LICENSE
is legal documentation.
A NOTICE may be subject to a retention clause.
Read more on NOTICE documents here.
Learn about copyright and software licensing here.
NOTICE needed?It depends :-)
Some licenses require NOTICE documents to be retained.
For example, clause 4.4 in the
Apache License, Version 2
is a retention clause covering any NOTICE distributed with the original.
When creating or distributing a modified version of a project licensed with a retention clause,
you need to ensure that the NOTICE is distributed.
Read more on NOTICE documents here.
Learn about copyright and software licensing here.
NOTICE for my Apache Licensed Project?
Not necessarily, though Apache Software Foundation projects
MUST include a NOTICE
of standard form.
The Apache License, Version 2
requires that a NOTICE is retained but if your project contains only
original files then you could opt not to have a NOTICE. Please read
this.
It is polite to include a minimal NOTICE. Otherwise,
downstream consumers may need to manually verify that no
NOTICE exists
for the release.
Read more on NOTICE documents here.
For projects distributing applications containing only a few third party dependencies,
manually maintaining and verifying the LICENSE and NOTICE documents
shipped is not a major burden. When releasing complex applications containing scores of
third party dependencies from dozens of sources, producing accurate licensing documentation
without automation takes a lot of time. This is where Whisker has the biggest value.
The entity issuing the license.
Software flows downstream from the source to the end user. Dependencies are upstream of a project, and software that relies on a project are downstream consumers.
An open-source license complies with the Open Source Definition. Open Source Licenses are those on this list. Both are maintained by the Open Source Initiative.
Learn more about Open Source here.
A reciprocal open source copyright license limiting some rights of downstream consumers to distribute under more restrictive licenses (following Open Source Licensing, Lawrence Rosen).
Read more about copyleft here.
Read more about open source licenses here.
Learn more about Free Software here.
Learn more about weak copyleft here.
A copyleft license that allows some forms of derivative work to be distributed under more restrictive licenses by downstream consumers.
Read more about copyleft here.
Read more about open source licenses here.
Some (typically weak copyleft) open source licenses ask that distributors of binaries built from their sources facilitate downstream consumers in obtaining the source for the distributed binary. The part of the license explaining exactly what this means we refer to as a source clause.
For example, the CDDL 1.0 contains:
3.1. Availability of Source Code.
Any Covered Software that You distribute or otherwise make available in Executable form must also be made available in Source Code form and that Source Code form must be distributed only under the terms of this License. You must include a copy of this License with every copy of the Source Code form of the Covered Software You distribute or otherwise make available. You must inform recipients of any such Covered Software in Executable form as to how they can obtain such Covered Software in Source Code form in a reasonable manner on or through a medium customarily used for software exchange.
A distributor of CDDL licensed materials should consider including (within the distribution) either the source, or information about how the source could be obtain - perhaps in the form of an URL linking to the source.
Source clauses differ. Read, understand and comply with each. The term source clause is a useful aide memoire: when a license has a source clause distributors need to remember to act to satisfy it.
Learn how Whisker can help here.
Learn about copyright and software licensing here.
Read more about licenses here.
Read more about weak copyleft licenses here.
Open source licenses are designed to be re-usable: both you and I can use the same basic text to license our works. Many license texts can be reused without modification (for example, the Apache License, Version 2). Others require that a small number of details are changed.
For example, to use the BSD License (2 Clause) your name, organisation and the year of publication must be inserted. We call licenses of this sort a license family to emphasis that the text is a template from which instances of the licenses are created by parameterisation.
Each family shares the share legal qualities, typically differing only in details related to the act of publication. Knowing that a license belongs to a family allows knowledge about that family to be applied without extensive analysis of the text. So, for example, even though BSD License (2 Clause) texts differ we can confidently state that each is an Open Source License.
Learn how Whisker supports license families here.
Read more about licenses here.
Learn about copyright and software licensing here.
Yes
Including examples focussing on
Read more about organisations here.