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

Merge pull request #1305 from PowerShell/vors/docs

Browse source 
Update docs, assigned to Sergei
This commit is contained in:
Sergei Vorobev 2016-07-08 16:25:24 -07:00 committed by GitHub
parent 5e1cbe0e5d 7ea99107ec
commit cb1c6e1245
7 changed files with 148 additions and 207 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/building/windows-full.md
View file

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

1
docs/dev-process/setup-dev-environment.md
View file

@ -1 +0,0 @@
author: Sergei and Andy

2
docs/dev-process/tryit.md
View file

@ -1,2 +0,0 @@
author: Sergei and Andy
> steps for Trying out with the binaries a developer just built

93
docs/git/basics.md
View file

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

58
docs/git/committing.md
View file

@ -1,58 +0,0 @@
Commit Dance
============
This process only applies to `src/Modules/Pester`.
If you need to touch their content, this doc
provides the overview of the process. Remember that it's written
against `src/monad` submodule, which doesn't exist anymore.
Also see the [submodules documentation](./submodules.md).
Sometimes, you need to do the work in a submodule (i.e. you added a new string in `.resx` file).
The submodule has a relationship to the SuperProject (PowerShell), but in order to be sure that CI is
notified about changes in a submodule, you need be sure that this is reflected as a pull request in the SuperProject.
**Scenario**: Jim fixes issue in `src/monad/monad/src/engine/DataStoreAdapter.cs`
the following takes place in the submodule:
* Make the code change
* Commit the code change in a feature branch. Branch name in form `<alias>/<moniker>`, i.e `jim/colon-drive`.
* Push the branch (in the submodule project): `git push origin jim/colon-drive`
* Pull request in the submodule to notify people via email about new code review.
Then, in the SuperProject (PowerShell)
* `git status` should show a change of submodule **as a whole** (not individual files). _In my case_ it is `src/monad`.
* `git diff` should show something like
```diff
index 1ba8dd4..ed5d202 160000
--- a/src/monad
+++ b/src/monad
@@ -1 +1 @@
-Subproject commit 1ba8dd4f721f2cd4363f64609515ec1600378c30
+Subproject commit ed5d2022617f317a78a8a57e2c257c8e29cddbd5
```
* Commit that change into a branch with the same name, i.e. `jim/colon-drive`
* Push the branch (in the SuperProject): `git push origin jim/colon-drive`
* Pull request in the superproject to kick-in CI build and notify people. Reference submodule pull-request in the PR message to make navigation between two simpler.
Commands log
------------
Here is a transcript of command Jim used:
```sh
cd $HOME/PowerShell/src/monad/monad/src/engine
vi DataStoreAdapter.cs
git checkout -b jim/colon-drive
git commit -a
git push origin jim/colon-drive
```
then I went to the web interface and did the pull request *in the submodule*. After that, back to the commandline:
```sh
cd $HOME/PowerShell
git checkout -b jim/colon-drive
git commit -a
git push origin jim/colon-drive
```
and back to the web interface for the pull request *in the superproject*.

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

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

52
docs/git/source-depot.md
View file

@ -1,52 +0,0 @@
# Quick git-primer for sd users
There few important conceptual differences with **sd**.
This list tries to bridge the gap
* When you do `git commit` changes are stored in your local clone of the repo.
To Submit them, you need to do `git push`.
* Forks are just a way to store branches.
You can push branch to the original repo (if you have permissions) or to the fork.
There is no principal difference.
* Most of the git complications come from the fact that you need to do integrations by yourself.
The Microsoft Open Source Hub [article](https://opensourcehub.microsoft.com/articles/git-for-sd-users) for other details.
### Rosetta stone
#### Concepts
| Concept | SD termin | Git termin |
|---------|----|----------------|
| Your local copy | enlistment | cloned repo |
| Code changes | changelist | commit |
| Way to preserve changes locally | dpk | local branch |
#### Commands
Before running a git command for the first time, try
```sh
git help <command name>
```
To read about flags and the overall meaning.
|Scenarios | SD command | Git commmand |
|---------|----|----------------|
| Get the code at the first place | sd enlist | git clone |
| Sync changes | sd sync | git pull |
| Add new files | sd add | git add |
| Modify existing files | sd edit | git add |
| Remove existing files | sd delete | git rm |
| Copy/Rename files | sd branch | git mv |
| Commit to local | | git commit |
| Submit changes | sd submit | git push |
| Revert changes | sd revert | git checkout |
| Undo submitted changes | sd undo | git revert |
| Diff tool | odd | git diff |
| Clean enlistment | build nuke | git clean |