Developing

#Dogfood layout

Same trees under modules/*/src: the green path is dogfood (project/meta-* mirrors → root loads from source). The amber path is the publishable plugin project for Central and scripted.

• project/meta-{workflow,core,central,plugin} compile the same modules/*/src/main/scala trees

• Shared versions live in project/Dependencies.scala

• project/*.sbt cannot see project/*.scala directly (sbt layering). project/project/build.sbt pulls Dependencies.scala / Dogfood.scala onto that classpath via unmanagedSources (no symlinks)

After changing sources under modules/{workflow,core,central,sbt-plugin}: reload, then zipxWorkflowGenerate if planner output changed.

Action pins: edit .github/zipx/action-pins.yml (not under workflows/), then regenerate. Or let Dependabot bump workflow uses: and run sbt zipxActionsPull (dogfood enables zipxDependabotSync := true for the automatic sync workflow). Published jar defaults embed this pin file via resourceGenerators. See the Action pins docs page.

When adding a library dependency used by those modules: update project/Dependencies.scala only.

When adding a mirrored module: add a meta* project in project/dogfood.sbt, create project/meta-<name>/, and wire dependsOn like the existing chain.

The publishable plugin project remains for Central publish and scripted tests. examples/monorepo is a consumer (uses publishLocal or a released sbt-zipx). Root dogfood uses Aggregate ZipxCentral.release and ZipxDocs.pages, both with JobCondition.repositoryIs("early-effect/zipx") so fork tag pushes do not publish or deploy Pages.

Remote-cache IT lives in modules/it (not Aggregate). Run sbt it/test (Docker required). CI runs it as a parallel Verify job (remote-cache-it, needs verify-gate only). Pins and live Put/Get are documented under Remote cache for teams / RemoteCacheProof.

#Docs site

Docs are Specular DocSpecs under docs/src/test/scala:

sbt docs/test
sbt docs/specularSite
sbt docs/specularServe   # one-shot preview
sbt docsPreview          # watch: ~docs/specularPreview (rebuild + restart DocsServe)

Open http://127.0.0.1:8765/ while docsPreview is running. Pages deploy on v* tags or manual workflow_dispatch (zipxWorkflowDispatch := true) via ZipxDocs.pages in the generated workflow. Verify is skipped on dispatch so a docs-only refresh does not re-run the full test suite. Install / chrome versions use specularDisplayVersion (last stable tag when dynver is *-ci) so docs-only deploys do not advertise -ci coordinates.

#Status

See ROADMAP.md. The plugin targets sbt 2.x / Scala 3.8.4. License: Apache-2.0.