[Task][Docs] Add PR title and description guidance to AGENTS.md

Open Beginner friendly
  • Is something wrong?
#8,395 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
83/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
java, markdown
Domain
documentation

Research direction

Read the root AGENTS.md alongside .github/PULL_REQUEST_TEMPLATE.md and add the concise guidance and examples requested in the issue. Check the wording against the existing working principles and build guidance, then verify links and terminology; done when titles, scope, issue references, dependencies, truthful validation reporting, and final review are covered without creating a competing template or new requirements.

Written by the indexing model from the issue text.

Description

Description

Add a concise pull-request writing section to the root AGENTS.md so coding agents produce concrete, reviewable PR titles and descriptions that agree with the repository's existing template.

Reviewed at master 88883dc20fb1f57db6343ba811c1d1f3ee70a6bf.

Current guidance and gap

  • AGENTS.md already requires pre-submission checks. Its working principles require checking current issue/PR state, explaining material assumptions/tradeoffs and reporting verification.
  • It does not explain how to write a PR title/body, link issues, describe incomplete dependencies, or keep the description aligned with the final diff.
  • .github/PULL_REQUEST_TEMPLATE.md already provides an issue-reference example and contribution/test/build checkboxes. The new guidance should explain how to supply useful information within that template, rather than introduce a competing template.

Task list

  1. Title: use a concise, concrete description of the affected area and resulting change, following established repository conventions. Avoid vague titles such as "optimize code"; do not introduce a new mandatory prefix or commit convention through this documentation task.
  2. Problem and behavior: lead the body with the problem, its trigger and the resulting behavior. For a bug, include a short before/after or reproduction example when useful. Explain the material implementation choice, compatibility implications and limitations at a level that helps a reviewer assess the final change.
  3. Scope and issue references: keep each PR focused on one coherent problem or capability. Use Fixes #... only when the PR actually resolves that issue; use a non-closing reference such as Related to #... for partial or supporting work. Explain any required unmerged PR dependency. Do not impose an arbitrary one-PR/one-issue or one-file rule on a complete cross-module change.
  4. Verification: record the relevant commands, executed tests and results, plus important checks not run and why. Distinguish actual behavior tests from compilation or -DskipTests builds, and distinguish current-diff evidence from older results. Retain existing Checkstyle, RAT/license and contribution requirements. Never check a template box for a command that was not successfully run.
  5. Final review: reread the final diff before submission or updating a PR. Rewrite the title/body when the scope changes; remove stale claims, conversation history and abandoned approaches unless they explain a current tradeoff. Keep small PR descriptions short and add structure only when useful or required by the template.
  6. Include a compact illustrative bugfix example and a lighter documentation-only example, clearly marked as examples rather than claims that their tests were run.

Acceptance criteria

  • Root AGENTS.md contains a short, actionable PR-writing section covering titles, problem/resulting behavior, scope, issue links, dependencies and verification.
  • The section explicitly points to the checked-in PR template and preserves its contribution requirements; it does not create a second mandatory template.
  • A reviewer can tell what changed, why it changed, which issue is resolved or merely related, and what validation actually ran.
  • Examples demonstrate proportional detail and truthful validation reporting, including skipped/unrun checks; no blanket exemption from required checks is introduced.
  • Existing working principles, build guidance and architecture content remain consistent. No new approval workflow, runtime behavior, CI policy or issue-to-PR cardinality rule is added.

Validation and related work

Review the added text and examples against AGENTS.md and .github/PULL_REQUEST_TEMPLATE.md; check links and terminology. This documentation task does not need an artificial Java regression test.

Follow-up to #8211, which added the existing working principles and corrected build facts and is now closed. This issue specifically covers PR communication guidance.

Dominant language
Java
Stars
8.9k
Forks
3.1k
Avg merge
2d 1h
Merged PRs (30d)
362

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

  • No Dockerfile or Docker Compose file
  • Has a pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from apache/shenyu

All issues in apache/shenyu

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.