Repository navigation
Merge pull request #130 from blanketops/feat/contract-docs-generation feat: generate per-package contract docs, aligned with docs/code/ convention - #131
Merged
Conversation
…vention Adds `mage docs`, which generates Markdown documentation from .proto comments via protoc-gen-doc, driven by buf -- one file per proto package directory (docs/code/blanketops/<path>.md), matching exactly the docs/code/ layout gomarkdoc produces in the sibling environments and environments-controller repos. Wired into finalize-release.yml only, right after the existing Go/TS codegen step -- this repo already generates and commits its Go/TS contracts exclusively at release time (no async on-push-to-main job), which is the correct, race-free pattern the sibling repos' docs generation had to be retrofitted into after hitting a real drift bug. Docs generation follows that same already-correct shape from the start. Cleaned up banner-divider comments (`// ====...====`) in 11 .proto files first -- protoc-gen-doc attaches a message/service's leading comment block the same way Go's doc tooling does (no blank line before the declaration), so an attached banner would have rendered as literal ASCII dashes in the generated docs, same failure mode already fixed across the Go repos. Verified with `buf lint` and `buf build` that the comment-only edits didn't break anything, and spot-checked the generated output renders clean. Includes the initial generated docs/ output so docs exist immediately rather than waiting for the next release cut. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
feat: generate per-package contract docs, aligned with docs/code/ convention
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Why
Domain
environmentseventssourcesnetworkscommonAPI impact
v1alpha1— free to changev1beta1— backwards-compatible only, deprecations allowedv1— breaking change (requires version bump + changelog entry + migration note)Checklist
mage verifypasses locallybuf lintcleanbuf breakingreviewed (failures justified above if pre-v1)buf generate) reflects the change — all targets (Go / C# / Java / TS)environments.blanketops.dev/*)Notes for reviewer