diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63d74f905a..9112b5e615 100644 --- a/CONTRIBUTING.md +++ b/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. + diff --git a/README.md b/README.md index 6a4731c7fa..c0e7396183 100644 --- a/README.md +++ b/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 -------------- diff --git a/docs/git/committing.md b/docs/git/committing.md index 3625801aa6..305e64484a 100644 --- a/docs/git/committing.md +++ b/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. diff --git a/docs/workflow/branches.md b/docs/workflow/branches.md new file mode 100644 index 0000000000..8144df2bc7 --- /dev/null +++ b/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"). + diff --git a/docs/workflow/mapping.md b/docs/workflow/mapping.md new file mode 100644 index 0000000000..98bf4bd245 --- /dev/null +++ b/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/`. +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 + +``` + +## 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 "` switch to indicate that it's a collective work. + +``` +git commit --author="PowerShell Team " +``` + +* 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`. + diff --git a/docs/workflow/resources.md b/docs/workflow/resources.md new file mode 100644 index 0000000000..64e93b9e42 --- /dev/null +++ b/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\\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)