README and licence

The documentation every version needs, waivers, and licence rules

Chapter 17 of 34Current for Gritpack 1.2.63Source: docs/guide/17-readme-and-licence.md

Someone who finds your package needs two answers before they use it: what does it do, and am I allowed to use it? Every hub therefore asks every new version for a README a person can read and a licence declaration. This chapter shows what counts, what the refusals look like, how to publish without either when you have a real reason, and what happens when a hub limits which licences may be published at all.

What you will be able to do

  • write a README that meets the rule, and point the manifest at it;
  • declare a licence with an SPDX expression or licence files;
  • publish without a README or licence, giving your reason, when that is right;
  • see how those reasons appear to people reading the package;
  • understand a licence-rule refusal and fix it.

The rule

Every hub requires every new version, in every ecosystem, to carry:

  • a README with at least 100 words of prose; and
  • a licence declaration: an SPDX licence expression, or one or more licence files in the package.

Versions published before the rule began are not affected. The rule is checked twice: by the hub when you run gritpack publish --dry-run or gritpack publication verify, and again when the version is actually published, so no route around it exists.

What counts as prose

Only words a person reads count towards the 100. Fenced code blocks, inline code, URLs, link targets, HTML tags and Markdown markup do not. A README that is mostly a code sample is refused, and the refusal says how many words it found:

$ gritpack publish --dry-run
...
  native:@ada/textkit@0.1.0:c/c23:-:-: Blocked
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
    PUBLICATION_DOCUMENTATION_REQUIRED: Failed: @ada/textkit's README has 6 words of prose; it needs at least 100 (code blocks, URLs and markup do not count). To publish it anyway, give your reason: `gritpack publish --without-readme "<reason>"`, ...
publication verification blocked

A hundred words is about one good paragraph: what the package does, who it is for, and how to start. It is not a high bar, and it is the paragraph people will see on the package's page and in gritpack info --json.

The README is a Markdown file inside the package, named by readme in gritpack.toml:

[package]
readme = "README.md"
files = ["include/**", "src/**", "README.md", "LICENSE"]

The file must be one of the files the package carries, so if you use files, include it there too. Having a README.md in the directory is not enough on its own; the manifest has to name it. A README may be up to 128 KiB.

Catalogue pages show READMEs with a restricted kind of Markdown: paragraphs, headings, emphasis, lists, blockquotes, tables, links and code. Raw HTML, images, embedded media and scripts are not shown.

What counts as a licence

Either of these satisfies the rule:

[package]
license = "MIT"
[package]
license-files = ["LICENSE"]

license is an SPDX licence expression: an identifier from the SPDX list, such as MIT, Apache-2.0 or GPL-3.0-only, or several joined with AND, OR and WITH, such as Apache-2.0 OR MIT. For terms of your own, use an identifier starting with LicenseRef-, such as LicenseRef-Acme-Internal-Source. An unknown identifier is refused when you pack, so a typo cannot slip through.

license-files lists up to eight licence texts inside the package. They are evidence you supply; Gritpack does not read them or work out a licence from them. Declaring both is best: the expression is what tools and licence rules read, the files are what lawyers read.

With licence files only, the documentation rule is satisfied, but Gritpack notes that there is no expression it can check:

  check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
  check=PUBLICATION_LICENSE_DECLARED status=Unverified — no SPDX licence expression

That matters if the hub has licence rules, described below.

A version with no licence declaration at all is refused:

    PUBLICATION_DOCUMENTATION_REQUIRED: Failed: @ada/textkit declares no licence; set package.license to an SPDX expression or list package.license-files. To publish without one anyway, give your reason: `gritpack publish --without-license "<reason>"`, ...

Publishing without one, with a reason

Sometimes a README or a licence really does not belong: an internal helper documented elsewhere, code covered by an employment contract rather than a licence. Then say so, in your own words:

gritpack publish \
  --without-readme "Internal helpers, documented in the team wiki" \
  --without-license "Internal code, covered by our employment contracts"

The reason must be a sentence of at least four words, on one line, at most 1000 bytes. A placeholder is refused:

$ gritpack publish --dry-run --without-readme "short"
...
    PUBLICATION_DOCUMENTATION_REQUIRED: Failed: the reason given for --without-readme must be a sentence of at least 4 words and at most 1000 bytes, on one line

The reason is kept with the version and shown wherever the version is shown:

$ gritpack info @ada/textkit
@ada/textkit 0.1.0 (native)
  Small text helpers for C
  dialect: c/c23
  versions: 0.1.0
  variants: 1
  owner: 01a1e866-0f88-7a53-b8fe-d10b69bab7ef
  ...
  published without a README: Internal helpers, documented in the team wiki
  published without a licence: Internal code, covered by our employment contracts

