We welcome and appreciate contributions from the community. There are many ways to become involved with PowerShell, including filing issues, joining in design conversations,
- Check if the issue you are going to file already exists in our [GitHub issues][open-issue].
- If you can't find your issue already, [open a new issue](https://github.com/PowerShell/PowerShell/issues/new), making sure to follow the directions as best you can.
Please see [Building PowerShell](../README.md#building-powershell)
#### Testing PowerShell
Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running-tests-outside-of-ci] on how to test you build locally.
### Finding or creating an issue
1. Follow the instructions in [Contributing to Issues][contribute-issues] to find or open an issue.
2. Mention in the issue that you are working on the issue and ask `@powershell/powershell` for an assignment.
### Forks and Pull Requests
GitHub fosters collaboration through the notion of [pull requests][using-prs].
On GitHub, anyone can [fork][fork-a-repo] an existing repository into their own branch where they can make private changes to the original repository.
To contribute these changes back into the original repository, a user simply creates a pull request in order to "request" that the changes be taken "upstream".
Additional references:
* GitHub's guide on [forking project](https://guides.github.com/activities/forking/)
* GitHub's guide on [Contributing to Open Source](https://guides.github.com/activities/contributing-to-open-source/#pull-request)
* GitHub's guide on [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/)
### Lifecycle of a pull request
#### Pull request submission
**Always create a pull request to the `master` branch of this repository**.
For more information, learn about our [branch structure][branch-structure].
* If your contribution in a way that changes the user or developer experience, you are expected to document those changes. See [Contributing to documentation related to the PowerShell the product](#contributing-to-documentation-related-to-the-powershell-the-product)
* Add a meaningful title of the PR describing what change you want to check in. Don't simply put: "Fixes issue #5". A better example is: "Added Ensure parameter to New-Item CmdLet. Fixes #5".
* When you create a pull request, fill out the pull request template including a summary of what's included in your changes.
If the changes are related to an existing GitHub issue, please reference the issue in pull request title or description (e.g. ```Closes #11```). See [this][closing-via-message] for more details.
* Include an update to the [change log](../CHANGELOG.MD) file in your pull request to reflect changes for future versions changelog. Put them in `Unreleased` section (create one if doesn't exist). This would simplify the release process for [maintainers][maintainers]. Example:
```
## Versions
### Unreleased
- Added support for `-FriendlyName` in `Update-Item`.
```
Please use past tense when describing your changes:
* Instead of "Adding support for Windows Server 2012 R2", write "Added support for Windows Server 2012 R2".
* Instead of "Fix for server connection issue", write "Fixed server connection issue".
Also, if change is related to specific resource, please prefix the description with the resource name:
* Instead of "New parameter 'ConnectionCredential' in New-SqlConnection", write "New-SqlConnection: added parameter 'ConnectionCredential'"
#### Pull request - Automatic checks
* If this is your first contribution to PowerShell, you may be asked to sign a [Contribution Licensing Agreement][CLA] (CLA) before your changes will be accepted.
* Make sure you follow the [Common Engineering Practices](#common-engineering-practices) and [testing guidelines](../docs/testing-guidelines/testing-guidelines.md)
* After submitting your pull request, our [CI system (Travis-CI & Appveyor)][ci-system] will run a suite of tests and automatically update the status of the pull request.
#### Pull request - Code review
* After a successful test pass, the area [maintainers][maintainers] will do a code review, commenting on any changes that might need to be made. If you are not designated as an area's [maintainer][maintainers], feel free to review others' Pull Requests as well. Additional feedback is always welcome (leave your comments even if everything looks good - simple "Looks good to me" or "LGTM" will suffice so that we know someone has already taken a look at it)!
* Once the code review is done, all merge conflicts are resolved, and the CI system build status is passing, a [maintainer][maintainers] will merge your changes.
for example, PowerShell parameter, API or protocols changes. Before making changes to the code, first review the [breaking changes contract](../docs/dev-process/breaking-change-contract.md)
To add new features such as CmdLets or making design changes, please follow the [PowerShell Request for Comments (RFC)](https://github.com/PowerShell/PowerShell-RFC) process.
and [testing](../docs/testing-guidelines/testing-guidelines.md)) discussed above, we encourage contributors to follow these common engineering practices:
- Don't commit code that you didn't write. If you find code that you think is a good fit to add to PowerShell, file an issue and start a discussion before proceeding
The following file header is used for all PowerShell code. Please use it for new files. For more information, see [coding guidelines](../docs/coding-guidelines/coding-guidelines.md).
To speed up the acceptance of any contribution to any PowerShell repositories, you could [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/) ahead of time.
If you've already contributed to PowerShell repositories in the past, congratulations! You've already completed this step. This a one-time requirement for the PowerShell project.
Signing the CLA process is simple and can be done in less than a minute. You don't have to do this up-front. You can simply clone, fork, and submit your pull request as usual.