Merge pull request #772 from PowerShell/vors/docs

Add workflow docs and links to them

CONTRIBUTING.md

@@ -65,7 +65,7 @@ Particularly:
 [MS-OSS-Hub]: https://opensourcehub.microsoft.com/articles/how-to-join-microsoft-github-org-self-service
 [2 factor authentication]: https://github.com/blog/1614-two-factor-authentication
 
-Branches
+[Branches](docs/workflow/branches.md)
 --------
 
 * Checkout a new local branch for every change you want to make (bugfix, feature).
@@ -109,6 +109,7 @@ updates, ensure no other changes are in the same commit. Submodule
 bumps may be included in feature branches for ease of work, but the
 update must be independently approved before merging into master.
 
+
 Recommended Git configurations
 ------------------------------
 
@@ -139,3 +140,14 @@ git config --global rerere.enabled true
 git config --global rerere.autoUpdate true
 git config --global am.threeWay true
 ```
+
+[Mapping](docs/workflow/mapping.md)
+--------
+
+Learn about new files locations in PowerShell/PowerShell.
+
+[Resources](docs/workflow/resources.md)
+--------
+
+Learn how to work with string resources in `.resx` files.
+

README.md

@@ -16,10 +16,10 @@ flavor of PowerShell. It is a collaborative effort among many teams:
 Build Status
 ------------
 
-| Platform     | `master` | `server2016` |
-|--------------|----------|--------------|
-| Ubuntu 14.04 | [![Build Status](https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master)](https://travis-ci.com/PowerShell/PowerShell) | [![Build Status](https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=server2016)](https://travis-ci.com/PowerShell/PowerShell) |
-| Windows      | [![Build status](https://ci.appveyor.com/api/projects/status/wb0a0apbn4aiccp1/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/powershell-linux/branch/master) |  [![Build status](https://ci.appveyor.com/api/projects/status/wb0a0apbn4aiccp1/branch/server2016?svg=true)](https://ci.appveyor.com/project/PowerShell/powershell-linux/branch/server2016) |
+| Platform     | `master` |
+|--------------|----------|
+| Ubuntu 14.04 | [![Build Status](https://travis-ci.com/PowerShell/PowerShell.svg?token=31YifM4jfyVpBmEGitCm&branch=master)](https://travis-ci.com/PowerShell/PowerShell) |
+| Windows      | [![Build status](https://ci.appveyor.com/api/projects/status/wb0a0apbn4aiccp1/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/powershell-linux/branch/master) |
 
 Get PowerShell
 --------------

docs/git/committing.md

@@ -1,5 +1,10 @@
 #Commit Dance
-Most of the time, you're going to be working in a submodule (say src/monad/monad/engine).
+
+**Update:** commit dance became much simpler after [removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656).
+Meahwhile, there are still few submodules. 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.
+
+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.
 

docs/workflow/branches.md

@@ -0,0 +1,10 @@
+# Branches
+
+PowerShell has a number of [long-living](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows#Long-Running-Branches) branches
+
+* **master** -- current development, upstream. It's based on source-depot, but has changes for Linux/OS X. 
+It also has changes for the latest version of .NET Core, i.e. rc3.
+* **source-depot** -- an exact mirror of dev branch in Source Depot for all [mapped](./mapping.md) files. 
+Here code flow in "sd -> github" case. 
+It should be treated mostly as **read-only** (unless you are integrating changes "sd->github").
+

docs/workflow/mapping.md

@@ -0,0 +1,60 @@
+# Mapping
+
+PowerShell/PowerShell utilizes `dotnet cli` project model.
+Source code for a library (executable) is located under `src/<library-name>`.
+I.e. System.Management.Automation.dll sources are located under `src/System.Management.Automation`
+
+In the windows source tree, this files located differently.
+That's why we have `mapping.json` in the root of PowerShell/PowerShell repo.
+This file is a simple json hashtable that describes mapping between files in source depot and GitHub.
+
+Keys are relative file paths from `src\monad` submodule (that has the same layout as admin sd enlistment).
+Values are relative file paths in PowerShell/PowerShell GitHub project.
+
+**Note**: this "src\monad" prefix appears in keys for historical reasons.
+We used to have a submodule at this path.
+If you replace this `src\monad` with path to the **admin** enlistment, you will get the mapping to source depot.
+
+### PowerShellGitHubDev.psm1
+
+Our dev module contains a number of functions to work that can be used to work with this mapping file.
+
+* `Copy-SubmoduleFiles` -- is used for "sd -> github" integration
+* `New-MappingFile` -- was used to create the first version on mapping.json
+* `Send-GitDiffToSd` -- the most interesting function for us: 
+it applies patch from git to **admin** enslistment with respect to `mapping.json`.
+It supports `-WhatIf` switch.
+
+```
+> Send-GitDiffToSd -diffArg1 45555786714d656bd31cbce67dbccb89c433b9cb -diffArg2 45555786714d656bd31cbce67dbccb89c433b9cb~1 -pathToAdmin d:\e\ps_dev\admin 
+> cd d:\e\ps_dev\admin
+> sd online ...
+> # move files to new change list (i.e. with sdb)
+> sd submit -c <n>
+ 
+```
+
+## Updating `mapping.json`
+
+If you are bringing new (that are not yet included) files from source-depot, you need to update `mapping.json` to include them.
+This way, we can keep track of changes and have ability to integrate changes back to Source Depot.
+We will use term **integrate** for that kind of new files.
+
+* Use `source-depot` branch to initially add files.
+
+* Make a separate commit with update for `mapping.json`. Separate commit will help to manage this change in other branches.
+
+* You can use `Copy-SubmoduleFiles` function to copy files on disk.
+
+* Make a separate commit for integrated files.
+Use `--author="PowerShell Team <PowerShellTeam@hotmail.com>"` switch to indicate that it's a collective work.
+
+```
+git commit --author="PowerShell Team <PowerShellTeam@hotmail.com>"
+```
+
+* Merge changes to `master`
+
+Use this approach for **test files** as well.
+You can add them under `test` directory and include in CI test run, but keep the notion of integration in `mapping.json`.
+ 

docs/workflow/resources.md

@@ -0,0 +1,31 @@
+# Resources
+
+Resources are `.resx` files with string values that we use for error messages and such.
+They live in `src\<project>\resources` folders.
+
+At the moment `dotnet cli` doesn't support generating C# bindings (strongly typed resource files).
+
+We are using `src\windows-build\gen` folder in [src\windows-build](https://github.com/PowerShell/psl-windows-build) 
+with pre-generated `.cs` files to work-around it.
+See [issue 756](https://github.com/PowerShell/PowerShell/issues/746) for details.
+
+## Editing resx files
+
+**Don't edit** resx files from Visual Studio. 
+It will try to create `.cs` files for you and you will get whole bunch of hard-to-understand errors.
+
+To edit resource file, use any **plain text editor**. 
+Resource file is a simple xml, and it's easy to edit.
+
+### Updating string
+
+If you just updated the string value, that's all you need to do: no need to re-generate `.cs` files
+
+### Adding or removing string
+
+When you adding or removing string, `.cs` file need to be changed.
+
+1. Run `Start-ResGen` function from `PowerShellGitHubDev.psm1`
+1. Make sure your code is building with newly generated resources (run `Start-PSBuild`).
+1. Go to submodule (`cd src\windows-build`) and perform the [submodule commit dance](../git/committing.md).
+Follow working with [submodule rules](../../CONTRIBUTING.md#submodules)