From 4960e6e39c9f24225de069da428c946e19b224c0 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Thu, 7 Apr 2016 13:46:00 -0700 Subject: [PATCH 1/3] Refactor submodule documentation Moved notes on submodules out of contributing guidelines and into `docs/git/submodules.md` as most developers will touch them infrequently now. --- CONTRIBUTING.md | 32 +++---------------------------- docs/git/basics.md | 4 ++-- docs/git/committing.md | 14 ++++++++++---- docs/git/submodules.md | 43 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 58 insertions(+), 35 deletions(-) create mode 100644 docs/git/submodules.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9112b5e61..9f2af30e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,10 +6,6 @@ Rules **Do not commit code changes to the master branch!** -**Read the documentation on [submodules][]!** - -**Do not commit submodule updates accidentally!** - Don't forget to commit early and often! Please add `[ci skip]` to commits that should be ignored by the CI systems @@ -24,7 +20,6 @@ Write *good* commit messages. Follow Tim Pope's [guidelines][]: * The rest should be a wrapped, detailed explanation of the what and why * The tone should be imperative -[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules [guidelines]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html New to Git? @@ -71,7 +66,9 @@ Particularly: * 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 super-project and all [submodules][]. +* Use same branch name in superproject and all [submodules][]. + +[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules Permissions ----------- @@ -87,29 +84,6 @@ repositories, as you can also just [fork a repo][]. [fork a repo]: https://help.github.com/articles/fork-a-repo/ -Rebase and Fast-Forward Merge Pull Requests in Submodules ---------------------------------------------------------- - -*This is not necessary in the superproject, only submodules!* - -Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an -extra merge commit will always be created. This can be especially -annoying when trying to commit updates to submodules. Therefore our -policy is to merge using the Git CLI after approval, with a rebase -onto master to enable a fast-forward merge. - -Submodules ----------- - -This repository is a superproject with a half-dozen [submodules][]. -**DO NOT** commit updates unless absolutely necessary. When submodules -must be updated, a separate Pull Request must be submitted, reviewed, -and merged before updating the superproject. When committing submodule -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 ------------------------------ diff --git a/docs/git/basics.md b/docs/git/basics.md index 0bb36b073..727958ea9 100644 --- a/docs/git/basics.md +++ b/docs/git/basics.md @@ -76,8 +76,8 @@ git fetch --all -p # you should call this command ONLY from master branch git pull origin master -# update submodules -git submodule update --recursive +# 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 diff --git a/docs/git/committing.md b/docs/git/committing.md index 305e64484..555cff5bd 100644 --- a/docs/git/committing.md +++ b/docs/git/committing.md @@ -1,8 +1,14 @@ -#Commit Dance +Commit Dance +============ -**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. +**Update:** commit dance became much simpler after +[removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656). +Thus, this really only applies to `src/windows-build` and +`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 diff --git a/docs/git/submodules.md b/docs/git/submodules.md new file mode 100644 index 000000000..462602026 --- /dev/null +++ b/docs/git/submodules.md @@ -0,0 +1,43 @@ +Submodules +========== + +While most developers will not have to deal with submodules on a +regular basis, those who do should read this information. The +submodules currently in this project are: + +- `src/Modules/Pester`: The Pester testing framework for PowerShell + +- `src/libpsl-native/test/googletest`: The GoogleTest framework for + Linux native code + +- `src/windows-build`: Collection of pre-generated artifacts required + until .NET CLI deprecates them (C# resource bindings) and NuGet + packages that will soon be moved to a MyGet feed + +- `src/omi`: The Open Management Infrastructure project for PSRP on + Linux (to be removed) + +- `src/omi-provider`: The OMI provider for PSRP on Linux (to be + removed) + +[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules + +Rebase and Fast-Forward Merge Pull Requests in Submodules +========================================================= + +*This is not necessary in the superproject, only submodules!* + +**DO NOT** commit updates unless absolutely necessary. When submodules +must be updated, a separate Pull Request must be submitted, reviewed, +and merged before updating the superproject. + +Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an +extra merge commit will always be created. This is especially annoying +when trying to commit updates to submodules. Therefore our policy is +to merge using the Git CLI after approval, with a rebase onto master +to enable a fast-forward merge. + +When committing submodule 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. From d7f60447ecc79e723a87db1d5fa213f07874625f Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Thu, 7 Apr 2016 13:47:07 -0700 Subject: [PATCH 2/3] Quick markdown cleanups --- CONTRIBUTING.md | 12 +++++++----- docs/git/basics.md | 9 +++++---- docs/git/committing.md | 8 ++++---- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f2af30e0..6ab29d575 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,8 +26,10 @@ New to Git? ----------- - [Git Basics](docs/git/basics.md): install and getting started. -- [Git for sd users](docs/git/source-depot.md): a handy reference document for people familiar with `sd`. -- [Commit process](docs/git/committing.md): step-by-step commit guide with all gory details. +- [Git for sd users](docs/git/source-depot.md): a handy reference + document for people familiar with `sd`. +- [Commit process](docs/git/committing.md): step-by-step commit guide + with all gory details. Authentication -------------- @@ -61,7 +63,7 @@ Particularly: [2 factor authentication]: https://github.com/blog/1614-two-factor-authentication [Branches](docs/workflow/branches.md) --------- +------------------------------------- * Checkout a new local branch for every change you want to make (bugfix, feature). * Use `alias/feature-name` pattern. @@ -116,12 +118,12 @@ 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/docs/git/basics.md b/docs/git/basics.md index 727958ea9..c426cca16 100644 --- a/docs/git/basics.md +++ b/docs/git/basics.md @@ -1,10 +1,11 @@ # Git 101 -We are using git version 2.7.x, but any version should be good. -It's recommended to learn `git` command line tool for full cross-platform expirience. +We are using Git version 2.8.1, 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 referrences to our favorites. +There are (too) many Git tutorials on the internet. Here we post +references to our favorites. ## Install diff --git a/docs/git/committing.md b/docs/git/committing.md index 555cff5bd..f40bc865a 100644 --- a/docs/git/committing.md +++ b/docs/git/committing.md @@ -39,10 +39,11 @@ index 1ba8dd4..ed5d202 160000 * 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 +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 @@ -50,11 +51,10 @@ 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*. - From e97ccc1c5f20c42ecaaf7933d4d94ef46ccb4563 Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Thu, 7 Apr 2016 13:49:19 -0700 Subject: [PATCH 3/3] Refer to contributing guidelines in building documentation For #771. --- docs/building/linux.md | 3 +++ docs/building/windows-core.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/building/linux.md b/docs/building/linux.md index f459c8207..e7476ef04 100644 --- a/docs/building/linux.md +++ b/docs/building/linux.md @@ -58,6 +58,9 @@ uninstall prior any prior versions. Git Setup --------- +Using Git requires it to be setup correctly; refer to the +[Contributing Guidelines](../../CONTRIBUTING.md). + Please clone the superproject (this repo) and initialize a subset of the submodules: diff --git a/docs/building/windows-core.md b/docs/building/windows-core.md index 479d3cf37..386410364 100644 --- a/docs/building/windows-core.md +++ b/docs/building/windows-core.md @@ -46,6 +46,9 @@ CLI can cause odd failures when running. Please check your version. Git Setup --------- +Using Git requires it to be setup correctly; refer to the +[Contributing Guidelines](../../CONTRIBUTING.md). + Please clone the superproject (this repo) and initialize a subset of the submodules: