scout: update watch reference#24169
Conversation
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![docker-agent[bot]](https://avatars.githubusercontent.com/in/2787757?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Summary
This PR manually edits a YAML file in data/scout-cli/ which is documented as being generated from upstream sources. While the PR description acknowledges this is a temporary workaround, this creates a maintenance risk:
- Manual changes will be lost when upstream generation resumes
- The file may drift further from upstream over time
- Future contributors may unknowingly regenerate and overwrite these changes
Recommendation: Add a comment in the file or create a tracking issue to ensure this temporary workaround is addressed before the next upstream sync.
There was a problem hiding this comment.
Review Summary
High Severity Issue
This PR edits data/scout-cli/docker_scout_watch.yaml, which is generated from upstream (scout-cli repository). According to documentation standards, YAML files in data/*/*.yaml subdirectories are CLI reference data generated from upstream and should not be manually modified.
Why this matters:
- Manual edits will be overwritten on the next upstream sync
- Creates divergence between upstream and downstream documentation
- Makes maintenance difficult and error-prone
Recommended approach:
As mentioned in the PR description, the proper fix is to resolve the formatting issue in the upstream markdown source and regenerate the YAML, rather than manually patching the generated file.
If this is an exceptional case requiring manual intervention, please document:
- Why the upstream source cannot be fixed
- How future upstream syncs will preserve these changes
- A plan to migrate back to upstream-generated content
|
Closing for now to clarify. |
2 participants
Description
Quick fix to manually add the examples from the upstream markdown to this downstream yaml.
https://github.com/docker/scout-cli/blob/main/docs/scout_watch.md#docker-scout-watch
We switched to upstream yaml from the md because of a formatting issue. Will look into it and try to get back to using the upstream md as the md and yaml have diverged over time.
https://deploy-preview-24169--docsdocker.netlify.app/reference/cli/docker/scout/watch/
Related issues or tickets
#23921
https://docker.slack.com/archives/C04C69EM70C/p1771418602873829?thread_ts=1754573643.278429&cid=C04C69EM70C
Reviews