So a reason is not a way to hide anything: it tells readers plainly what they are getting. A waiver given on the command line is recorded only on the versions that need it. In a workspace that publishes ten packages, nine of which have READMEs, only the tenth carries the reason.

Each publishing route takes the reason in its own place:

RouteHow to give the reason
gritpack publish, gritpack publication plan--without-readme "<reason>", --without-license "<reason>"
cargo publish straight to the hubwithout-readme = "<reason>" and without-license = "<reason>" under [package.metadata.gritpack] in Cargo.toml
npm publish straight to the hub"gritpack": {"without-readme": "<reason>", "without-license": "<reason>"} in package.json
gritpack publish <package file>, gritpack go publishnone: publish the directory with gritpack publish instead

Each ecosystem keeps its README in its usual place. Gritpack reads a native package's readme; the README text cargo publish sends, else the crate's packaged README; the npm package's readme field, else its top-level README* file; a Go module's top-level README*. A Go module declares its licence with a top-level LICENSE*, LICENCE* or COPYING* file, because Go has no licence field.

From Cargo. license and license-file in Cargo.toml work as you expect. A crate with only license-file meets the documentation rule, but not a licence rule, which needs an SPDX expression.

Licence rules

A hub can also limit which licences packages may be published under. This is a safety net against an honest mistake: a company's own code going out under an open-source licence because a manifest was copied from a template, or because a coding assistant filled in MIT OR Apache-2.0. Only the hub's administrators set rules (Licence rules, quarantine and the audit log). As a publisher, you meet them when you publish.

A rule lists the licences allowed for the whole hub, for one account, for one scope, or for one package name. The most specific rule decides. With no rule, anything goes.

What a refusal looks like

Suppose the hub's rule for the scope @ada allows Apache-2.0 and LicenseRef-Ada-Internal, and you try to publish a version declaring MIT:

$ gritpack publish --dry-run
...
  native:@ada/hello-tool@1.2.0:application/cli:executable/native:x86_64-unknown-linux-gnu: Blocked
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
    PUBLICATION_LICENSE_NOT_ALLOWED: Failed: @ada/hello-tool 1.2.0 declares the licence `MIT`, but the hub's licence rule for @ada allows only Apache-2.0, LicenseRef-Ada-Internal. Not allowed: MIT. Correct the licence in the package manifest; only the hub's operator can change the rule
publication verification blocked

The refusal comes at the dry run, before anything is uploaded, and again at publication. The command exits with code 6.

How matching works

A version passes only when every licence in its expression is on the list, whatever joins them:

DeclaredAllowedResult
Apache-2.0Apache-2.0, LicenseRef-Ada-Internalallowed
MITsamerefused: MIT
Apache-2.0 OR MITsamerefused: MIT
Apache-2.0 AND MITsamerefused: MIT
GPL-2.0-only WITH Classpath-exception-2.0GPL-2.0-onlyrefused: the exception is a separate term
no expression (licence files only, or --without-license)anythingrefused: a rule needs an expression to check

X OR MIT lets every user choose MIT, and X AND MIT puts part of the code under MIT, so both are exactly the mistake the rule is there to catch:

$ gritpack publish --dry-run
...
    PUBLICATION_LICENSE_NOT_ALLOWED: Failed: @ada/hello-tool 1.2.0 declares the licence `Apache-2.0 OR MIT`, but the hub's licence rule for @ada allows only Apache-2.0, LicenseRef-Ada-Internal. Not allowed: MIT. ...

Go modules have no licence field, so a Go module cannot be published where a licence rule applies.

What to do

Read the message: it names the licence that is not allowed. Then:

  • If the declaration was a mistake, correct license in the manifest (gritpack.toml, Cargo.toml or package.json) and publish again.
  • If the package really must use that licence, for example a fork of an open-source project that keeps its upstream licence, ask the hub's administrator for a rule for that one name. That is a deliberate decision for the administrator, and the message never suggests it, so a script or a coding assistant that hits the rule fixes the manifest rather than looking for a way around it.

Rules apply only to versions published after they are set. Published versions are never hidden or relabelled because of a rule.

What just happened

  • Every new version needs a README of 100 words of prose and a licence declaration, checked at the dry run and again at publication.
  • readme, license and license-files in the manifest provide them; --without-readme and --without-license publish without them, with your reason shown beside the version.
  • A licence rule limits which SPDX licences may be published. Every term of the expression must be allowed, and the fix is to correct the manifest.

You can stop here

If your packages have a README and a licence, you will rarely think about this again.

Next