maxmustermann/PowerShell
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
PowerShell/docs/dev-process/map-json-files.md
Travis Plunk 68bcd4b528 Removed trailing whitespace (#3485)
2017-04-11 09:44:43 -07:00

3 KiB
Raw Blame History

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, the files are organized differently. That's why we use map.json files in src/<library-name>. This file is a simple json hashtable that describes mapping between files in source depot and GitHub.

  • Keys are relative file paths from psl-monad (that has the same layout as admin sd enlistment).
  • Values are file paths, relative to the corresponding map.json folder.

Example

There is an entry

"monad/src/engine/COM/ComMethod.cs":  "engine/COM/ComMethod.cs",

in .\src\System.Management.Automation\map.json. It tells us that file ComMethod.cs located at monad/src/engine/COM/ComMethod.cs in psl-monad (and sd enlistment) is mapped to src/System.Management.Automation/engine/COM/ComMethod.cs in PowerShell/PowerShell.

build.psm1

Our dev module contains a number of functions that can be used to work with this mapping file.

  • Copy-MappedFiles -- copies files from psl-monad into PowerShell/PowerShell. Used for "sd -> github" integration.
  • Send-GitDiffToSd -- applies patch from git to admin enlistment with respect to all map.json files. It supports -WhatIf switch.
> Send-GitDiffToSd -diffArg1 32b90c048aa0c5bc8e67f96a98ea01c728c4a5be~1 -diffArg2 32b90c048aa0c5bc8e67f96a98ea01c728c4a5be -AdminRoot 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 map.json

If you are bringing new (that are not yet included) files from source-depot, you need to update map.json in the corresponding folder to include them.

This way, we can keep track of changes and have ability to integrate changes back to Source Depot.

Use this approach for any files from source-depot (including test files)

Creating map.json

If you are creating new folder for that, create map.json with all mapped files in it.

  • Make a separate commit with update/creation for map.json. Separate commit will help to manage this change.
> mkdir .\src\My.New.Module
> notepad .\src\My.New.Module\map.json
# add mappings into the file
  • Find current baseline SD change-list in tags:
> git tag
SD-692351
SD-693793
SD/688741
SD/692351
SD/693793
SD/695331
SD/700586
SD/704605
SD/706766
SD/709766  <--- the last changelist
v0.1.0
v0.2.0
v0.3.0
v0.4.0
  • Find corresponding commit in psl-monad and check it out.
> Push-Location ..\psl-monad
> git checkout 85e2ecd
> Pop-Location
  • Use Copy-MappedFiles function to copy files on disk.
> Copy-MappedFiles -PslMonadRoot ..\psl-monad -Path .\src\My.New.Module
  • Make a separate commit with mapped 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>"