mirror of
https://github.com/aphrody-labs/PowerShell.git
synced 2026-10-17 04:36:39 +00:00
Drafted update to contribution guidelines
This commit is contained in:
Travis Plunk committed
1 parent
b1a0dda6de
commit
4c74e05972
9 files changed
+203
-57
No files matched your search
+105
-44
@@ -2,62 +2,107 @@ Contribute to PowerShell
|
||||
=================================
|
||||
|
||||
We welcome and appreciate contributions from the community. There are many ways to become involved with PowerShell, including filing issues, joining in design conversations,
|
||||
writing and improving documentation, contributing to code. Please read the rest of this document to ensure a smooth contribution process.
|
||||
writing and improving documentation, contributing to the code. Please read the rest of this document to ensure a smooth contribution process.
|
||||
|
||||
New to Git?
|
||||
----
|
||||
- Make sure you have a [GitHub account](https://github.com/signup/free)
|
||||
- [Git Basics](../docs/git/basics.md): install and getting started.
|
||||
- Learning Git:
|
||||
* GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources]
|
||||
* [Git Basics](../docs/git/basics.md): install and getting started.
|
||||
* PowerShell DSC Resources: [Getting Started With GitHub](https://github.com/PowerShell/DscResources/blob/master/GettingStartedWithGitHub.md)
|
||||
- [GitHub Flow Guide](https://guides.github.com/introduction/flow/): step-by-step instructions of GitHub flow.
|
||||
|
||||
|
||||
Quick Start Check-list
|
||||
----
|
||||
- Read [the Community Governance](../docs/community/governance.md)
|
||||
- Make sure you have signed a [PowerShell Contribution License Agreement (CLA)](#contributor-license-agreement) before submitting a pull request
|
||||
- Review the [Contribution License Agreement][CLA] requriement.
|
||||
- Get familiar with the [PowerShell repository](../docs/git/powershell-repository-101.md)
|
||||
|
||||
Contributing to Issues
|
||||
----
|
||||
|
||||
- Review the [GitHub issue management process](../docs/dev-process/issue-management-process.md). It covers the triage process and the definition of labels and assignees as well as a description of how we will verify and close issues
|
||||
- Check if the issue you are going to file already exists in our [GitHub issues](https://github.com/PowerShell/PowerShell/issues)
|
||||
- Review the [Issue Label Descriptions](../docs/dev-process/issue-label-descriptions.md)
|
||||
- Check if the issue you are going to file already exists in our [GitHub issues][open-issues]
|
||||
- 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 in the issue template as best you can.
|
||||
- If the issue is marked as [`Help Wanted`][help-wanted-issue], the issue team is looking for help with the issue.
|
||||
|
||||
Contributing to Documentation
|
||||
----
|
||||
- First, check the list of [documentation issues](https://github.com/PowerShell/PowerShell-Docs/issues) to make sure your issue doesn't already exist or that someone is already working on it.
|
||||
- If you cannot find an existing issue for your desired work, [open a new issue](https://github.com/PowerShell/PowerShell/issues/new) explaining that you'd like to contribute to fix the problem.
|
||||
- Follow the guidelines at [Contributing to PowerShell Documentation](https://github.com/PowerShell/PowerShell-Docs/blob/staging/CONTRIBUTING.md).
|
||||
- If you contribute to the PowerShell project in a way that changes the user or developer experience, you are expected to document those changes.
|
||||
- When you are writting markdown docs, use [semantic linefeeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/).
|
||||
In most cases, it means "once sentance per line".
|
||||
### Contributing to documentation related to the PowerShell the product
|
||||
|
||||
Please see the [Contributor Guide in `PowerShell/PowerShell-Docs`](https://github.com/PowerShell/PowerShell-Docs/blob/staging/CONTRIBUTING.md).
|
||||
|
||||
### Contributing to documentation related to Contributing or maintaining the PowerShell Project
|
||||
|
||||
These issues should be treated like any other issue in this repo. See [Contribuing to Code](#contributing-to-code).
|
||||
|
||||
Contributing to Code
|
||||
----
|
||||
|
||||
- Learn how to setup your development environment and build PowerShell for [Linux][build-linux], [Windows Core][build-wc], [Windows Full][build-wf] or
|
||||
[OS X][build-osx].
|
||||
- Build the [PowerShell repository](https://github.com/PowerShell/PowerShell)
|
||||
- Ensure you can [locally execute tests][testing-guidelines] with your build.
|
||||
- [Pick something to work on](https://github.com/PowerShell/PowerShell/issues)
|
||||
- If you cannot find an existing issue for your desired work, open a new issue for your work
|
||||
- Get agreement from the PowerShell team and the community regarding your proposed change via the [issue triage process][issue-triage].
|
||||
- If you're changes require a new cmdlet or other design changes, follow the [design change guidelines](#making-design-changes)
|
||||
- Ensure that you've reviewd our [breaking changes guidelines](#making-breaking-changes)
|
||||
- If you would like to be assigned to the issue, please ask `@powershell/powershell` for an assignment
|
||||
- Create a [personal fork of the repository](https://help.github.com/articles/fork-a-repo/) to start your work
|
||||
- Follow the [coding guidelines](../docs/coding-guidelines/coding-guidelines.md) and [testing guidelines](../docs/testing-guidelines/testing-guidelines.md)
|
||||
- Read the [Pull Request (PR) Guidelines](../docs/dev-process/pull-request-rules.md) and create a [PR](https://guides.github.com/activities/hello-world/) against the upstream repository
|
||||
- Perform a [code review](../docs/dev-process/code-review-guidelines.md) with the [PowerShell Committee][governance] on the pull request.
|
||||
### Building and testing
|
||||
#### Building PowerShell
|
||||
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.
|
||||
|
||||
[build-wc]: ../docs/building/windows-core.md
|
||||
[build-wf]: ../docs/building/windows-full.md
|
||||
[build-osx]: ../docs/building/osx.md
|
||||
[build-linux]: ../docs/building/linux.md
|
||||
[testing-guidelines]: ../docs/testing-guidelines/testing-guidelines.md
|
||||
[issue-triage]: ../docs/dev-process/issue-management-process.md
|
||||
[governance]: ../docs/community/governance.md
|
||||
### 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].
|
||||
|
||||
|
||||
|
||||
* 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.
|
||||
|
||||
Making Breaking Changes
|
||||
----
|
||||
@@ -68,14 +113,14 @@ and follow the guidelines to keep PowerShell backward compatible.
|
||||
|
||||
Making Design Changes
|
||||
----
|
||||
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.
|
||||
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.
|
||||
|
||||
Common Engineering Practices
|
||||
----
|
||||
Other than the guidelines for ([coding](../docs/coding-guidelines/coding-guidelines.md), the [RFC process](https://github.com/PowerShell/PowerShell-RFC) for design, [documentation](#contributing-to-documentation)
|
||||
Other than the guidelines for ([coding](../docs/coding-guidelines/coding-guidelines.md),
|
||||
the [RFC process](https://github.com/PowerShell/PowerShell-RFC) for design, [documentation](#contributing-to-documentation)
|
||||
and [testing](../docs/testing-guidelines/testing-guidelines.md)) discussed above, we encourage contributors to follow these common engineering practices:
|
||||
- Do not commit code changes to the `master` branch!
|
||||
Read GitHub's guides on [forking project](https://guides.github.com/activities/forking/) and [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/)
|
||||
|
||||
- Format commit messages based on [Tim Pope's guidelines]("http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html"):
|
||||
|
||||
```
|
||||
@@ -85,8 +130,7 @@ Provide more detail after the first line. Leave one blank line below the
|
||||
summary and wrap all lines at 72 characters or less.
|
||||
|
||||
If the change fixes an issue, leave another blank line after the final
|
||||
paragraph and indicate which issue is fixed in the specific format
|
||||
below.
|
||||
paragraph and indicate which issue the change fixes in the specific format below.
|
||||
|
||||
Fix #42
|
||||
```
|
||||
@@ -113,9 +157,26 @@ You can find more information about the PowerShell source license and copyright
|
||||
|
||||
Contributor License Agreement (CLA)
|
||||
----
|
||||
You must sign a PowerShell Contribution License Agreement (CLA) before your pull request will be merged.
|
||||
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.
|
||||
|
||||
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.
|
||||
When your pull request is created, it is classified by a CLA bot.
|
||||
If the change is trivial, it's classified as `cla-required`.
|
||||
Once you sign a CLA, all your existing and future pull requests will be labeled as cla-signed.
|
||||
Once you sign a CLA, all your existing and future pull requests will be labeled as `cla-signed`.
|
||||
|
||||
[testing-guidelines]: ../docs/testing-guidelines/testing-guidelines.md
|
||||
[running-tests-outside-of-ci]: ../docs/testing-guidelines/testing-guidelines.md#running-tests-outside-of-ci
|
||||
[issue-triage]: ../docs/dev-process/issue-management-process.md
|
||||
[governance]: ../docs/community/governance.md
|
||||
[using-prs]: https://help.github.com/articles/using-pull-requests/
|
||||
[fork-a-repo]: https://help.github.com/articles/fork-a-repo/
|
||||
[branch-structure]: tbd
|
||||
[closing-via-message]: https://help.github.com/articles/closing-issues-via-commit-messages/
|
||||
[CLA]: #contributor-license-agreement-cla
|
||||
[ci-system]: ../docs/testing-guidelines/testing-guidelines.md#ci-system
|
||||
[good-git-resources]: https://help.github.com/articles/good-resources-for-learning-git-and-github/
|
||||
[contribute-issues]: #contributing-to-issues
|
||||
[open-issue]: https://github.com/PowerShell/PowerShell/issues
|
||||
[maintainers]: ../docs/maintainers/maintainers.md
|
||||
[help-wanted-issue]: https://github.com/PowerShell/PowerShell/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22
|
||||
Reference in new issue
Block a user