README and licence
The documentation every version needs, waivers, and licence rules
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:
| Route | How to give the reason |
|---|---|
gritpack publish, gritpack publication plan | --without-readme "<reason>", --without-license "<reason>" |
cargo publish straight to the hub | without-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 publish | none: 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.
licenseandlicense-fileinCargo.tomlwork as you expect. A crate with onlylicense-filemeets 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:
| Declared | Allowed | Result |
|---|---|---|
Apache-2.0 | Apache-2.0, LicenseRef-Ada-Internal | allowed |
MIT | same | refused: MIT |
Apache-2.0 OR MIT | same | refused: MIT |
Apache-2.0 AND MIT | same | refused: MIT |
GPL-2.0-only WITH Classpath-exception-2.0 | GPL-2.0-only | refused: the exception is a separate term |
no expression (licence files only, or --without-license) | anything | refused: 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
licensein the manifest (gritpack.toml,Cargo.tomlorpackage.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,licenseandlicense-filesin the manifest provide them;--without-readmeand--without-licensepublish 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
- After publishing: what you can and cannot do to a version once it is out.
- Optional: Licence rules, quarantine and the audit log, the administrator's side of licence rules.