eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Refresh roadmap documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-31 17:34:41 +00:00
parent 01e408f4d5
commit 1d71a151cc
2 changed files with 84 additions and 642 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/policy/development.md
View File

@@ -71,7 +71,7 @@ GOCACHE=/private/tmp/distributor-gocache GOMODCACHE=/private/tmp/distributor-gom
- Prefer package-local helpers over broad abstractions until behavior is shared by multiple packages.
- Keep CLI parsing in `internal/cli`; business decisions belong in `internal/app`, `internal/bundle`, `internal/publish`, `internal/state`, and related core packages.
- Keep adapter packages thin. Backend-specific filesystem or service behavior belongs in adapters; bundle, state, transform, and publish policy belongs outside adapters.
- Preserve public CLI behavior, config semantics, manifest schema, destination state schema, and local MVP behavior unless the current task explicitly changes them.
- Preserve public CLI behavior, config semantics, manifest schema, destination state schema, and implemented backend behavior unless the current task explicitly changes them.
- Use `storage.DisplayPath`, `storage.StateFileName`, `storage.StatePath`, and `storage.ManagedBundleTargets` instead of duplicating those conventions.
- Use `bundle.ValidateManifest` for normalized source manifest semantics, including embedded source manifests in destination state.
- Use `config.ValidatePublishTransformPolicy` for publish and transform policy combinations.
@@ -105,9 +105,9 @@ When adding or changing configuration:
5. Update `docs/config.md` in the same change if current user-visible config behavior changes.
6. Update examples only with configs that are valid and executable for implemented behavior.
Config validation may accept fields for backends that are not executable yet,
but user-facing docs and examples must clearly state execution support. At the
time of this policy, local, SSH, and S3 backends are executable.
Config validation may accept fields for roadmap backends before execution
support exists, but user-facing docs and examples must clearly state execution
support. Runtime executable backends are local, SSH, and S3.
Credential-consuming code must use the config-owned environment resolver for
explicit credential environment variable references. Do not call `os.Getenv`
@@ -128,7 +128,7 @@ When adding or changing commands or flags:
4. Update `docs/cli.md` if syntax, flags, output expectations, or workflows change.
`validate` and `inspect` are local path commands. `run` loads configured
pipelines and currently executes local, SSH, and S3 backends.
pipelines and executes local, SSH, and S3 backends.
## Storage Backends
@@ -184,13 +184,14 @@ for test-only controls.
## Examples
Examples under `examples/` must be valid, maintained, and free of secrets.
They should be copyable for implemented behavior. Do not leave examples that
look runnable but require unsupported backend execution.
They should be copyable for implemented behavior. Remote examples must use
placeholders or environment variables for endpoint and credential material.
When changing examples:
1. Keep paths relative to the repository where practical.
2. Prefer local examples until remote backend support exists.
2. Keep local examples runnable without external services; gate remote examples
behind user-provided endpoints and credentials.
3. Run `go test ./internal/config` because config tests load examples.
4. Update README, CLI, or config docs if links or recommended workflows change.