maxmustermann/PowerShell
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Improvements to the contribution guide (#12086)

Browse source 
* Fix typo in contribution guide

* Improve contributing links and wording

Various improvements to the contributor's guide, including grammar fixes, making common links for easier updating, and fix for a broken link to VS Code editor documentation.

* Update .github/CONTRIBUTING.md

Co-authored-by: Travis Plunk <travis.plunk@microsoft.com>
This commit is contained in:
Shayde Nofziger 2020-03-11 14:46:19 -04:00 committed by GitHub
parent bb8a7c779d
commit 23b7dce320
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 19 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
.github/CONTRIBUTING.md vendored
View file

@ -19,7 +19,7 @@ Please read the rest of this document to ensure a smooth contribution process.
## Quick Start Checklist
* Review the [Contribution License Agreement][CLA] requirement.
* Review the [Contributor License Agreement][CLA] requirement.
* Get familiar with the [PowerShell repository](../docs/git).
## Contributing to Issues
@ -115,7 +115,7 @@ Please see [Building PowerShell](../README.md#building-the-repository).
#### Testing PowerShell
Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running-tests-outside-of-ci] on how to test you build locally.
Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running-tests-outside-of-ci] on how to test your build locally.
### Finding or creating an issue
@ -167,11 +167,11 @@ Additional references:
An issue title is to briefly describe what is wrong, while a PR title is to briefly describe what is changed.
A better example is: "Add Ensure parameter to New-Item cmdlet", with "Fix #5" in the PR's body.
* When you create a pull request,
including a summary about your changes in the PR description.
include a summary about your changes in the PR description.
The description is used to create change logs,
so try to have the first sentence explain the benefit to end users.
If the changes are related to an existing GitHub issue,
please reference the issue in PR description (e.g. ```Fix #11```).
please reference the issue in the PR description (e.g. ```Fix #11```).
See [this][closing-via-message] for more details.
* Please use the present tense and imperative mood when describing your changes:
@ -277,10 +277,10 @@ Additional references:
- `Request changes` if you believe the PR merge should be blocked if your feedback is not addressed,
- `Approve` if you believe your feedback has been addressed or the code is fine as-is, it is customary (although not required) to leave a simple "Looks good to me" (or "LGTM") as the comment for approval.
- `Comment` if you are making suggestions that the *author* does not have to accept.
Early in the review, it is acceptable to provide feedback on coding formatting based on the published [Coding Guidelines](../docs/dev-process/coding-guidelines.md), however,
after the PR has been approved, it is generally _not_ recommended to focus on formatting issues unless they go against the [Coding Guidelines](../docs/dev-process/coding-guidelines.md).
Early in the review, it is acceptable to provide feedback on coding formatting based on the published [Coding Guidelines][coding-guidelines], however,
after the PR has been approved, it is generally _not_ recommended to focus on formatting issues unless they go against the [Coding Guidelines][coding-guidelines].
Non-critical late feedback (after PR has been approved) can be submitted as a new issue or new pull request from the *reviewer*.
1. *Assignee* who are always *Maintainers* ensure that proper review has occurred and if they believe one approval is not sufficient, the *maintainer* is responsible to add more reviewers.
1. *Assignees* who are always *Maintainers* ensure that proper review has occurred and if they believe one approval is not sufficient, the *maintainer* is responsible to add more reviewers.
An *assignee* may also be a reviewer, but the roles are distinct.
Once the PR has been approved and the CI system is passing, the *assignee* will merge the PR after giving one business day for any critical feedback.
For more information on the PowerShell Maintainers' process, see the [documentation](../docs/maintainers).
@ -302,22 +302,22 @@ In these cases:
## Making Breaking Changes
When you make code changes,
please pay attention to these that can affect the [Public Contract](../docs/dev-process/breaking-change-contract.md).
please pay attention to these that can affect the [Public Contract][breaking-changes-contract].
For example, changing PowerShell parameters, APIs, or protocols break the public contract.
Before making changes to the code,
first review the [breaking changes contract](../docs/dev-process/breaking-change-contract.md)
first review the [breaking changes contract][breaking-changes-contract]
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.
please follow the [PowerShell Request for Comments (RFC)][rfc-process] process.
## Common Engineering Practices
Other than the guidelines for ([coding](../docs/dev-process/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,
Other than the guidelines for [coding][coding-guidelines],
the [RFC process][rfc-process] 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:
* Format commit messages following these guidelines:
@ -359,7 +359,7 @@ is also appropriate, as is using Markdown syntax.
If you find code that you think is a good fit to add to PowerShell,
file an issue and start a discussion before proceeding.
* Create and/or update tests when making code changes.
* Run tests and ensure they are passing before pull request.
* Run tests and ensure they are passing before opening a pull request.
* All pull requests **must** pass CI systems before they can be approved.
* Avoid making big pull requests.
Before you invest a large amount of time,
@ -368,7 +368,7 @@ is also appropriate, as is using Markdown syntax.
## Contributor License Agreement (CLA)
To speed up the acceptance of any contribution to any PowerShell repositories,
you should to [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/) ahead of time.
you should sign the Microsoft [Contributor License Agreement (CLA)](https://cla.microsoft.com/) ahead of time.
If you've already contributed to PowerShell or Microsoft repositories in the past, congratulations!
You've already completed this step.
This a one-time requirement for the PowerShell project.
@ -395,8 +395,10 @@ Once you sign a CLA, all your existing and future pull requests will have the st
[up-for-grabs]: https://github.com/powershell/powershell/issues?q=is%3Aopen+is%3Aissue+label%3AUp-for-Grabs
[semantic linefeeds]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
[PowerShell-Docs]: https://github.com/powershell/powershell-docs/
[use-vscode-editor]: ../docs/learning-powershell/using-vscode.md#editing-with-visual-studio-code
[use-vscode-editor]: https://docs.microsoft.com/en-us/powershell/scripting/components/vscode/using-vscode?view=powershell-7#editing-with-vscode
[repository-maintainer]: ../docs/community/governance.md#repository-maintainers
[area-expert]: ../docs/community/governance.md#area-experts
[ci-system]: ../docs/testing-guidelines/testing-guidelines.md#ci-system
[first-time-issue]: https://github.com/powershell/powershell/issues?q=is%3Aopen+is%3Aissue+label%3AFirst-Time-Issue
[coding-guidelines]: ../docs/dev-process/coding-guidelines.md
[breaking-changes-contract]: ../docs/dev-process/breaking-change-contract.md
[rfc-process]: https://github.com/PowerShell/PowerShell-RFC