Publish your first package

pack, publish --dry-run, publish, and what the hub keeps

Chapter 16 of 34Current for Gritpack 1.2.63Source: docs/guide/16-publish-your-first-package.md

Reading packages is harmless and can always be undone. Publishing is the one place where Gritpack asks you to slow down, because a published version is permanent: once @ada/greet 0.1.0 exists on a hub, those bytes are what every project that asks for it will get, forever. This chapter walks through the whole flow with a small C library: describe the package, build it, check everything with a dry run, publish, and keep the record of what landed.

What you will be able to do

  • turn a directory into a package with a gritpack.toml;
  • build the package file locally with gritpack pack;
  • run every check, locally and with the hub, without publishing anything;
  • publish, and read the receipt Gritpack prints;
  • understand why a version can never be changed, and what to do instead.

Before you start

You need two things:

  1. A login to a hub you may publish to. Reading needs no account, but every change does. gritpack auth status should show your account. If it does not, see Logging in. The public hub, get.gritpack.org, does not take publications from the public; this chapter uses a private hub you were invited to.

  2. The right to the name. A scoped name such as @ada/greet needs your account to own the scope @ada. gritpack auth status lists the scopes you can write:

    $ gritpack auth status
    

account=01a1e866-0f88-7a53-b8fe-d10b69bab7ef email=ada@example.com status=Active credential=01a1e866-2356-7c22-86a8-313961ffe866 status=Active expires_at=1797492370 writable_scope=@ada

If it says writable_scopes=none, claim one with gritpack scope claim ada or ask your hub's administrator. Names, scopes and owners explains the rules.

A package directory

Start with an ordinary directory of files:

greet/
  include/greet.h
  src/greet.c
  README.md
  LICENSE

gritpack init writes the smallest manifest that names the package:

$ gritpack init @ada/greet --dialect c/c23
initialized @ada/greet 0.1.0 dialect=c/c23 at ./gritpack.toml status=changed
[dependencies]

[package]
dialect = "c/c23"
name = "@ada/greet"
version = "0.1.0"

Those three fields are the package's identity: its name, its version, and its dialect, the language and version it is written in. (A small mental model covers dialects, encodings and targets.)

The first dry run, and the first refusal

Before writing anything more, ask Gritpack what would happen:

$ gritpack publish --dry-run
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:2826840f... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
...
publication verification plan=sha256:2826840f... repository=550e8400-e29b-41d4-a716-446655440000 result=Blocked generation=sha256:811272b7... attestation_threshold=0
  native:@ada/greet@0.1.0:c/c23:-:-: Blocked
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
    PUBLICATION_DOCUMENTATION_REQUIRED: Failed: @ada/greet has no README; every publication needs one with at least 100 words of prose. To publish without one anyway, give your reason: `gritpack publish --without-readme "<reason>"`, ...
publication verification blocked

The command exits with code 6, a conflict, and nothing reached the hub. Two things in it are worth noticing.

First, the authority check passed: the hub agrees that this account may publish @ada/greet. Second, the hub refused because the package has no README. There is a README.md in the directory, but the manifest does not say so, and Gritpack never guesses which files mean what. Every hub requires every new version to carry a README of at least 100 words and a licence declaration. README and licence explains the rule and the rare cases where you may go without.

Describe the package properly

Fill in the rest of the manifest:

[package]
name = "@ada/greet"
version = "0.1.0"
dialect = "c/c23"
description = "A tiny C library that says hello"
keywords = ["example", "greeting"]
readme = "README.md"
license = "MIT"
license-files = ["LICENSE"]
files = ["include/**", "src/**", "README.md", "LICENSE"]

[dependencies]
  • description is the one line people see in search results, at most 512 bytes.
  • keywords help search; at most 32, each at most 64 bytes, stored in lowercase.
  • readme names the README file inside the package.
  • license is an SPDX licence expression, such as MIT or Apache-2.0 OR MIT. license-files lists the licence texts you ship.
  • files chooses what goes into the package, with ** matching any depth. Without it, every regular file under the directory is included, except the top-level .git, .gritpack and target directories. gritpack.toml is always included.

None of these change the package's identity, but none of them can be changed after publication either, so it pays to get them right now.

Build the package file

You do not have to build the package yourself; publish does it for you. But gritpack pack shows exactly what will be published, and is useful when you want to look before you leap:

$ gritpack pack --output ../greet-0.1.0.gpk
packed @ada/greet 0.1.0 dialect=c/c23 files=5 payload_sha256=2d2f390ac4efb42894609b4d58c9651cf436c59ae07122863ffa3a7b542ee5f4 -> ../greet-0.1.0.gpk

A package file is one file holding the manifest, the chosen files and their digests. The name and extension are yours to choose. Packing is deterministic: the same directory always produces the same bytes, so you can build it twice, on two machines, and compare digests.

From C/C++. Nothing is compiled. A package carries the files you list, byte for byte: headers, sources, prebuilt libraries, whatever your build needs. Your build system stays yours. C and C++ shows how a consumer uses them.

The dry run again

$ gritpack publish --dry-run
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:73c67995... result=RequiresRemoteVerification nodes=1 edges=0 output=./.gritpack/publication-plan.json
native:@ada/greet@0.1.0:c/c23:-:- adapter=Native status=Indeterminate artifact=.gritpack/publication/artifacts/...
  check=PUBLICATION_METADATA_COMPLETE status=Passed — gritpack.toml declares description, README, licence
  check=PUBLICATION_DOCUMENTATION_POLICY status=Passed — README and licence meet the hub's documentation policy
  check=PUBLICATION_LICENSE_DECLARED status=Passed — MIT
