mirror of
https://github.com/PowerShell/PowerShell
synced 2026-06-08 12:12:50 +00:00
Add documentation requirements to CONTRIBUTING.md (#3794)
This commit is contained in:
Joey Aiello
committed by
Travis Plunk
Travis Plunk
parent
3133f85443
commit
a164609eea
+51
-69
@@ -1,5 +1,4 @@
|
||||
Contributing to PowerShell
|
||||
========================
|
||||
# Contributing to PowerShell
|
||||
|
||||
We welcome and appreciate contributions from the community.
|
||||
There are many ways to become involved with PowerShell:
|
||||
@@ -9,25 +8,21 @@ 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?
|
||||
-----------
|
||||
## Intro to Git and GitHub
|
||||
|
||||
* 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 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.
|
||||
step-by-step instructions of GitHub Flow
|
||||
|
||||
Quick Start Checklist
|
||||
---------------------
|
||||
## Quick Start Checklist
|
||||
|
||||
* Review the [Contribution License Agreement][CLA] requirement.
|
||||
* Get familiar with the [PowerShell repository](../docs/git).
|
||||
|
||||
Contributing to Issues
|
||||
----------------------
|
||||
## Contributing to Issues
|
||||
|
||||
* Review [Issue Management][issue-management].
|
||||
* Check if the issue you are going to file already exists in our [GitHub issues][open-issue].
|
||||
@@ -37,8 +32,7 @@ Contributing to Issues
|
||||
* If the issue is marked as [`Up-for-Grabs`][up-for-grabs],
|
||||
the PowerShell Maintainers are looking for help with the issue.
|
||||
|
||||
Contributing to Documentation
|
||||
-----------------------------
|
||||
## Contributing to Documentation
|
||||
|
||||
### Contributing to documentation related to PowerShell
|
||||
|
||||
@@ -58,25 +52,29 @@ which can be run in interactive mode to correct typos or add words to the ignore
|
||||
(`.spelling` at the repository root).
|
||||
|
||||
To run the spellchecker, follow the steps as follows:
|
||||
* install [Node.js](https://nodejs.org/en/) (v6.4.0 or up)
|
||||
* install [markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) by
|
||||
`npm install -g markdown-spellcheck` (v0.11.0 or up)
|
||||
* run `mdspell "**/*.md" --ignore-numbers --ignore-acronyms`
|
||||
* if the `.spelling` file is updated, commit and push it
|
||||
|
||||
Contributing to Code
|
||||
--------------------
|
||||
* install [Node.js](https://nodejs.org/en/) (v6.4.0 or up)
|
||||
* install [markdown-spellcheck](https://github.com/lukeapage/node-markdown-spellcheck) by
|
||||
`npm install -g markdown-spellcheck` (v0.11.0 or up)
|
||||
* run `mdspell "**/*.md" --ignore-numbers --ignore-acronyms`
|
||||
* if the `.spelling` file is updated, commit and push it
|
||||
|
||||
## Contributing to Code
|
||||
|
||||
### Building and testing
|
||||
|
||||
#### 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.
|
||||
|
||||
### 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.
|
||||
1. Mention in the issue that you are working on the issue and ask `@powershell/powershell` for an assignment.
|
||||
|
||||
### Forks and Pull Requests
|
||||
|
||||
@@ -87,11 +85,11 @@ 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](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
|
||||
|
||||
#### Before submitting
|
||||
@@ -103,7 +101,6 @@ Additional references:
|
||||
Each commit should be a **single complete** change.
|
||||
This discipline is important when reviewing the changes as well as when using `git bisect` and `git revert`.
|
||||
|
||||
|
||||
#### Pull request submission
|
||||
|
||||
**Always create a pull request to the `master` branch of this repository**.
|
||||
@@ -111,60 +108,59 @@ Additional references:
|
||||
|
||||
|
||||
* If you're contributing in a way that changes the user or developer experience, you are expected to document those changes.
|
||||
See [Contributing to documentation related to PowerShell](#contributing-to-documentation-related-to-powershell).
|
||||
|
||||
See [Contributing to documentation related to PowerShell](#contributing-to-documentation-related-to-powershell).
|
||||
* 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,
|
||||
including a summary of what's included in your changes and
|
||||
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.
|
||||
|
||||
* If the change warrants a note in the [changelog](../CHANGELOG.MD)
|
||||
either update the changelog in your pull request or
|
||||
add a comment in the PR description saying that the change may warrant a note in the changelog.
|
||||
New changes always go into the **Unreleased** section.
|
||||
Keeping the changelog up-to-date simplifies the release process for Maintainers.
|
||||
An example:
|
||||
```
|
||||
Unreleased
|
||||
----------
|
||||
An example (with an associated PR #):
|
||||
|
||||
* `Update-Item` now supports `-FriendlyName`.
|
||||
```
|
||||
Please use the present tense and imperative mood when describing your changes:
|
||||
```markdown
|
||||
Unreleased
|
||||
----------
|
||||
|
||||
* Instead of "Adding support for Windows Server 2012 R2", write "Add support for Windows Server 2012 R2".
|
||||
* `Update-Item` now supports `-FriendlyName` (#1234).
|
||||
```
|
||||
|
||||
* Instead of "Fixed for server connection issue", write "Fix server connection issue".
|
||||
* Please use the present tense and imperative mood when describing your changes:
|
||||
* Instead of "Adding support for Windows Server 2012 R2", write "Add support for Windows Server 2012 R2".
|
||||
* Instead of "Fixed for server connection issue", write "Fix server connection issue".
|
||||
|
||||
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:
|
||||
|
||||
* Instead of "New,parameter 'ConnectionCredential' in New-SqlConnection",
|
||||
write "New-SqlConnection: added parameter 'ConnectionCredential'".
|
||||
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).
|
||||
* If the change is related to a specific resource, please prefix the description with the resource name:
|
||||
* Instead of "New parameter 'ConnectionCredential' in New-SqlConnection",
|
||||
write "New-SqlConnection: add parameter 'ConnectionCredential'".
|
||||
* If your change warrants an update to user-facing documentation,
|
||||
a Maintainer will add the `Documentation Needed` label to your PR and add an issue to the [PowerShell-Docs repository][PowerShell-Docs],
|
||||
so that we make sure to update official documentation to reflect your contribution.
|
||||
As an example, this requirement includes any changes to cmdlets (including cmdlet parameters) and features which have associated about_* topics.
|
||||
While not required, we appreciate any contributors who add this label and create the issue themselves.
|
||||
Even better, all contributors are free to contribute the documentation themselves.
|
||||
(See [Contributing to documentation related to PowerShell](#contributing-to-documentation-related-to-powershell) for more info.)
|
||||
|
||||
#### 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 and AppVeyor)][ci-system]
|
||||
will run a suite of tests and automatically update the status of the pull request.
|
||||
|
||||
* Our CI contains automated spellchecking. If there is any false-positive,
|
||||
[run the spellchecker command line tool in interactive mode](#spellchecking-documentation)
|
||||
[run the spellchecker command line tool in interactive mode](#spellchecking-documentation)
|
||||
to add words to the `.spelling` file.
|
||||
|
||||
#### Pull Request - Code Review
|
||||
@@ -186,22 +182,18 @@ See [Contributing to documentation related to PowerShell](#contributing-to-docum
|
||||
* For a PR to be merged, it must be approved by at least one PowerShell Team member or Collaborator,
|
||||
so additional Reviewer(s) may be added by the Assignee as appropriate.
|
||||
The Assignee may also be re-assigned by Maintainers.
|
||||
|
||||
* A Reviewer can postpone the code review if CI builds fail,
|
||||
but also can start the code review early regardless of the CI builds.
|
||||
|
||||
* The Author **is responsible** for driving the PR to the Approved state.
|
||||
The Author addresses review comments, and pings Reviewer(s) to start the next iteration.
|
||||
If the review is making no progress (or very slow),
|
||||
the Author can always ask the Assignee to help coordinate the process and keep it moving.
|
||||
|
||||
* Additional feedback is always welcome!
|
||||
Even if you are not designated as a Reviewer,
|
||||
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!
|
||||
|
||||
* When updating your pull request, please **create new commits**
|
||||
and **don't rewrite the commits history**. This way it's very easy for
|
||||
the reviewers to see diff between iterations.
|
||||
@@ -209,17 +201,14 @@ See [Contributing to documentation related to PowerShell](#contributing-to-docum
|
||||
Once the review is done, you can rewrite the history to make it prettier,
|
||||
if you like.
|
||||
Otherwise it's likely would be squashed on merge to master.
|
||||
|
||||
* Once the code review is done,
|
||||
all merge conflicts are resolved,
|
||||
and the CI system build status is passing,
|
||||
the PR Assignee will merge your changes.
|
||||
|
||||
* For more information on the the PowerShell Maintainers' process,
|
||||
* For more information on the PowerShell Maintainers' process,
|
||||
see the [documentation](../docs/maintainers).
|
||||
|
||||
Making Breaking Changes
|
||||
-----------------------
|
||||
## 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).
|
||||
@@ -228,14 +217,12 @@ 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
|
||||
---------------------
|
||||
## 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.
|
||||
|
||||
Common Engineering Practices
|
||||
----------------------------
|
||||
## 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,
|
||||
@@ -277,23 +264,17 @@ is also appropriate, as is using Markdown syntax.
|
||||
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.
|
||||
|
||||
Contributor License Agreement (CLA)
|
||||
-----------------------------------
|
||||
## 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.
|
||||
@@ -321,3 +302,4 @@ Once you sign a CLA, all your existing and future pull requests will be labeled
|
||||
[open-issue]: https://github.com/PowerShell/PowerShell/issues
|
||||
[up-for-grabs]: https://github.com/powershell/powershell/issues?q=is%3Aopen+is%3Aissue+label%3AUp-for-Grabs
|
||||
[semantic linefeeds]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
|
||||
[PowerShell-Docs]: https://github.com/powershell/powershell-docs/
|
||||
Reference in New Issue
Block a user