wenjin272 commented on code in PR #1073: URL: https://github.com/apache/flink-agents/pull/1073#discussion_r3921668672
########## contribution-guides/ai-assisted-pr.md: ########## @@ -0,0 +1,175 @@ +# Writing an Implementation Description for an AI-assisted PR + +Read this before opening a pull request whose implementation is largely +AI-assisted. An Implementation Description is an as-built account of the +code the PR actually contains: what it does today, not what it was planned +to do. It is not a plan and not a spec, and it is written from the finished +diff. The tooling that produced the change already worked out the runtime +flow, the contracts and the failure paths; a plain summary throws all of +that away and leaves the reviewer to rebuild it from the diff. This guide +is iterative and will be extended as worked examples accumulate. + +## When this applies + +Non-trivial code changes: a change that adds or alters behavior a caller +can observe, or that touches a runtime path, a public API, or a failure +path. + +It does not apply to a change whose diff is already prose, such as +documentation, comments, or site content. The format is built around +runtime flow, behavioral contracts and failure behavior, and a prose diff +has none of them. Describing one produces a second copy of the change that +the reviewer then has to keep consistent with the first. Use the repository +template as it stands. + +When only part of a PR qualifies, describe that part and nothing else. Say +in one line which part of the diff the description covers, so a reviewer +does not read the omission as a gap. + +## The two-stage review it feeds + +Stage one is a human, reviewing the architecture, the behavioral contracts, +the failure behavior and the compatibility impact as the description states +them. That stage is accountable for the judgment: whether these are the +right contracts, whether the failure behavior is acceptable, whether the +compatibility cost is worth paying. + +Stage two is the checking agent, an agent that did not write the change. It +checks two directions: that the code and tests match the description claim +by claim, and that the description omits nothing important, by walking each +hunk of the diff and asking which field accounts for it. That stage is +accountable for the correspondence between the description and the code, +not for the design. + +## Where it goes + +The PR body is the description. There is no separate document, so the +description lives in exactly one place. Fold the seven fields into the +sections of `.github/PULL_REQUEST_TEMPLATE.md`; sections not listed here +are unchanged. + +| Template section | Carries | +|---|---| +| `Purpose of change` | the user-visible outcome first, then the intent behind the change, then runtime flow and key decisions | +| `Implementation Description` | interaction decisions, behavioral contracts, failure behavior | +| `Tests` | the contracts-to-tests table | +| `API` | compatibility impact | + +Three of the seven fields have no existing home, and one new `### Review Comment: The current wording works for me. Keeping it generic avoids reintroducing the old heading name. -- 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]
