ike-example-ws
IKE Example Workspace 22-SNAPSHOT

workspace.yaml — Annotated Tour

workspace.yaml is the manifest of an IKE workspace. It’s the source of truth for which subprojects this workspace orchestrates, where they live in Git, what branch they track, and the dependency relationships that drive ws:* goal ordering.

This page walks through ike-example-ws/workspace.yaml field by field. Use it as a template when authoring a new workspace.

File location

A workspace’s manifest always lives at:

<workspace-root>/workspace.yaml

The ws:* goal family reads it on every invocation. The workspace root is detected by walking up from pwd looking for a directory that contains both workspace.yaml and pom.xml.

Schema

schema-version: "1.0"
generated: 2026-04-23

defaults:
  branch: main
  maven-version: "4.0.0-rc-5"

subprojects:
  doc-example:
    repo: https://github.com/IKE-Network/doc-example.git
    version: 1-SNAPSHOT
  example-project:
    repo: https://github.com/IKE-Network/example-project.git
    version: 1-SNAPSHOT

schema-version

Identifies the manifest format. Bumped when the schema gains breaking changes; ws:align-publish migrates legacy schemas in place. Current value is "1.0".

generated

Date stamp of the last ws:scaffold-init or ws:align-publish rewrite. Informational; does not affect goal behavior.

defaults

Default values applied to every subproject that doesn’t override them. Two fields supported:

  • branch — the git branch each subproject tracks. The workspace-branch-coherence rule (ike-issues[1] — see feedback_workspace_branch_coherence) requires every subproject to track the same branch as the workspace root, so this is typically main.
  • maven-version — the Maven Wrapper version each subproject resolves on ws:scaffold-init and on mvn -N invocations. Pinned to a Maven 4 RC (4.0.0-rc-5) for the IKE Network’s modelVersion 4.1.0 POMs.

subprojects

The map of subprojects under workspace orchestration. Each entry’s key is the subproject name (typically matching the artifact ID and the directory name under the workspace root). Per-entry fields:

  • repo — git URL the subproject is cloned from on ws:scaffold-init.
  • version — release version pin (tag) or <n>-SNAPSHOT for HEAD tracking. ws:scaffold-publish writes this when the workspace releases the subproject; ws:scaffold-init checks out the corresponding commit on a fresh clone.

Optional per-subproject fields not exercised in ike-example-ws:

  • branch — override the default branch.
  • parent — an explicit subproject-name reference for the Maven parent POM, used by ws:scaffold-draft and ws:align-publish to enforce parent version alignment across the workspace.
  • sha — pin a specific git commit SHA (typically written by ws:checkpoint-publish). When present, overrides version for ws:scaffold-init purposes.

Why ike-tooling, ike-docs, ike-platform are NOT subprojects

ike-example-ws/workspace.yaml lists exactly two subprojects: doc-example and example-project. The IKE Network foundation repos — ike-tooling, ike-docs, ike-platform — are intentionally not under workspace orchestration. Three reasons:

  1. ike-tooling is the bootstrap. It produces ike-maven-plugin, which the workspace plugin itself depends on. Putting ike-tooling inside a workspace creates a chicken-and-egg problem: the workspace can’t bootstrap before the plugin it needs is installed.
  2. ike-platform contains ike-workspace-maven-plugin AND ike-parent. The first defines the ws:* goals; the second is the release-tracked parent POM the workspace itself inherits. That self-reference triggers a Maven 4 reactor parent-cycle bug (ike-parent:N → workspace pom.xml → ike-parent:N).
  3. ike-docs provides ike-doc-maven-plugin. Same release-cadence argument as the others: it lives above the consumer line in the cascade, releases independently via its own ike:release-publish, and is consumed at released versions from Nexus rather than co-developed inside any workspace.

The corollary: when the foundation repos release (e.g., ike-tooling 150 → ike-docs 12 → ike-platform 34), this workspace picks up the new versions by running:

# Today: detection only — reports parent + property drift
mvn ike:scaffold-draft

# Post-#348: detection + apply in one command
mvn ike:scaffold-publish

The scaffold zip embeds the tested-together foundation versions at ike-tooling release time (#345). Running scaffold-draft shows what’s behind; scaffold-publish (post-#348) applies the bumps. For specific-version overrides (reproducibility testing, partial-cycle rollback), ws:scaffold-publish -DparentVersion=N remains available — but the routine "bump to current" workflow collapses to a single scaffold command.

Foundation repos themselves are never under ws:* control — they release independently via their own ike:release-publish.

How ws:* goals consume this file

Goal What it reads from workspace.yaml What it writes back
ws:scaffold-init repo, branch, version, sha for each subproject Nothing — this is read-only.
ws:overview Whole manifest Nothing — produces the ws꞉overview.md report at the workspace root.
ws:sync branch, version per subproject Updates the on-disk repo state to match the manifest (or vice versa, depending on -Dfrom=…​).
ws:scaffold-publish Reads the parent declaration in each subproject’s POM (not workspace.yaml directly) Updates each subproject’s <parent> block in its pom.xml to the requested version. Commits per subproject. Does not touch workspace.yaml itself.
ws:release-publish Whole manifest (build order, dependencies) Walks subprojects in topological order and runs ike:release-publish on each that has source changes since its last release tag. After all subprojects release, releases the workspace root last when it has its own unreleased changes (#326+#328). Does not rewrite workspace.yaml per-subproject version: fields — those remain at the workspace’s HEAD-tracking value (typically 1-SNAPSHOT); the durable per-cycle anchor is the workspace’s own release tag plus any ws:checkpoint-publish snapshots under checkpoints/.
ws:align-publish Whole manifest Migrates legacy schema (components: → subprojects: for the pre-#150 schema, etc.). Writes back the migrated form.
ws:scaffold-draft Whole manifest Nothing — runs read-only checks (parent-version alignment, branch coherence, working-tree cleanliness, etc.).

Relationship to the workspace pom.xml

The workspace root has both workspace.yaml and pom.xml. They serve different purposes:

  • workspace.yaml is the manifest — declarative, IKE-specific, consumed by ws:* goals.
  • pom.xml is a standard Maven aggregator — declares <subprojects> for normal Maven reactor operations (mvn clean install walks the reactor in topological order).

The two stay synchronized: each entry in workspace.yaml.subprojects has a matching <subproject>name</subproject> in pom.xml. The ws:scaffold-init and ws:add goals write both files atomically to keep them in sync; ws:scaffold-draft flags drift.

See also

IKE workspace aggregator ws goals multi-repo integration test IKE Network
Links:
  • [1] https://github.com/IKE-Network/ike-issues
  • [2] index.html
  • [3] https://ike.network/ike-example-its/
  • [4] https://ike.network/ike-platform/ike-workspace-maven-plugin/ws-goals.html
Date: 2026-05-19 12:25:23 -0700
Searching...
No results.