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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#8,395 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
83/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
java, markdown
Lĩnh vực
documentation

Hướng nghiên cứu

Đọc AGENTS.md ở thư mục gốc cùng với .github/PULL_REQUEST_TEMPLATE.md và bổ sung hướng dẫn ngắn gọn cùng các ví dụ được yêu cầu trong issue. Đối chiếu cách diễn đạt với các nguyên tắc làm việc và hướng dẫn build hiện có, sau đó kiểm tra liên kết và thuật ngữ; hoàn tất khi đã đề cập đến tiêu đề, phạm vi, tham chiếu issue, phần phụ thuộc, báo cáo xác thực trung thực và bước rà soát cuối cùng mà không tạo mẫu cạnh tranh hoặc yêu cầu mới.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.

Ngôn ngữ chính
Java
Star
8.9k
Fork
3.1k
Merge trung bình
2 ngày 1 giờ
Pull request đã merge (30 ngày)
362

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

  • Không có Dockerfile hay tệp Docker Compose
  • Có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của apache/shenyu

Tất cả issue của apache/shenyu

Issue tương tự

Thêm issue về Java

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.