[docs] docs: unbloat frontmatter reference#36300
Conversation
…nt (#36295) * Fix 4 golint issues: copyloopvar, errorlint, modernize, testifylint Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> * Fix 4 golint issues: copyloopvar, errorlint, modernize, testifylint Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Reduce bloat in the frontmatter reference (552 → 464 lines, 16% line / 10% word / 34% bullet reduction) while preserving all field semantics: - Remove filler restatement paragraphs in Labels, Metadata, and Private - Condense the over-structured Runtimes section: merge three near-identical YAML examples into one and drop the redundant Format / Fields / Use Cases / Default Behavior bullet subsections - Convert Constraints and Security-best-practices bullet lists to prose - Unwrap awkwardly hard-wrapped Observability prose - Tighten Redirect, Resources, and timeout-minutes descriptions Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
automation
doc-unbloat
documentation
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #36300 does not have the 'implementation' label and has 0 new lines of code in business logic directories (≤100 threshold). The changed files are shell/python scripts under .github/skills/ and .github/workflows/shared/mcp/, which are outside the configured business logic directories. |
|
🧪 Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR (#36300, '[docs] docs: unbloat frontmatter reference'). Test Quality Sentinel skipped. |
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ PR Code Quality Reviewer completed the code quality review. No action needed: PR #36300 is already merged. It contains only documentation changes (unbloating frontmatter.md) — no code changes, no logic, no correctness/security/performance concerns to flag. All field semantics, defaults, and constraints are preserved in the condensed prose. |
There was a problem hiding this comment.
Pull request overview
This PR streamlines the Frontmatter reference documentation by removing redundant restatement and simplifying structure while keeping all field semantics, defaults, tables, callouts, and key notes intact.
Changes:
- Condensed several sections (e.g., Labels, Metadata, Secrets, Observability, Resources, Redirect, Private) by merging repetitive paragraphs/bullets into tighter prose.
- Simplified the
runtimes:section by collapsing repetitive sub-structure and examples into a single clearer example plus a short set of rules. - Reflowed and tightened explanatory text (notably Observability and
timeout-minutes) without changing the described behavior.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/frontmatter.md | Removes redundancy and over-structuring across multiple frontmatter field sections while preserving documented semantics and reference tables. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 0
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · sonnet46 1.2M
| `endpoint` accepts a string, a `{url, headers}` object, or an array of endpoint objects for fan-out; `headers` accepts a map or comma-separated `key=value` string; `if-missing` supports `error` (default), `warn`, and `ignore`; and `attributes` is an optional map of custom span attributes (values support GitHub Actions expressions). See [OpenTelemetry](/gh-aw/reference/open-telemetry/) for runtime variables, endpoint forms, span attributes, and artifact files. | ||
|
|
||
| ### Resources (`resources:`) | ||
|
|
There was a problem hiding this comment.
[/grill-with-docs] The four-clause semicolon chain may trade readability for brevity — scanability was actually the reason the original had separate lines.
💡 Suggested alternative
Consider a compact definition list or just two sentences:
`endpoint` accepts a string, a `{url, headers}` object, or an array of objects for fan-out.
`headers` accepts a map or comma-separated `key=value` string; `if-missing` supports `error` (default), `warn`, and `ignore`;
`attributes` is an optional map of custom span attributes (values support GitHub Actions expressions).Three sentences keeps scanning fast without the original hard-wrapping.
Summary
Two independent improvements shipped together: a documentation tightening pass on the frontmatter reference page, and a batch of Go lint fixes to keep CI green.
Changes
📝 docs: unbloat frontmatter reference
File:
docs/src/content/docs/reference/frontmatter.mdCondensed and rewrote multiple reference sections —
labels,metadata,timeout-minutes,secrets,observability,resources,runtimes,redirect, andprivate— to be more concise. Scattered bullet lists and multi-paragraph blocks were merged into tighter prose. No documented functionality was removed; this is a readability-only change.🔧 Fix lint-go CI failures (#36295)
Resolved a batch of
lint-goCI failures introduced by updated linter rules:copyloopvarerrorlintmodernizetestifylinttestifyassertion calls corrected to preferred formsType of change
Testing