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

Merge pull request #1335 from PowerShell/joey/refactor-docs

Browse source 
Joey/refactor docs
This commit is contained in:
Joey Aiello 2016-07-12 17:12:39 -07:00 committed by GitHub
parent 6ac0e1afdb 0eac00ed0b
commit 76d8b45a93
9 changed files with 113 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
.github/CONTRIBUTING.md vendored
View file

@ -9,54 +9,59 @@ 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.
- [Commit process](../docs/git/committing.md): step-by-step instructions how to commit your changes
- [Git for sd users](../docs/git/source-depot.md): a handy reference document for people familiar with `sd`
Quick Start Check-list
----
- Read [the Community Governance](../docs/community/governance.md)
- Make sure you have signed [PowerShell Contribution License Agreement (CLA)](#contributor-license-agreement) before pull request
- Make sure you have signed a [PowerShell Contribution License Agreement (CLA)](#contributor-license-agreement) before submitting a pull request
- Get familiar with the [PowerShell repository](../docs/git/powershell-repository-101.md)
- Setup your [development environment](../docs/dev-process/setup-dev-environment.md)
- Build the [PowerShell repository](https://github.com/PowerShell/PowerShell)
- [Try it out with the binaries you just built](../docs/dev-process/tryit.md)
Contributing to Issue
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 Label, Assignee and the guidance like verifying and closing issues
- Check if the issue you are going to file already exists in [GitHub Issue query](https://github.com/PowerShell/PowerShell/issues)
- Submit an issue, assuming it does not exist yet, via [GitHub Issue track](https://github.com/PowerShell/PowerShell/issues) by following the issue template.
- 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)
- 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.
Contributing to Documentation
----
- Choose what to work on. Check the list of [documentation issues](https://github.com/PowerShell/PowerShell-Docs/issues) to see if someone is already working on it.
- If you cannot find an existing issue for your desired work, open a new issue for your work.
- 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.
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](../docs/dev-process/issue-management-process.md).
- If you will be adding a new cmdlet or other design changes, follow [Making Design Changes guidelines](#making-design-changes)
- For breaking changes, see [Make Breaking Changes guidelines](#making-breaking-changes)
- If you would like to be assigned to the issue, please ask @powershell/powershell (TODO) for an assignment
- 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 (TODO) on the pull request.
- Perform a [code review](../docs/dev-process/code-review-guidelines.md) with the [PowerShell Committee][governance] on the pull request.
[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
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 starting making changes to the code, first review the [Breaking Changes guidelines](../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)
and follow the guidelines to keep PowerShell backward compatible.
Making Design Changes
@ -65,10 +70,11 @@ To add new features such as cmdlets or making design changes, please follow the
Common Engineering Practices
----
Other than the guidelines ([coding](../docs/coding-guidelines/coding-guidelines.md), [RFC process](https://github.com/PowerShell/PowerShell-RFC) for design, [documentation](#contributing-to-documentation)
and [testing](../docs/testing-guidelines/testing-guidelines.md)) discussed above, following are common engineering practices we would like everyone to follow:
- 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 as follows based on [the 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:
- 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"):
```
Summarize change in 50 characters or less
@ -87,12 +93,12 @@ Fix #42
- 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 a big pull requests. Instead, file an issue and start a discussion with the community before you invest a large amount of time
- 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!
File Headers
----
The following file header is the used for PowerShell. 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.
@ -101,16 +107,13 @@ The following file header is the used for PowerShell. Please use it for new file
Licensing & Copyright
----
You can find [here](../docs/community/legal-licensing.md) for the PowerShell sources license and copyright information.
You can find more information about the PowerShell source license and copyright [here](../docs/community/legal-licensing.md).
Contributor License Agreement
Contributor License Agreement (CLA)
----
You must sign a PowerShell Contribution License Agreement (CLA) before your Pull Request will be merged.
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 can read more about [Contribution License Agreements (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) on wikipedia.
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
(e.g. you just fixed a typo), then the PR is labelled with cla-not-required. Otherwise it's
classified as cla-required. Once you signed a CLA, the current and all future pull-requests will be
labelled as cla-signed.
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.

2
.github/PULL_REQUEST_TEMPLATE.md vendored
View file

@ -1,6 +1,6 @@
<!-- PR checklist -->
- [ ] Resolves #xyz.
- [ ] Resolves issue #xyz.
- [ ] Code is up-to-date with `master`.
- [ ] Add tests that fail without your changes.
- [ ] Update all relevant [documentation](../docs).

12
README.md
View file

@ -49,26 +49,26 @@ Developing and Contributing
If you are new to Git, we recommend you start by reviewing our
[Git basics document][git-basics] where you will find Git installation
instructions, cheat sheets and links to our favorite Git tutorials. We also
recommend, reviewing an example of a [basic Git commit walkthrough][git-commit].
recommend, reviewing an example of a [basic Git commit walkthrough][git-commit].
To begin development, you'll need to setup your development environment for
either [Linux][build-linux], [Windows Core][build-wc], [Windows Full][build-wf] or
To begin development, you'll need to setup your development environment for [Linux][build-linux], [Windows Core][build-wc], [Windows Full][build-wf] or
[OS X][build-osx] and are encouraged to review the
[contribution guidelines][contribution] for specific workflow, test
requirements and coding guidelines.
If you encounter issues, please consult the [known issues][known-issues]
If you encounter issues in your development, please consult the [known issues][known-issues]
and [FAQ][faq] documents to see if the issue you are running into is
captured and if a workaround exists.
If do not see your issue captured, please file a [new issue][new-issue] using
If you encounter issues with PowerShell itself, first search for it in our [issues][github-issues]. If you do not see your issue captured, please file a [new issue][new-issue] using
the appropriate issue tag.
[git-basics]: docs/git/basics.md
[git-commit]: docs/git/committing.md
[git-commit]: docs/git/powershell-repository-101.md
[contribution]: .github/CONTRIBUTING.md
[known-issues]: docs/KNOWNISSUES.md
[faq]: docs/FAQ.md
[github-issues]:https://github.com/PowerShell/PowerShell/issues
[new-issue]:https://github.com/PowerShell/PowerShell/issues/new

8
docs/community/governance.md
View file

@ -2,3 +2,11 @@ author: Joey
> PowerShell community, twitter, facebook, linkedIn...)
> Community ground rules, appeals process (if they disagree with our decision)
> SME
TODO
1. Define a difference between small, medium, large design decisions/bugs
a. Point to quick fix doc
2. Explain the RFC process
3. Define maintainer vs. feature owner
4. Define committee
5.

5
docs/community/legal-licensing.md
View file

@ -1 +1,6 @@
author: Joey
TODO: It's MIT
Make sure to CLA
Do we even need this doc?

0
docs/coding-guidelines/coding-guidelines.md → docs/dev-process/coding-guidelines.md
View file

30
docs/dev-process/issue-management-process.md
View file

@ -1,6 +1,34 @@
author: Andy
author: Jason/Andy
> meaning of label, assignees, etc.
> triage process
> requirements for resolving (timing), closing...
## Long-living issue labels
### Feature areas
These labels describe what feature area of PowerShell that an issue addresses.
* `Area-Build`:
* `Area-Cmdlets`:
* `Area-Console`:
* `Area-Debugging`:
* `Area-Documentation`:
* `Area-Engine`:
* `Area-Intellisense`:
* `Area-Language`:
* `Area-OMI`:
* `Area-PackageManagement`:
* `Area-Performance`:
* `Area-Portability`:
* `Area-PSReadline`:
* `Area-Test`:
### Operating systems
These are for issues that are specific to certain operating systems:
* `OS-Linux`
* `OS-OS X`
* `OS-Windows`

12
docs/dev-process/pull-request-rules.md
View file

@ -6,3 +6,15 @@ author: Hemant
> "some tests we can only run internally"
> exact timeline not need for Aug17
> Windows quality gates
## Minimum gates (TODO)
Our [pull request template][pr-template] includes the bare minimum requirements for a pull request to be accepted into PowerShell. This includes:
* Writing tests
* Writing documentation (where does thie one live already? is it where this guidance should exist all up?)
* Our [code review process][code-review]
* Repository maintainer sign-off, per our [governance model][governance]
[pr-template]: ../.github/PULL_REQUEST_TEMPLATE.md
[code-review]: code-review-guidelines.md
[governance]: ../community/governance.md

35
docs/git/powershell-repository-101.md
View file

@ -7,10 +7,9 @@ Working with PowerShell repository
git clone --recursive https://github.com/PowerShell/PowerShell
```
PowerShell repository has **submodules**.
They are required to build and test powershell.
That's why you need `--recursive`, when you `clone`.
The PowerShell repository has **submodules**.
They are required to build and test PowerShell.
That's why you need `--recursive`, when you `git clone`.
If you already cloned the repo without `--recursive`, update submodules manually
@ -22,32 +21,28 @@ git submodule update
See [FAQ](../FAQ.md#why-is-my-submodule-empty) for details.
Branches
---------
* Don't commit your changes directly to master.
It would make workflow messy.
* Checkout a new local branch from master for every change you want to make (bugfix, feature).
* Use `alias/feature-name` pattern.
It will make the collaborative workflow messy.
* Checkout a new local branch from `master` for every change you want to make (bugfix, feature).
* Use the `username/feature-name` pattern for naming branches.
* Use lowercase-with-dashes for naming.
* Follow [Linus' recommendations][Linus] about history.
- People can (and probably should) rebase their _private_ trees (their own
work). That's a _cleanup_. But never other peoples code. That's a "destroy
history"
- You must never EVER destroy other peoples history. You must not rebase
commits other people did. Basically, if it doesn't have your sign-off
on it, it's off limits: you can't rebase it, because it's not yours.
- "People can (and probably should) rebase their _private_ trees (their own work). That's a _cleanup_. But never other peoples code. That's a 'destroy history'...
You must never EVER destroy other peoples history. You must not rebase commits other people did.
Basically, if it doesn't have your sign-off on it, it's off limits: you can't rebase it, because it's not yours."
#### Understand branches
* **master** is the branch with the latest and gratest changes.
* **master** is the branch with the latest and greatest changes.
It could be unstable.
* Send your Pull Requests to **master**.
* Send your pull requests to **master**.
#### Sync your local repo
Use **git rebase** instead of **git merge** and **git pull**, when you updating your feature-branch.
Use **git rebase** instead of **git merge** and **git pull**, when you're updating your feature-branch.
```sh
# switch to master branch
@ -63,7 +58,7 @@ git pull origin master
```
Then switch to your branch and do rebase
Then switch to your branch and do a rebase
```
git rebase master
@ -81,7 +76,6 @@ We are leaving few links here:
[Linus]:http://thread.gmane.org/gmane.comp.video.dri.devel/34739/focus=34744
Tags
------
@ -92,7 +86,7 @@ you will find it via **tags**.
* Find the tag that corresponds to the release.
* Use `git checkout <tag-name>` to get this version.
**Note:** [checking out tag][] will move the repo in [DETACHED HEAD][] state.
**Note:** [checking out a tag][] will move the repo to a [DETACHED HEAD][] state.
[checking out tag]:https://git-scm.com/book/en/v2/Git-Basics-Tagging#Checking-out-Tags
[DETACHED HEAD]:https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit
@ -105,7 +99,6 @@ git checkout -b vors/hotfix
```
Recommended Git configurations
==============================