wso2 / wso2/wso2-cli

wso2 bundle is superseded by release variants under the monorepo: say so in the documents

Open
#140 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

ready-for-agent Type/Task
Dominant language
Go
Stars
0
Forks
3
Avg merge
8h 43m
Merged PRs (30d)
60

Description

wso2 bundle create, wso2 bundle inspect and wso2 bundle install are published in docs/reference/commands.md, specified in architecture.md §7.5, and required at P1 in product-requirements.md. They should not be built as specified, and the documents should say so.

Why the design no longer fits

The bundle commands exist because modules were going to live in separate repositories and be published independently. ADR 0006 pairs them explicitly: "wso2 bundle and third-party module publishing are deferred, not cancelled." If a module's releases are its own, assembling a coherent offline set is real work, and wso2 bundle create is where that work goes.

The monorepo removed that problem. Modules are built and released from one tree, and the catalog is generated from it, so a coherent set is what a release already is. The assembly bundle create was for now happens at release time.

The replacement is a release variant, not a command. Publish a shell-only release and a full release carrying the shell and the modules. An air-gapped user transfers the full one. No bundle command is needed for the fresh-machine path, which architecture.md §7.5 already concedes: "These commands are not prerequisites for fresh-machine installation."

What this does not solve

Signing. §7.5 describes a signed bootstrap, a signed catalog snapshot, and offline trust material. §9.2 says the opposite is true today: "Artifacts are integrity-checked and not signed… Nothing signs the catalog, so the integrity of the manifest itself rests on HTTPS to the origin and on control of what is published there."

Offline, the HTTPS half is gone. A user who carries an artifact in on removable media has no origin to trust and no signature to check, so the digest has to arrive through some independently trusted channel or it establishes nothing about authenticity. Dropping bundle does not avoid this — it makes #80 the whole of the air-gapped trust story. Any release-variant work should wait on #80 or state plainly what it does and does not guarantee.

Tailoring. bundle create built a set for a named platform from selected modules. A full release is every module, which is fine at one and awkward at twenty. Revisit when a second product module exists.

Inspection. bundle inspect reported contents and verification state without installing — a real function for someone deciding whether to trust what they were handed. That belongs as a manifest inside the release rather than as a command.

What to change

  • docs/architecture.md §7.5 records that the three bundle commands are superseded by release variants under the monorepo, and that the fresh-machine path needs no CLI command
  • docs/adr/0006-monorepo-modules-and-generated-catalog.md notes that the deferral it recorded is now a supersession for bundle, third-party publishing being the part that remains deferred
  • docs/product-requirements.md's P1 offline-bundle requirements are restated in terms of release variants, keeping the requirement (an air-gapped machine can install the shell and modules with no network) and dropping the mechanism
  • The three bundle rows leave docs/reference/commands.md, so the reference stops publishing commands nobody intends to build
  • Both documents point at #80 as the unresolved trust question, rather than describing a signed model that does not exist

Refs #80. Split out of #112.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/architecture.md §7.5 and ADR 0006, then compare the P1 requirements in docs/product-requirements.md with the three entries in docs/reference/commands.md. Update the four named documents to describe release variants as the replacement, remove the superseded commands, preserve the air-gapped installation requirement, and point to #80 for the unresolved trust question.

Written by the indexing model from the issue text.

Assessment

Domain
cli, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.