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

Joey/refactor docs

docs/community/governance.md

@@ -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.  

docs/community/legal-licensing.md

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

docs/dev-process/issue-management-process.md

@@ -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`

docs/dev-process/pull-request-rules.md

@@ -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

docs/git/powershell-repository-101.md

@@ -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
 ==============================