flog
Documentation menu

Workspace release sets

flog publish validates that a workspace publication is coherent before it runs lifecycle scripts or mutates a registry. This complements release authoring tools: flog does not choose versions, edit manifests, or generate changelogs, but it refuses a mechanically valid yet incomplete release set.

The failure this prevents#

Suppose the registry contains core@1.9.0 and adapter@2.4.0. The published adapter depends on core@^1.9.0, while the workspace now contains adapter with core: workspace:^ and local core is 2.0.0. Packing adapter converts that declaration to core@^2.0.0.

Publishing core alone can leave local adapter code ahead of its published package. Publishing adapter as 2.5.0 would move its dependency across a compatibility boundary while advertising only a compatible adapter update. Flog therefore requires adapter in a new compatibility line, such as 3.0.0, and propagates that requirement to adapter's dependents.

workspace: conversion uses the current local workspace version; it does not mean the registry's latest tag. Registry tags only select the published baseline for comparison.

Compatibility lines#

Flog uses these conservative compatibility lines:

  • packages at 1.0.0 or above use their major version;
  • 0.x packages use their minor version;
  • every 0.0.x version is a separate line.

Thus 1.8 → 2.0, 0.4 → 0.5, and 0.0.4 → 0.0.5 propagate release requirements. Changes within 1.x or 0.4.x do not. A dependent is not forced into the release set when its actual published range already accepts the proposed dependency version, including a deliberately broad explicit range.

The baseline comes from the requested publication tag. A next publication is compared with next, not with an unrelated stable latest release.

Edges and availability#

Runtime, optional, and peer workspace dependencies participate in release closure. Development dependencies are reported for review but do not force publication. Private and never-published dependents create no public release obligation.

The workspace root participates when it is a public package: its workspace dependencies are checked when publishing the root, and its published manifest can require a release when a child crosses a compatibility line. A private root remains configuration only and creates no publication obligation. Public roots and public workspace children must have distinct package names; workspace discovery rejects an ambiguous duplicate publication identity.

Mutually dependent packages are analyzed as one deterministic release unit. Because uploads are still sequential, a cycle is publishable only when each forward range is satisfied by an existing registry version or by a package that can be uploaded earlier; otherwise the availability check blocks it.

Every selected package is also checked in the forward direction. Its converted workspace ranges must be satisfied by a registry version or a package in the dependency-first publication plan. This prevents references to versions that consumers cannot obtain.

Human and JSON plans record the package chain, dependency field, old and new versions, published and proposed ranges, required bump, corrective action, availability source, and override status.

Reviewing and overriding#

Inspect the complete plan without mutation:

flog publish --recursive --dry-run
flog publish --recursive --dry-run --json

Flog does not add packages or edit versions automatically. Fix the reported versions and selection, then rebuild the plan. If external knowledge proves a conservative blocker acceptable, use the dedicated override:

flog publish --recursive --allow-incomplete-release-set

Neither --yes nor a git override bypasses release-set checks. The dedicated override remains visible in the plan and final summary. Registry baselines for omitted affected packages are revalidated during execution; a change aborts publication rather than applying a stale decision.

Relationships visible through workspace dependencies need no configuration. Explicit release groups may be added later for packages coupled outside that graph. A future release-authoring command may edit versions and changelogs, but safe publication does not depend on such a command.