Merge pull request PowerShell#1305 from PowerShell/vors/docs

Update docs, assigned to Sergei

docs/building/windows-full.md

@@ -86,16 +86,14 @@ Start-DevPowerShell -binDir (Split-Path -Parent (Get-PSOutput))
 ```
 
 The default for produced `powershell.exe` is x64.
-You can contorl it with `Start-PSBuild -FullCLR -NativeHostArch x86`
+You can control it with `Start-PSBuild -FullCLR -NativeHostArch x86`
 
 Build manually
 ==============
 
-The build logic is relatively simple and contains the following steps:
+The build contains the following steps:
 
-- building managed DLLs: `dotnet publish --runtime net451`
 - generating Visual Studio project: `cmake`
 - building `powershell.exe` from generated solution: `msbuild
   powershell.sln`
-
-Please don't hesitate to experiment.
+- building managed DLLs: `dotnet publish --runtime net451`

docs/git/basics.md

@@ -1,13 +1,12 @@
-# Git 101
+Getting started with git
+========================
 
-We are using Git version 2.8.1, but any recent version should be good.
+We are using Git version 2.9.0, but any recent version should be good.
 It's recommended to learn the `git` command line tool for full
 cross-platform experience and a deeper understanding of Git itself.
 
-There are (too) many Git tutorials on the internet. Here we post
-references to our favorites.
-
-## Install
+Install
+---------
 
 #### Windows
 
@@ -31,7 +30,11 @@ Install via the package manager:
 sudo apt-get install git
 ```
 
-## Interactive tutorials
+Interactive tutorials
+----------------------
+
+There are (too) many Git tutorials on the internet. Here we post
+references to our favorites.
 
 #### Hello world
 
@@ -50,52 +53,6 @@ learn Git in couple hours. After finishing 50+ real-world scenarios
 you will have a pretty good idea about what and when you can do with
 Git.
 
-## Cheatsheets
-
-#### Git pretty
-
-[So you have a mess on your hands?](http://justinhileman.info/article/git-pretty/)
-
-## Scenarios
-
-#### Sync your local repo
-
-Don't commit your changes directly to master.
-It would make workflow messy.
-
-Always create a branch for your changes.
-
-```sh
-# switch to master branch
-
-# fetch updates all remote branch references in the repo and all submodules
-# --all : tells it to do it for all remotes (handy, when you use your fork)
-# -p : tells it to remove obsolete remote branch references (when they are removed from remote)
-git fetch --all -p
-
-# pull updates your local files
-# you should call this command ONLY from master branch
-git pull origin master
-
-# update submodules: this checks the submodules out to the commit recorded in the superproject
-git submodule update
-```
-
-Then switch to your branch and do rebase
-
-```
-git rebase master
-```
-
-[Branches](../docs/workflow/branches.md)
--------------------------------------
-
-* Checkout a new local branch for every change you want to make (bugfix, feature).
-* Use `alias/feature-name` pattern.
-* Use lowercase-with-dashes for naming.
-* Use same branch name in superproject and all [submodules][].
-
-[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
 
 Authentication
 --------------
@@ -128,33 +85,3 @@ Your should push to this repository instead of a fork so that the CI system can
 provide credentials to your pull request. If you make a pull request from a
 fork, the CI *will* fail.
 
-Recommended Git configurations
-------------------------------
-
-We highly recommend these configurations to help deal with whitespace,
-rebasing, and general use of Git.
-
-> Auto-corrects your command when it's sure (`stats` to `status`)
-```sh
-git config --global help.autoCorrect -1
-```
-
-> Refuses to merge when pulling, and only pushes to branch with same name.
-```sh
-git config --global pull.ff only
-git config --global push.default current
-```
-
-> Shows shorter commit hashes and always shows reference names in the log.
-```sh
-git config --global log.abbrevCommit true
-git config --global log.decorate short
-```
-
-> Ignores whitespace changes and uses more information when merging.
-```sh
-git config --global apply.ignoreWhitespace change
-git config --global rerere.enabled true
-git config --global rerere.autoUpdate true
-git config --global am.threeWay true
-```

docs/git/powershell-repository-101.md

@@ -1,9 +1,138 @@
-author:  Sergei and Andy
+Working with PowerShell repository
+==================================
 
+#### Get the code for the first time
 
+```sh
+git clone --recursive https://github.com/PowerShell/PowerShell
+```
 
->getting started working with PowerShell github
->branch structure intro
-  >	branching (and folder) structure (where do I submit PRs? where's the release branch? dev branch? working branch?)
->PR process and requirements
-> more
+PowerShell repository has **submodules**.
+They are required to build and test powershell.
+That's why you need `--recursive`, when you `clone`.
+
+
+If you already cloned the repo without `--recursive`, update submodules manually
+
+```sh
+git submodule init
+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.
+* 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.
+
+#### Understand branches
+
+* **master** is the branch with the latest and gratest changes.
+  It could be unstable.
+* 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.
+
+```sh
+# switch to master branch
+
+# fetch updates all remote branch references in the repo and all submodules
+# --all : tells it to do it for all remotes (handy, when you use your fork)
+# -p : tells it to remove obsolete remote branch references (when they are removed from remote)
+git fetch --all -p
+
+# pull updates your local files
+# you should call this command ONLY from master branch
+git pull origin master
+
+```
+
+Then switch to your branch and do rebase
+
+```
+git rebase master
+```
+
+#### More complex scenarios
+
+Covering all possible git scenarios is behind the scope of the current document.
+Git has excellent documentation and lots of materials available online.
+
+We are leaving few links here:
+
+[Git pretty flowchart](http://justinhileman.info/article/git-pretty/): what to do, when your local repo became a mess.
+
+[Linus]:http://thread.gmane.org/gmane.comp.video.dri.devel/34739/focus=34744
+
+
+
+Tags
+------
+
+If you are looking for the source code for a particular release,
+you will find it via **tags**.
+
+* `git tag` will show you list of all 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.
+
+[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
+
+If you want to make changes, based on tag's version (i.e. a hotfix), 
+checkout a new branch from this DETACHED HEAD state.
+
+```sh
+git checkout -b vors/hotfix
+```
+
+
+
+Recommended Git configurations
+==============================
+
+We highly recommend these configurations to help deal with whitespace,
+rebasing, and general use of Git.
+
+> Auto-corrects your command when it's sure (`stats` to `status`)
+```sh
+git config --global help.autoCorrect -1
+```
+
+> Refuses to merge when pulling, and only pushes to branch with same name.
+```sh
+git config --global pull.ff only
+git config --global push.default current
+```
+
+> Shows shorter commit hashes and always shows reference names in the log.
+```sh
+git config --global log.abbrevCommit true
+git config --global log.decorate short
+```
+
+> Ignores whitespace changes and uses more information when merging.
+```sh
+git config --global apply.ignoreWhitespace change
+git config --global rerere.enabled true
+git config --global rerere.autoUpdate true
+git config --global am.threeWay true
+```