Releasing a workspace

release-plan, publishing members together, all or none

Chapter 24 of 34Current for Gritpack 1.2.63Source: docs/guide/24-releasing-a-workspace.md

Your workspace's packages depend on each other. When you release, people on the hub must never see the new application before the new library it needs, and a failure halfway must not leave half a release behind. This chapter shows how Gritpack turns a workspace into one release: it works out which members must go together, checks the whole set with the hub before uploading anything, and makes every new version visible at the same moment, or none of them.

What you will be able to do

  • see which members a release must include, and why;
  • check a whole release with the hub without publishing it;
  • publish every member, or only some, in one all-or-nothing step;
  • keep members that must move together in a release group;
  • understand the three answers a hub gives for each package: new, already there, or in conflict.

It continues the workspace from Workspaces: @bea/core, @bea/fmt (needs core) and @bea/report (needs both, and @ada/greet from the hub).

Which members go together

Ask before you publish:

$ gritpack workspace release-plan
release roots=@bea/core,@bea/fmt,@bea/report closure=@bea/core,@bea/fmt,@bea/report groups=0 blockers=0

With no --member, the release includes every publishable member. Name one, and Gritpack adds everything it needs from the workspace:

$ gritpack workspace release-plan --member @bea/fmt
release roots=@bea/fmt closure=@bea/core,@bea/fmt groups=0 blockers=0

You asked for the formatting library; it cannot be installed without the core, so the core is in the closure, the full set that will be published. @ada/greet is not in it: it is already published on the hub and is not yours to release.

Release groups

Some members should always be released together even when only one changed, for example a library and its companion headers, or a client and a server that speak the same protocol. Give them the same release_group in gritpack-workspace.toml:

[[members]]
path = "libs/core"
adapter = "native"
role = "publishable"
release_group = "text"

[[members]]
path = "libs/fmt"
adapter = "native"
role = "publishable"
release_group = "text"

Now asking for the core brings its group along:

$ gritpack workspace release-plan --member @bea/core --json
{
  "blockers": [],
  "closure": [
    "@bea/core",
    "@bea/fmt"
  ],
  "expanded_roots": [
    "@bea/core",
    "@bea/fmt"
  ],
  "groups": {
    "text": [
      "@bea/core",
      "@bea/fmt"
    ]
  },
  "requested_roots": [
    "@bea/core"
  ],
  "schema": "gritpack/workspace-release-set@1"
}

requested_roots is what you asked for; expanded_roots adds the group; closure adds what those need. gritpack publish --member uses exactly this set.

Blockers

A member whose role is not publishable can never be released, and neither can anything that needs it. If the core were marked internal-only:

$ gritpack workspace release-plan --member @bea/fmt
release roots=@bea/fmt closure=@bea/core,@bea/fmt groups=0 blockers=1
blocked package=@bea/core member=libs/core role=InternalOnly reason=publishable closure depends on a non-publishable editable member

Publishing stops at the same point, before anything is built or uploaded:

$ gritpack publish --dry-run --member @bea/fmt
...
invalid workspace: immutable release is blocked by @bea/core (InternalOnly): publishable closure depends on a non-publishable editable member

The fix is a decision for you: make the core publishable, or stop depending on it from a published package.

Checking a release without publishing

workspace verify --immutable does everything a release does except publish: it builds a package file for every member in the release, writes a plan, and asks the hub to check it.

$ gritpack workspace verify --immutable
immutable workspace verified plan=sha256:37598609d72cfb817ce2e4c8216f04442d6e63f44afb9e1ad1460bd52bc2bca4 result=Publishable nodes=3 mutated=false output=./.gritpack/immutable-verification-plan.json

result=Publishable and mutated=false: the hub would accept all three, and nothing changed anywhere. It takes --member like the other workspace commands. gritpack publish --dry-run gives the same answer with the full report; use whichever reads better in your CI logs.

Publishing the release

From the workspace root, gritpack publish publishes the whole release. It shows its plan and the hub's verdict, asks you to confirm on a terminal, and then commits. Here it is with --yes, the per-package checks shortened:

$ gritpack publish --yes
planning publication; Cargo members may run cargo metadata/package and rustc version checks
publication plan=sha256:37598609d72c... result=RequiresRemoteVerification nodes=3 edges=3 output=./.gritpack/publication-plan.json
native:@bea/core@0.1.0:c/c23:-:- adapter=Native status=Indeterminate artifact=...
native:@bea/fmt@0.1.0:c/c23:-:- adapter=Native status=Indeterminate artifact=...
  @bea/core ^0.1.0 -> publication-set status=Internal
native:@bea/report@0.1.0:c/c23:-:- adapter=Native status=Indeterminate artifact=...
...
publication verification plan=sha256:37598609d72c... repository=550e8400-e29b-41d4-a716-446655440000 result=Publishable ...
  native:@bea/core@0.1.0:c/c23:-:-: New
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
  native:@bea/fmt@0.1.0:c/c23:-:-: New
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
  native:@bea/report@0.1.0:c/c23:-:-: New
    PUBLICATION_AUTHORITY_VERIFIED: Passed: publisher owns the package authority
    PUBLICATION_PREREQUISITE_AVAILABLE: Passed: @ada/greet ^0.2.0 is available at the destination
