Add implementation roadmap for the next feature set
This commit is contained in:
179
docs/roadmap/link_generation.md
Normal file
179
docs/roadmap/link_generation.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# Roadmap: Link Generation Support
|
||||
|
||||
## Purpose
|
||||
|
||||
Add destination-aware link generation so distributor can record human-usable URLs
|
||||
for published artifacts.
|
||||
|
||||
This feature should be implemented after destination path mapping so generated
|
||||
URLs use the final archive or fixed destination path semantics. It prepares the
|
||||
project for notification adapters, richer inspect/status output, static-site UX,
|
||||
and future feed generation.
|
||||
|
||||
## Current Implementation Grounding
|
||||
|
||||
Current publish planning produces `publish.Output` values with destination path,
|
||||
source path, kind, transform, SHA-256, size, and optional generated data.
|
||||
|
||||
Current `.distributor.json` output records contain path, kind, source path,
|
||||
transform, SHA-256, and size. They do not contain URL metadata, and destination
|
||||
state has no top-level links block.
|
||||
|
||||
Current destination bundle paths preserve the source-root-relative bundle path.
|
||||
Latest/fixed path mapping is not implemented yet.
|
||||
|
||||
## Goals
|
||||
|
||||
- Add optional destination-level link configuration.
|
||||
- Generate per-output URLs when a destination has `links.base_url`.
|
||||
- Record generated URLs in destination state when configured.
|
||||
- Select a deterministic primary URL when possible.
|
||||
- Keep link generation destination-local and independent of producer manifests.
|
||||
- Do not infer public URLs from backend configuration automatically.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not deliver notifications.
|
||||
- Do not require every destination to expose URLs.
|
||||
- Do not add static-site indexes or feeds.
|
||||
- Do not add latest path mapping.
|
||||
- Do not change source manifest schema.
|
||||
|
||||
## Configuration Shape
|
||||
|
||||
Add optional destination-level config:
|
||||
|
||||
```yaml
|
||||
links:
|
||||
base_url: https://weather.example.com
|
||||
primary: auto
|
||||
```
|
||||
|
||||
Semantics:
|
||||
|
||||
- `links.base_url`: absolute HTTP or HTTPS URL corresponding to the destination
|
||||
backend root.
|
||||
- `links.primary`: optional primary-link selection policy.
|
||||
|
||||
Initial `primary` policies:
|
||||
|
||||
- `auto`: choose the best available output;
|
||||
- `html`: prefer generated HTML outputs;
|
||||
- `source`: prefer copied source outputs.
|
||||
|
||||
If `links` is absent, no URL metadata is generated.
|
||||
|
||||
## URL Construction
|
||||
|
||||
Construct URLs from:
|
||||
|
||||
1. `links.base_url`;
|
||||
2. destination bundle path relative to the destination backend root;
|
||||
3. output path relative to the destination bundle path.
|
||||
|
||||
Use URL path joining and escaping rules, not filesystem or storage path joins.
|
||||
Preserve any path prefix in `base_url`. Reject `base_url` values with query
|
||||
strings or fragments.
|
||||
|
||||
For `index.html`, generate a directory-style URL by omitting the filename:
|
||||
|
||||
```text
|
||||
https://weather.example.com/daily/brentwood/2026-06-01/
|
||||
```
|
||||
|
||||
For other outputs, include the output filename:
|
||||
|
||||
```text
|
||||
https://weather.example.com/daily/brentwood/2026-06-01/report.html
|
||||
```
|
||||
|
||||
`index.html` recognition should apply to any output path ending in
|
||||
`/index.html` or exactly `index.html`.
|
||||
|
||||
## Primary Link Selection
|
||||
|
||||
For `primary: auto`, select in deterministic publish-plan order:
|
||||
|
||||
1. any `index.html` output;
|
||||
2. first generated HTML output;
|
||||
3. first source output;
|
||||
4. no primary URL.
|
||||
|
||||
For `primary: html`, prefer generated HTML outputs. For `primary: source`,
|
||||
prefer source outputs. If no output matches the policy, record no primary link
|
||||
rather than failing publication.
|
||||
|
||||
## Destination State
|
||||
|
||||
When links are configured, destination state should record:
|
||||
|
||||
- optional per-output URL metadata;
|
||||
- optional top-level primary URL metadata.
|
||||
|
||||
Destinations without `links` should continue producing state without URL
|
||||
metadata.
|
||||
|
||||
Because distributor is still pre-release, URL metadata should be added as
|
||||
optional state schema version 1 fields rather than introducing destination state
|
||||
schema version 2 for this feature. Post-release, materially richer state
|
||||
semantics should use an explicit schema versioning policy.
|
||||
|
||||
## Relationship To Other Roadmaps
|
||||
|
||||
HTML index mode is not required, but link generation should treat `index.html`
|
||||
as the preferred URL shape when present.
|
||||
|
||||
Latest path destinations should provide the destination bundle path mapping
|
||||
needed to build fixed/latest URLs correctly.
|
||||
|
||||
Producer-facing manifest creation and remote validation are independent of URL
|
||||
metadata.
|
||||
|
||||
CLI display of generated primary links should follow
|
||||
`docs/roadmap/cli_output_policy.md` so link output is exposed through the shared
|
||||
`--format text|json` model rather than one-off command output.
|
||||
|
||||
## Testing Expectations
|
||||
|
||||
Suggested coverage:
|
||||
|
||||
- config validation accepts absent `links`;
|
||||
- config validation accepts valid HTTP and HTTPS base URLs;
|
||||
- config validation rejects invalid schemes, query strings, and fragments;
|
||||
- nested bundle paths generate correct URLs;
|
||||
- `index.html` URLs omit the filename;
|
||||
- non-index URLs include filenames;
|
||||
- primary selection is deterministic;
|
||||
- state records URLs when configured;
|
||||
- destinations without `links` produce no URL metadata.
|
||||
|
||||
## Documentation Updates After Implementation
|
||||
|
||||
- Update `docs/config.md` with destination `links` fields.
|
||||
- Update `docs/operations.md` with static-site URL examples.
|
||||
- Update `docs/internal/state.md` if destination state changes.
|
||||
- Update `docs/cli.md` only if run or inspect output displays links.
|
||||
|
||||
Keep this roadmap under `docs/roadmap/` until implemented.
|
||||
|
||||
## Decisions
|
||||
|
||||
- URL metadata is added as optional destination state schema version 1 fields
|
||||
while distributor remains pre-release.
|
||||
- v1 implements `links.primary` so future notification and operator-output
|
||||
features have one canonical primary-link selection policy.
|
||||
- `run` and `inspect` output should not display generated primary links
|
||||
immediately. Link display should wait for
|
||||
`docs/roadmap/cli_output_policy.md` or another explicit inspect/status output
|
||||
mode.
|
||||
|
||||
## Future Work
|
||||
|
||||
- Define a post-release destination state schema bump policy before introducing
|
||||
materially incompatible state changes.
|
||||
- Add CLI display of primary links through an explicit output mode or status
|
||||
command, preferably the shared `--format text|json` policy in
|
||||
`docs/roadmap/cli_output_policy.md`, rather than changing routine `run`
|
||||
output opportunistically.
|
||||
- Add richer link policies only if `auto`, `html`, and `source` prove
|
||||
insufficient.
|
||||
Reference in New Issue
Block a user