Meta Data
Generating Licensing Documents
Licensing
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
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.
We adopt the convention that LICENSE means the principle licensing document for the project.
Learn about copyright and software licensing here.
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.
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.
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.
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.
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.