publication verification plan=sha256:73c67995... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable generation=sha256:b6dc691f... attestation_threshold=0
  native:@ada/greet@0.1.0:c/c23:-:-: New
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
dry run complete; registry was not mutated

A dry run has two halves.

  • The plan, worked out on your machine. Gritpack built the package file into .gritpack/publication/artifacts/, ran its local checks, and wrote the whole plan to .gritpack/publication-plan.json. You, or a reviewer, can read that file.
  • Verification, done by the hub. It checked that you own the name, that the version is new (New), and that the package meets the hub's rules. result=Publishable means the real publish would go through.

The last line is the promise: nothing on the hub changed. The built file is byte for byte the one gritpack pack wrote a moment ago; their SHA-256 digests match.

Publish

gritpack publish

On a terminal, Gritpack shows the same plan and asks once:

Publish this immutable plan? [y/N]

Type y. When there is no terminal to ask in, for example in a script or CI, it refuses instead of guessing:

$ gritpack publish < /dev/null
...
publication requires --yes when input is non-interactive or structured output is selected

That run exits with code 2. Pass --yes once you have read the dry run:

$ gritpack publish --yes
...
committed publication transaction=01a1e870-5edc-7853-ba87-c383c8471c70 plan=sha256:73c67995... generation=sha256:59116ff0... nodes=1
  native:@ada/greet@0.1.0:c/c23:-:-: New storage_id=01M7M70QPWF19VN1Y3J95JHWBM digest=sha256:1504292e5770846383bfd0296fcc7f78af02e2283fede1d4f03f7144d9b5d379

The receipt

Those two lines are your receipt:

  • transaction identifies this publication on the hub. It is also the ID of the hub's signed receipt, which you can download and check later (Evidence and receipts).
  • plan is the digest of the plan that was published, the one in .gritpack/publication-plan.json.
  • generation identifies the state of the hub's catalogue that now includes your package.
  • storage_id is the hub's name for this exact published file. Most commands accept name@version instead (@ada/greet@0.1.0), but the storage ID is always exact.
  • digest is the SHA-256 of the published package file. Everyone who installs @ada/greet 0.1.0 from this hub gets a file with this digest, and Gritpack checks it every time.

You can ask the hub about the publication again at any time:

$ gritpack publication status 01a1e870-5edc-7853-ba87-c383c8471c70
publication transaction=01a1e870-5edc-7853-ba87-c383c8471c70 state=Committed plan=sha256:73c67995... nodes=1 expires_at=1794904640

For automation. gritpack publish --yes --json prints the receipt as one JSON document, and --format ndjson prints one record per line as the work happens. Keep it with your build's other records.

Look at what you published

Your package is visible to everyone who can read the hub:

$ gritpack search greet
@ada/greet 0.1.0 ecosystem=native score=900 dialect=c/c23 variants=1 — A tiny C library that says hello
$ gritpack info @ada/greet
@ada/greet 0.1.0 (native)
  A tiny C library that says hello
  dialect: c/c23
  versions: 0.1.0
  variants: 1
  license: MIT
  owner: 01a1e866-0f88-7a53-b8fe-d10b69bab7ef
  ...
  sha256: 1504292e5770846383bfd0296fcc7f78af02e2283fede1d4f03f7144d9b5d379

A scope decides who may publish a name, not who may see it. Everyone with access to the hub can find and use @ada/greet. Privacy comes from the hub: packages on a private hub are seen only by that hub's users.

Why a version never changes

Every lock file that records @ada/greet 0.1.0 records its digest too. If the bytes behind that version could change, every one of those projects would silently build something else tomorrow. So the hub keeps the version exactly as published.

Publishing the same thing again is harmless. Gritpack recognises the plan and gives you the same receipt:

$ gritpack publish --yes
...
    PUBLICATION_IDENTITY_SATISFIED: Passed: the immutable identity already contains this artifact
publication transaction 01a1e866-b38a-7bf2-ac3e-325932fcf48a is already Committed; finishing its commit
committed publication transaction=01a1e866-b38a-7bf2-ac3e-325932fcf48a ...

Publishing something different under the same version is refused:

$ gritpack publish --dry-run
...
  native:@ada/hello-tool@1.1.0:application/cli:executable/native:x86_64-unknown-linux-gnu: Conflict
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
    PUBLICATION_IDENTITY_CONFLICT: Failed: the immutable identity is occupied by different content
publication verification blocked

There is no overwrite flag. A mistake is fixed forward: raise the version in gritpack.toml and publish 0.1.1. You can steer people away from the old version with a deprecation or a yank, covered in After publishing.

Publishing a package file you already built

gritpack publish also accepts a package file instead of a directory:

gritpack publish ../greet-0.1.0.gpk --yes

This sends the file as it is, without a plan. Hubs that keep signed records of every publication accept new versions only through a plan, and refuse a bare file:

$ gritpack publish textkit-0.1.2.gpk --yes
the hub answered HTTP 409: repository evidence policy requires the publication transaction API

If you meet this, publish the directory instead. The directory route is also the only one where you can give the reasons described in README and licence.

What just happened

  • gritpack init named the package; you described it in gritpack.toml.
  • gritpack pack built a deterministic package file you could inspect.
  • gritpack publish --dry-run built the same file, wrote a plan, and had the hub verify it, without changing anything.
  • gritpack publish asked once (or took --yes), then committed the version and printed a receipt with its storage ID and digest.
  • The version is now permanent. Every fix is a new version.

You can stop here

If you publish an occasional package, this is the whole everyday flow.

Next

  • README and licence explains the documentation every version needs, and what to do when the hub refuses a licence.
  • Optional: Publishing step by step for several packages at once, and for publishing in separate plan, verify and publish steps.