committed publication transaction=01a1e869-1090-71d1-adfe-70e59c6d7d4d plan=sha256:37598609d72c... generation=sha256:0c72b79f... nodes=3
  native:@bea/core@0.1.0:c/c23:-:-: New storage_id=01M7M6J44GE78TVZKGYQ9TB0YT digest=sha256:3ad4472f...
  native:@bea/fmt@0.1.0:c/c23:-:-: New storage_id=01M7M6J44GE78TVZKH1R3MGQ5H digest=sha256:cce60728...
  native:@bea/report@0.1.0:c/c23:-:-: New storage_id=01M7M6J44GE78TVZKH32PC352F digest=sha256:876164e5...

Reading it top to bottom:

  1. Plan. Gritpack built a package file for each member (under .gritpack/publication/artifacts/) and wrote the plan to .gritpack/publication-plan.json. The line @bea/core ^0.1.0 -> publication-set status=Internal says the formatting library's dependency on the core is satisfied inside this release. Members are listed in dependency order: the core before what needs it.
  2. Verification. The hub checked every package: you own the names, the versions are free, and every dependency outside the release (here @ada/greet ^0.2.0) is already available on the hub. It answered Publishable.
  3. Commit. The hub staged all three files out of sight, then made them visible in one step. The transaction ID identifies this release; keep it for its signed receipt (Evidence and receipts).

Until that last step, nobody searching or installing from the hub could see any of the three. After it, they see all three. There is no moment when @bea/report 0.1.0 is visible but the core it needs is not, and if anything fails before the commit, the hub keeps none of it.

From Cargo. cargo publish --workspace publishes crates one after another, so a failure in the middle leaves some crates published. A Gritpack release is one transaction: all of it or none of it. For Cargo members in a workspace, Cargo still builds and checks each crate itself; Gritpack adds the all-or-nothing publication around them (Rust and Cargo).

Publishing some members

--member publishes a member and its closure, exactly as release-plan showed:

$ gritpack publish --dry-run --member @bea/fmt
...
publication plan=sha256:c64257b5... result=RequiresRemoteVerification nodes=2 edges=1 output=./.gritpack/publication-plan.json
...
dry run complete; registry was not mutated

Two nodes: the formatting library and the core it needs. Repeat --member for several.

New, satisfied and conflict

You will rarely change every member for a release. Gritpack does not make you pick out the changed ones: publish the workspace, and the hub sorts each package into one of three answers.

After a fix to the core, released as 0.1.1, with the other two unchanged:

$ gritpack publish --yes
...
  native:@bea/core@0.1.1:c/c23:-:-: New
  native:@bea/fmt@0.1.0:c/c23:-:-: Satisfied
    PUBLICATION_IDENTITY_SATISFIED: Passed: the immutable identity already contains this artifact
  native:@bea/report@0.1.0:c/c23:-:-: Satisfied
    PUBLICATION_IDENTITY_SATISFIED: Passed: the immutable identity already contains this artifact
...
committed publication transaction=01a1e871-57bb-7a92-a7e6-858865550bce ... nodes=3
  • New: this version does not exist yet; it is published.
  • Satisfied: this exact version, byte for byte, is already on the hub; nothing is uploaded and the release still succeeds. Package files are built deterministically, so unchanged sources give identical files.
  • Conflict: the version exists with different content.

A conflict blocks the whole release. It happens when you change a member and forget to raise its version:

$ gritpack publish --dry-run
...
  native:@bea/core@0.1.0:c/c23:-:-: Conflict
    PUBLICATION_IDENTITY_CONFLICT: Failed: the immutable identity is occupied by different content
...
publication verification blocked

The command exits with code 6, "conflict". Published versions never change (After publishing), so the only fix is a new version number for the member you changed.

The same rule makes a release safe to repeat. If your connection drops after you confirmed, run the same command again: what was committed is now Satisfied, and nothing is published twice.

After the release

People who depend on your packages get them the ordinary way. In another project, gritpack update picks up the new core within its requirement:

$ gritpack update
updated 4 packages status=changed
$ gritpack list
@ada/greet 0.2.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
@bea/core 0.1.1 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
@bea/fmt 0.1.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=@bea/core
@bea/report 0.1.0 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=@ada/greet,@bea/core,@bea/fmt

Inside the workspace nothing changes: members keep using each other's working copies.

When you need more control

gritpack publish does plan, verify and commit in one go. For a release that is built on one machine and published from another, approved by a person in between, or interrupted and resumed, the same steps are available one at a time: gritpack publication plan, verify, publish, status, resume and abort. Publishing step by step covers them. A workspace can also mix ecosystems, with Cargo, npm and Go members beside native ones; the chapters for each ecosystem say what is different.

What just happened

  • workspace release-plan shows which members a release includes: the ones you asked for, their release groups, and everything they need.
  • workspace verify --immutable and publish --dry-run check the whole release with the hub and change nothing.
  • gritpack publish builds, checks and commits every member in one transaction; dependents never appear before what they need.
  • Each package is New, Satisfied or in Conflict, so unchanged members cost nothing and a release can be safely repeated.

You can stop here

Teams that develop several packages in one repository now have the full path from editable source to a published release. If you do not need to prove later who published what, you can stop.

Next