Просмотр исходного кода

Closes #23713: Clarify PR and commit guidance

Explain the expected PR summary and commit message format so
contributors and AI tools follow consistent guidance.
Martin Hauser 1 день назад
Родитель
Сommit
d4e3bc172e

+ 8 - 1
.github/PULL_REQUEST_TEMPLATE.md

@@ -14,5 +14,12 @@
 ### Closes: #1234
 
 <!--
-    Please include a summary of the proposed changes below.
+    Briefly explain what this PR changes and the resulting behavior. One or
+    two short paragraphs are usually enough. Include only the context needed
+    to understand the change. Leave the full problem statement in the linked
+    issue.
+
+    Avoid repeating the issue, narrating the diff, or listing every test.
+    Include design decisions, compatibility notes, and meaningful validation
+    results where they help reviewers.
 -->

+ 25 - 1
AGENTS.md

@@ -260,7 +260,8 @@ All contributions must comply with the project's [AI policy](AI_POLICY.md). In s
 
 - AI tools may be used to explore the codebase and to generate code.
 - The contributor must fully understand, and be able to explain, every change submitted.
-- Issues, pull request descriptions, and comments must be written in the contributor's own voice. Anything you draft for these is a starting point for the contributor to review and rewrite: keep it brief and plain, and say so when handing it over.
+- Issues and comments must be written in the contributor's own voice. Anything you draft for these is a starting point for the contributor to review and rewrite: keep it brief and plain, and say so when handing it over.
+- Pull request descriptions may be AI-generated, as long as the contributor reviews them and they follow the [PR description guidance](#pr-descriptions).
 - Never open a GitHub issue on the contributor's behalf (e.g. via `gh issue create` or the API). The contributor must submit it themselves using one of the [issue forms](https://github.com/netbox-community/netbox/issues/new/choose); issues opened any other way are closed automatically.
 
 ## Branch & PR Conventions
@@ -270,6 +271,29 @@ All contributions must comply with the project's [AI policy](AI_POLICY.md). In s
 - Every PR must reference an approved GitHub issue.
 - PRs must include tests for new functionality.
 
+### PR Descriptions
+
+Follow [the PR template](.github/PULL_REQUEST_TEMPLATE.md). Summarize what changes and the resulting behavior, usually in one or two short paragraphs. Include only the context needed to understand the change, and leave the full problem statement in the linked issue. Avoid repeating the issue, narrating the diff, or listing every test. Include design decisions, compatibility notes, and meaningful validation results where they help reviewers.
+
+### Commit Messages and PR Titles
+
+For issue-linked changes, use the [commit message conventions](docs/development/getting-started.md#commit-messages-and-pr-titles). They follow the traditional [Git commit-message guidelines](https://cbea.ms/git-commit/) with NetBox's issue-prefixed subject format:
+
+- Use `Fixes #<issue-id>: <summary>` for bug fixes and `Closes #<issue-id>: <summary>` for all other issue types, such as features, housekeeping, and documentation. Use the same wording for the PR title and final commit subject.
+- Write the summary in the imperative, starting with a capital letter and without a trailing period. It should work as a release note entry. Aim for about 50 characters for the whole subject, including the issue prefix, while keeping the meaning clear.
+- When a body is needed, separate it from the subject with a blank line. Briefly explain what changes and why, rather than walking through the implementation. Wrap prose at 72 characters.
+- Omit a duplicate `Fixes` or `Closes` reference from the commit footer. Keep the required `Closes: #<issue-id>` line in the PR description.
+- When applicable, add a `Co-authored-by: Name <email>` trailer for each co-author, using their preferred attribution details. Separate the trailer block from the body with a blank line.
+
+For example:
+
+```text
+Fixes #1234: Keep cleared fields empty on refresh
+
+Refreshing an edit form restored the saved value of any field the user
+had cleared, discarding that edit. Cleared fields now stay empty.
+```
+
 ## PR Submission Requirements
 
 **Do not open a PR unless all the following conditions are met:**

+ 5 - 3
AI_POLICY.md

@@ -4,9 +4,10 @@ This project **welcomes the thoughtful use of AI tools** when contributing, yet
 
 ## Never let an LLM speak for you
 
-When maintainers read a comment, an issue, or a pull request from you, they want to know they are hearing your words. Grammar and spelling do not matter. What matters is real connection.
+When maintainers read a comment or an issue from you, they want to know they are hearing your words. Grammar and spelling do not matter. What matters is real connection.
 
-- All comments, issues, and pull request descriptions should be written in your own voice
+- All comments and issues should be written in your own voice
+- Pull request descriptions may be AI-generated, as long as you review them and they follow our [description guidelines](docs/development/getting-started.md#pull-request-descriptions)
 - We value clear, human communication over perfect grammar or spelling
 - Avoid copy-pasting AI-generated summaries that don't reflect your own understanding
 
@@ -27,7 +28,8 @@ Our aim is ensuring quality and maintaining the joy of collaborating and communi
 ## Summary
 
 - AI may be used to generate code or explore ideas
-- Comments, issues, and pull request descriptions must be written in your own voice
+- Comments and issues must be written in your own voice
+- AI-generated pull request descriptions must be reviewed by the contributor
 - Contributions must be fully understood and explainable by the contributor
 - Contribution guidelines must still be followed
 

+ 1 - 1
CONTRIBUTING.md

@@ -38,7 +38,7 @@ NetBox users are welcome to participate in either role, on stage or in the crowd
 > We do not currently accept issues submitted via GitHub's API: All issues must be submitted using one of the [provided templates](https://github.com/netbox-community/netbox/issues/new/choose). In addition to ensuring high-quality submissions, these templates automatically assign issue types and labels for categorization to help expedite triage. This does not happen when issues are submitted via the API.
 
 > [!IMPORTANT]
-> Every issue submitted to this repository is afforded consideration by a human reviewer. Please review our [AI policy](AI_POLICY.md) before contributing: While AI tools may be used to help write code, all issues, pull request descriptions, and comments must be written in your own words. Issues which appear to be completely authored by an AI may be rejected without further discussion.
+> Every issue submitted to this repository is afforded consideration by a human reviewer. Please review our [AI policy](AI_POLICY.md) before contributing: While AI tools may be used to help write code, all issues and comments must be written in your own words. Issues which appear to be completely authored by an AI may be rejected without further discussion.
 
 ## :bug: Reporting Bugs
 

+ 43 - 2
docs/development/getting-started.md

@@ -211,16 +211,57 @@ Only the value `1` enables this mode. Unlike `UPDATE_QUERY_COUNTS` mode, it work
 !!! note "Vouched contributors"
     Pull requests are accepted only from contributors who have been vouched for by a maintainer. If you aren't yet listed in [`.github/VOUCHED.td`](https://github.com/netbox-community/netbox/blob/main/.github/VOUCHED.td) (for example, if you're contributing for the first time), introduce yourself by [starting a discussion](https://github.com/netbox-community/netbox/discussions/new?category=vouch-request) in the **Vouch Request** category before submitting your first pull request. Pull requests from contributors who have not been vouched for are closed automatically. See the [contributing guide](https://github.com/netbox-community/netbox/blob/main/CONTRIBUTING.md) for details.
 
-Once you're happy with your work and have verified that all tests pass, commit your changes and push it upstream to your fork. Always provide descriptive (but not excessively verbose) commit messages. Be sure to prefix your commit message with the word "Fixes" or "Closes" and the relevant issue number (with a hash mark). This tells GitHub to automatically close the referenced issue once the commit has been merged.
+Once you're happy with your work and have verified that all tests pass, commit your changes using the [format below](#commit-messages-and-pr-titles) and push them upstream to your fork.
 
 ```no-highlight
 git commit -m "Closes #1234: Add IPv5 support"
 git push origin
 ```
 
-Once your fork has the new commit, submit a [pull request](https://github.com/netbox-community/netbox/compare) to the NetBox repo to propose the changes. Be sure to provide a detailed accounting of the changes being made and the reasons for doing so.
+Once your fork has the new commit, submit a [pull request](https://github.com/netbox-community/netbox/compare) to the NetBox repo to propose the changes. Follow the title and description guidance below.
 
 Once submitted, a maintainer will review your pull request and either merge it or request changes. If changes are needed, you can make them via new commits to your fork: The pull request will update automatically.
 
 !!! warning
     Remember, pull requests are permitted only for **accepted** issues. If an issue you want to work on hasn't been approved by a maintainer yet, it's best to avoid risking your time and effort on a change that might not be accepted. (The one exception to this is trivial changes to the documentation or other non-critical resources.)
+
+### Commit Messages and PR Titles
+
+For issue-linked changes, use one of these subject formats:
+
+* `Fixes #<issue-id>: <summary>` for bug fixes.
+* `Closes #<issue-id>: <summary>` for all other issue types, such as features, housekeeping, and documentation.
+
+GitHub closes the referenced issue automatically once the commit is merged into the default branch.
+
+Use the same wording for the PR title and final commit subject. Write the summary in the imperative (e.g. "Keep cleared fields empty on refresh"), starting with a capital letter and without a trailing period. It should describe the change clearly enough to serve as a release note entry. Aim for about 50 characters for the whole subject, including the issue prefix, while keeping the meaning clear.
+
+When a body is needed, separate it from the subject with a blank line. Briefly explain what changes and why, rather than walking through the implementation, and wrap prose at 72 characters. For example:
+
+```no-highlight
+Fixes #1234: Keep cleared fields empty on refresh
+
+Refreshing an edit form restored the saved value of any field the user
+had cleared, discarding that edit. Cleared fields now stay empty.
+```
+
+The issue reference in the subject is sufficient, so omit a duplicate `Fixes` or `Closes` reference from the commit footer. When applicable, add a `Co-authored-by: Name <email>` trailer for each co-author, using their preferred attribution details. Separate the trailer block from the body with a blank line.
+
+These conventions follow the traditional [Git commit-message guidelines](https://cbea.ms/git-commit/) with NetBox's issue-prefixed subject format.
+
+### Pull Request Descriptions
+
+Use the [PR template](https://github.com/netbox-community/netbox/blob/main/.github/PULL_REQUEST_TEMPLATE.md), including its `Closes: #<issue-id>` line even when the issue is referenced in the title.
+
+Briefly explain what the PR changes and the resulting behavior, usually in one or two short paragraphs. Include only the context needed to understand the change, and leave the full problem statement in the linked issue. Avoid repeating the issue, narrating the diff, or listing every test. Include design decisions, compatibility notes, and meaningful validation results where they help reviewers.
+
+For example:
+
+```markdown
+### Closes: #1234
+
+Keeps cleared fields empty when an edit form refreshes, so saved values
+are no longer restored.
+```
+
+Read through the description before submitting and check that it accurately describes your changes.

+ 4 - 4
docs/development/git-cheat-sheet.md

@@ -208,18 +208,18 @@ index 000000000..e69de29bb
 The `git commit` command records your changes to the current branch. Specify a commit message with the `-m` argument. (If omitted, a file editor will be opened to provide a message.
 
 ``` title="Command"
-git commit -m "Fixes #123: Fixed the thing that was broken"
+git commit -m "Fixes #123: Validate device names"
 ```
 
 ``` title="Example"
-$ git commit -m "Fixes #123: Fixed the thing that was broken"
-[123-fix-foo 9a12b5b5f] Fixes #123: Fixed the thing that was broken
+$ git commit -m "Fixes #123: Validate device names"
+[123-fix-foo 9a12b5b5f] Fixes #123: Validate device names
  2 files changed, 5 insertions(+)
  create mode 100644 foo.py
 ```
 
 !!! tip "Automatically Closing Issues"
-    GitHub will [automatically close](https://github.blog/2013-01-22-closing-issues-via-commit-messages/) any issues referenced in a commit message by `Fixes:` or `Closes:` when the commit is merged into the repository's default branch. Contributors are strongly encouraged to follow this convention when forming commit messages. (Use "Closes" for feature requests and "Fixes" for bugs.)
+    GitHub will [automatically close](https://github.blog/2013-01-22-closing-issues-via-commit-messages/) any issues referenced in a commit message by `Fixes` or `Closes` when the commit is merged into the repository's default branch. See the [commit message conventions](getting-started.md#commit-messages-and-pr-titles) for NetBox's subject format and examples.
 
 ### Push a Commit Upstream