120 lines
6.1 KiB
Markdown
120 lines
6.1 KiB
Markdown
# Power Toys Contributor's Guide
|
|
|
|
Below is our guidance for how to report issues, propose new features, and submit contributions via Pull Requests (PRs).
|
|
|
|
## Before you start, file an issue
|
|
|
|
Please follow this simple rule to help us eliminate any unnecessary wasted effort & frustration, and ensure an efficient and effective use of everyone's time - yours, ours, and other community members':
|
|
|
|
> 👉 If you have a question, think you've discovered an issue, would like to propose a new feature, etc., then find/file an issue **BEFORE** starting work to fix/implement it.
|
|
|
|
### Search existing issues first
|
|
|
|
Before filing a new issue, search existing open and closed issues first: It is likely someone else has found the problem you're seeing, and someone may be working on or have already contributed a fix!
|
|
|
|
If no existing item describes your issue/feature, great - please file a new issue:
|
|
|
|
### File a new Issue
|
|
|
|
* Don't know whether you're reporting an issue or requesting a feature? File an issue
|
|
* Have a question that you don't see answered in docs, videos, etc.? File an issue
|
|
* Want to know if we're planning on building 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 / repro-steps / etc.
|
|
|
|
### Complete the template
|
|
|
|
**Please include as much information as possible in your issue**. The more information you provide, the more likely your issue/ask will be understood and implemented. Helpful information includes:
|
|
|
|
* What device you're running (inc. CPU type, memory, disk, etc.)
|
|
* What build of Windows your device is running
|
|
|
|
👉 Tip: Run the following in PowerShell Core
|
|
|
|
```powershell
|
|
C:\> $PSVersionTable.OS
|
|
Microsoft Windows 10.0.18909
|
|
```
|
|
|
|
... or in Windows PowerShell
|
|
|
|
```powershell
|
|
C:\> $PSVersionTable.BuildVersion
|
|
|
|
Major Minor Build Revision
|
|
----- ----- ----- --------
|
|
10 0 18912 1001
|
|
```
|
|
|
|
... or Cmd:
|
|
|
|
```cmd
|
|
C:\> ver
|
|
|
|
Microsoft Windows [Version 10.0.18900.1001]
|
|
```
|
|
|
|
* What tools and apps you're using (e.g. VS 2019, VSCode, etc.)
|
|
* Don't assume we're experts in setting up YOUR environment and don't assume we are experts in YOUR workflow. Teach us to help you!
|
|
* **We LOVE detailed repro steps!** What steps do we need to take to reproduce the issue? Assume we love to read repro steps. As much detail as you can stand is probably _barely_ enough detail for us!
|
|
* Prefer error message text where possible or screenshots of errors if text cannot be captured
|
|
* **If you intend to implement the fix/feature yourself then say so!** If you do not indicate otherwise we will assume that the issue is ours to solve, or may label the issue as `Help-Wanted`.
|
|
|
|
### DO NOT post "+1" comments
|
|
|
|
> ⚠ DO NOT post "+1", "me too", or similar comments - they just add noise to an issue.
|
|
|
|
If you don't have any additional info/context to add but would like to indicate that you're affected by the issue, upvote the original issue by clicking its [+😊] button and hitting 👍 (+1) icon. This way we can actually measure how impactful an issue is.
|
|
|
|
---
|
|
|
|
## Contributing fixes / features
|
|
|
|
For those able & willing to help fix issues and/or implement features ...
|
|
|
|
### To Spec or not to Spec
|
|
|
|
Some issues/features may be quick and simple to describe and understand. For such scenarios, once a team member has agreed with your approach, skip ahead to the section headed "Fork, Branch, and Create your PR", below.
|
|
|
|
Small issues that do not require a spec will be labelled Issue-Bug or Issue-Task.
|
|
|
|
However, some issues/features will require careful thought & formal design before implementation. For these scenarios, we'll request that a spec is written and the associated issue will be labeled Issue-Feature.
|
|
|
|
Specs help collaborators discuss different approaches to solve a problem, describe how the feature will behave, how the feature will impact the user, what happens if something goes wrong, etc. Driving towards agreement in a spec, before any code is written, often results in simpler code, and less wasted effort in the long run.
|
|
|
|
Specs will be managed in a very similar manner as code contributions so please follow the "Fork, Branch and Create your PR" below.
|
|
|
|
### Writing / Contributing-to a Spec
|
|
|
|
To write/contribute to a spec: fork, branch and commit via PRs, as you would with any code changes.
|
|
|
|
Specs are written in markdown, stored under the `doc/specs` folder and named `[issue id] - [spec description].md`.
|
|
|
|
👉 **It is important to follow the spec templates and complete the requested information**. The available spec templates will help ensure that specs contain the minimum information & decisions necessary to permit development to begin. In particular, specs require you to confirm that you've already discussed the issue/idea with the team in an issue and that you provide the issue ID for reference.
|
|
|
|
Team members will be happy to help review specs and guide them to completion.
|
|
|
|
### Help Wanted
|
|
|
|
Once the team have approved an issue/spec, development can proceed. If no developers are immediately available, the spec can be parked ready for a developer to get started. Parked specs' issues will be labeled "Help Wanted". To find a list of development opportunities waiting for developer involvement, visit the Issues and filter on [the Help-Wanted label](https://github.com/microsoft/PowerToys/labels/Help%20Wanted).
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
Follow the [development guidelines](https://github.com/microsoft/PowerToys/blob/master/doc/devdocs/readme.md).
|
|
|
|
|
|
### How can I become a collaborator on the PowerToys team
|
|
|
|
Be a great community member. Just help out a lot and make useful additions, filing bugs/suggestions, help develop fixes and features, code reviews, and always, docs. Lets continue to make the PowerToys repository a great spot to learn and make a great set of utilities.
|
|
|
|
When the time comes, Microsoft will reach out and help make you a formal team member. Just make sure they can reach out to you :)
|
|
|
|
---
|
|
|
|
## Thank you
|
|
|
|
Thank you in advance for your contribution!
|