Mike Griese
f5f61ea984
I think we need to implement a hard rule that PR bodies should be authored by a human and never by a robot. The point of a PR is not only to contribute code and make modifications to the code base, but it is also to convey the learnings from the contributor to the rest of the maintainers. Important part of that process is being able to explain the change in your own words. If a contributor can't explain the change in their own words, then they don't understand what that change does to the codebase. And if the contributor can't understand it, then what hope would the maintainer have? I think we need to implement this as a hard rule when merging PRs. It's not something that we can try to detect or actually have an actual block on PRs for. But we should block PRs with prejudice when we suspect that the body was not authored by a human being. If you want to include the AI generated body in the PR, I think we should allow that with the caveat that the AI text MUST be in a details section. This PR adds a pile of text to all our files that LLMs read to try to enforce this. It removes some of the earlier tooling that would auto- generate PR bodies for fixes. To be clear: I'm not making any commentary on AI usage for code fixes here, nor should we discuss that at this time. The **only** thing I want to discuss here is AI usage in PR bodies.
5.4 KiB
PowerToys contributor's guide
Below is our guidance for reporting issues, proposing new features, and submitting contributions via Pull Requests (PRs). Our philosophy is to understand the problem and scenarios first, which is why we follow this pattern before work starts.
- There is an issue.
- There has been a conversation.
- There is agreement on the problem, the fit for PowerToys, and the solution to the problem (implementation).
Filing an issue
Importance of Filing an Issue First
Please follow this rule to help eliminate wasted effort and frustration, and to ensure an efficient and effective use of everyone's time:
👉 If you have a question, think you've discovered an issue, or would like to propose a new feature, please find/file an issue BEFORE starting work to fix/implement it.
When requesting new features or enhancements, providing additional evidence, data, tweets, blog posts, or research is extremely helpful. This information gives context to the scenario that may otherwise be lost.
- Unsure whether it's an issue or feature request? File an issue.
- Have a question that isn't answered in the docs, videos, etc.? File an issue.
- Want to know if we're planning a particular feature? File an issue.
- Got a great idea for a new utility or feature? File an issue/request/idea.
- Don't understand how to do something? File an issue/Community Guidance Request.
- Found an existing issue that describes yours? Great! Upvote and add additional commentary, info, or repro steps.
A quick search before filing an issue could be helpful. It's likely someone else has found the same problem, and they may even be working on or have already contributed a fix!
Indicating interest in issues
To let the team know which issues are important, upvote by clicking the [+😊] button and the 👍 icon on the original issue post. Avoid comments like "+1" or "me too" as they clutter the discussion and make it harder to prioritize requests.
Contributing fixes or features
Please comment on our Would you like to contribute to PowerToys? thread to let us know you're interested in working on something before you start. This helps avoid multiple people unexpectedly working on the same thing and ensures everyone is clear on what should be done. It's less work for everyone to establish this up front.
Localization issues
For localization issues, please file an issue to notify our internal localization team, as community PRs for localization aren't accepted. Localization is handled exclusively by the internal Microsoft team.
To spec or not to spec
A key point is for everyone to understand the approach that will be taken. We want to be sure that any work done will be accepted. Larger-scope items will require a spec to outline the approach and allow for discussion. Specs help collaborators consider different solutions, describe feature behavior, and plan for errors. Achieving agreement in a spec before writing code often results in simpler code and less wasted effort.
Once a team member has agreed with your approach, proceed to the "Development" section below. Team members are happy to help review specs and guide them to completion.
Help wanted
Once the team has approved an issue/spec approach, development can proceed. If no developers are immediately available, the spec may be parked and labeled "Help Wanted," ready for a developer to get started. For development opportunities, visit Issues labeled Help Wanted.
Development
Follow the development guidelines.
Pull request descriptions must be written by a human
A PR does more than change code. It also passes what you learned to the maintainers. To do that, you must explain the change in your own words. If you cannot explain a change, you do not understand what it does to the code base. If you do not understand it, a maintainer cannot be expected to understand it either.
-
You must write the PR body in your own words. This includes the summary, the detailed description, and the validation steps. Do not let an AI tool, agent, or bot write them.
-
AI-generated text is allowed only inside a collapsed
<details>section. Label it clearly as AI-generated, for example:<details> <summary>AI-generated summary</summary> ...text written by an AI tool... </details> -
If maintainers think a PR body was not written by a human, they can close the PR without further review.
-
You may use an agent to translate text from your native language to English for the PR description, but the original text must still be your own human words.
Naming features and functionality
Names should be descriptive and straightforward, clearly reflecting functionality and usefulness.
Becoming a collaborator on the PowerToys team
Be an active community member! Make helpful contributions by filing bugs, offering suggestions, developing fixes and features, conducting code reviews, and updating documentation.
When the time comes, Microsoft will reach out to you about becoming a formal team member. Just make sure they have a way to contact you. 😊
Thank you
Thank you in advance for your contribution! We appreciate your help in making PowerToys a better tool for everyone.