nevzheng opened a new issue, #12387: URL: https://github.com/apache/gravitino/issues/12387
### What would you like to be improved? Without explicit guidance, coding agents can default to bottom-up GitHub writing: PRs replay the diff, issues lead with a solution, and discussions bury the question or decision beneath chronology and detail. That content can be accurate, but readers must reconstruct the point. Titles and bodies should instead tell a concise, top-down story: lead with the bottom line and why it matters, then add the context, boundaries, and evidence needed to act or review. Use the relevant 5Ws and 1H as a coverage check, not a fixed questionnaire. Leave procedural inventories to the code or put them last in an optional deep dive. Preserve required template content. This improvement covers PR titles and descriptions, GitHub Issues, and GitHub Discussions. Design documents are explicitly out of scope. ### How should we improve? Update the repository agent guidance with shared writing principles and concise defaults for each artifact: - **Shared:** Lead with the audience's bottom line and why it matters. Use a proportional, evidence-backed narrative; preserve required templates and put supporting or procedural detail later. - **Pull requests:** Name the outcome and scope in the title. Explain the prior state or trigger, what changes and why, user-facing and unchanged boundaries, relevant relationships, and exact verification evidence. - **Issues:** Name the problem or desired outcome in the title. Lead with the problem and evidence, then the desired outcome; keep implementation ideas secondary unless already decided. - **GitHub Discussions:** Name the question or requested decision in the title. Lead with the input needed and why it matters, then give the relevant context, options, and tradeoffs; distinguish proposals from consensus. - **Freshness:** After material changes, warn when a title or body may be stale and show a refreshed preview before updating it. This issue proposes only an update to repository agent guidance. It does not propose changes to design-document guidance, GitHub templates, or validation workflows. Related: #9789 <details> <summary>Writing references</summary> - [Google Engineering Practices](https://google.github.io/eng-practices/review/developer/cl-descriptions.html) - [GitHub: Helping others review your changes](https://docs.github.com/en/pull-requests/concepts/helping-others-review-your-changes) - [Microsoft Engineering Fundamentals](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/process-guidance/author-guidance/) - [GitHub: Quickstart for Issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/learning-about-issues/quickstart) - [GitHub: Best practices for community conversations](https://docs.github.com/en/discussions/guides/best-practices-for-community-conversations-on-github) - [Axios HQ: Smart Brevity](https://www.axioshq.com/insights/smart-brief-writing-will-transform-your-internal-comms) - [Office for National Statistics: Structuring content](https://service-manual.ons.gov.uk/content/writing-for-users/structuring-content) - [CDC Clear Communication Index](https://www.cdc.gov/ccindex/tool/page-1.html) </details> -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
