PowerShell/docs/workflow/mapping.md

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

* 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>"
```

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