From 6e44b52c92440815bfb57fa39f153a767f05930e Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 27 Jul 2016 16:31:07 -0700 Subject: [PATCH] Update contributing guidelines * Links fixed. * Link to maintainers removed; superfluous in this document. * TODO added to changelog. (I don't like this but was hesitant to remove it). * Periods and spelling fixed. --- .github/CONTRIBUTING.md | 262 +++++++++++++++++++++++++++------------- 1 file changed, 180 insertions(+), 82 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f5e3d7c096..63b417213e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,48 +1,61 @@ 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 the code. Please read the rest of this document to ensure a smooth contribution process. +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, +and 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) -- Learning Git: - * GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources] - * [Git Basics](../docs/git/basics.md): install and getting started. -- [GitHub Flow Guide](https://guides.github.com/introduction/flow/): step-by-step instructions of GitHub flow. +----------- -Quick Start Check-list ----- -- Review the [Contribution License Agreement][CLA] requriement. -- Get familiar with the [PowerShell repository](../docs/git/powershell-repository-101.md) +* Make sure you have a [GitHub account](https://github.com/signup/free). +* Learning Git: + * GitHub Help: [Good Resources for Learning Git and GitHub][good-git-resources]. + * [Git Basics](../docs/git/basics.md): + install and getting started. +* [GitHub Flow Guide](https://guides.github.com/introduction/flow/): + step-by-step instructions of GitHub flow. + +Quick Start Checklist +--------------------- + +* Review the [Contribution License Agreement][CLA] requirement. +* Get familiar with the [PowerShell repository](../docs/git). Contributing to 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-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. -- If the issue is marked as [`Help Wanted`][help-wanted-issue], the PowerShell [maintainers][maintainers] are looking for help with the issue. +* 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-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. +* If the issue is marked as [`Help Wanted`][help-wanted-issue], + the PowerShell maintainers are looking for help with the issue. Contributing to Documentation ----- +----------------------------- + ### 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 -- When appropriate in writting markdown docs, use [semantic linefeeds](http://rhodesmill.org/brandon/2012/one-sentence-per-line/). - In most cases, it means "once sentence per line". -- Otherwise, these issues should be treated like any other issue in this repo. See [Contribuing to Code](#contributing-to-code). +* When writing Markdown documentation, use [semantic linefeeds][]. + In most cases, it means "once clause / idea per line". +* Otherwise, these issues should be treated like any other issue in this repo. Contributing to Code ----- +-------------------- ### Building and testing #### Building PowerShell -Please see [Building PowerShell](../README.md#building-powershell) +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. @@ -54,11 +67,13 @@ Please see PowerShell [Testing Guidelines - Running Tests Outside of CI][running ### 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". +On GitHub, anyone can [fork][fork-a-repo] an existing repository +into their own user account, where they can make private changes to their fork. +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 [forking](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/) @@ -66,104 +81,188 @@ Additional references: ### 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]. ![Github-PR-dev.png](Images/Github-PR-dev.png) -* 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) +* 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". +* 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: "Add Ensure parameter to New-Item cmdlet", with "Fixes #5" in the PR's body. -* 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. +* 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 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: +* Include an update to the [changelog](../CHANGELOG.MD) in your pull request. + New changes always go into the **Unreleased** section. + Keeping the changelog up-to-date simplifies the release process for maintainers. + An example: ``` - ## Versions + Unreleased + ---------- - ### Unreleased - - - Added support for `-FriendlyName` in `Update-Item`. + * `Update-Item` now supports `-FriendlyName`. ``` - Please use past tense when describing your changes: + Please use the present tense and imperative mood when describing your changes: - * Instead of "Adding support for Windows Server 2012 R2", write "Added support for Windows Server 2012 R2". + * Instead of "Adding support for Windows Server 2012 R2", write "Add 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'" + * Instead of "Fixed for server connection issue", write "Fix server connection issue". -#### Pull request - Automatic checks + This form is akin to giving commands to the code base, + and is recommended by the Git SCM developers. + It is also used in the [Git commit messages](#common-engineering-practices). + + Also, if change is related to a specific resource, please prefix the description with the resource name: -* 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. + * Instead of "New,parameter 'ConnectionCredential' in New-SqlConnection", + write "New-SqlConnection: added parameter 'ConnectionCredential'". -#### Pull request - Code review +#### 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. -* 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. +* 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 and 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 will do a code review, + commenting on any changes that might need to be made. + +* Additional feedback is always welcome! + Even if you are not designated as an area's maintainer, + feel free to review others' pull requests anyway. + Leave your comments even if everything looks good; + a simple "Looks good to me" or "LGTM" will suffice. + This way 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 will merge your changes. + +* For more information on the the PowerShell maintainers' process, + see the [documentation](../docs/maintainers). 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), -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) +When you make code changes, +please pay attention to these that can affect the [Public Contract](../docs/dev-process/breaking-change-contract.md). +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) 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) -and [testing](../docs/testing-guidelines/testing-guidelines.md)) discussed above, we encourage contributors to follow these common engineering practices: +---------------------------- -- Format commit messages based on [Tim Pope's guidelines]("http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html"): +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: + +* Format commit messages following these guidelines: ``` Summarize change in 50 characters or less -Provide more detail after the first line. Leave one blank line below the -summary and wrap all lines at 72 characters or less. +Similar to email, this is the body of the commit message, +and the above is the subject. +Always leave a single blank line between the subject and the body +so that `git log` and `git rebase` work nicely. -If the change fixes an issue, leave another blank line after the final -paragraph and indicate which issue the change fixes in the specific format below. +The subject of the commit should use the present tense and +imperative mood, like issuing a command: -Fix #42 +> Makes abcd do wxyz + +The body should be a useful message explaining +why the changes were made. + +If significant alternative solutions were available, +explain why they were discarded. + +Keep in mind that the person most likely to refer to your commit message +is you in the future, so be detailed! + +As Git commit messages are most frequently viewed in the terminal, +you should wrap all lines around 72 characters. + +Using semantic line feeds (breaks that separate ideas) +is also appropriate, as is using Markdown syntax. ``` -- 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 -- Create and/or update tests when making code changes -- Run tests and ensure they are passing before pull request -- All pull requests **must** pass CI systems before they can be approved -- Avoid making big pull requests. Instead, file an issue and start a discussion with the community before you invest a large amount of time -- Blog and tweet about your contributions frequently! +* These are based on Tim Pope's [guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), + Git SCM [submitting patches](https://git.kernel.org/cgit/git/git.git/tree/Documentation/SubmittingPatches), + Brandon Rhodes' [semantic linefeeds][], + and John Gruber's [Markdown syntax](https://daringfireball.net/projects/markdown/syntax). + +* 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. + +* Create and/or update tests when making code changes. + +* Run tests and ensure they are passing before 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, + file an issue and start a discussion with the community. File Headers ----- -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). +------------ + +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). + ```C# // … TODO TODO // Licensed to the PowerShell …. under one or more agreements. // See the LICENSE file in the project root for more information. ``` -Licensing & Copyright ----- +Licensing and Copyright +----------------------- + You can find more information about the PowerShell source license and copyright [here](../docs/community/legal-licensing.md). Contributor License Agreement (CLA) ----- +----------------------------------- -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. +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`. @@ -174,12 +273,11 @@ Once you sign a CLA, all your existing and future pull requests will be labeled [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 +[semantic linefeeds]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/