Merge pull request #779 from PowerShell/andschwa/git-docs
Small updates around Git documenatation
This commit is contained in:
Andy Schwartzmeyer
commit
2adc0d1fcd
|
|
@ -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,15 +20,16 @@ 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?
|
||||
-----------
|
||||
|
||||
- [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
|
||||
--------------
|
||||
|
|
@ -66,12 +63,14 @@ 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.
|
||||
* 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 +86,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
|
||||
------------------------------
|
||||
|
||||
|
|
@ -142,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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -76,8 +77,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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -33,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
|
||||
|
|
@ -44,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*.
|
||||
|
||||
|
|
|
|||
43
docs/git/submodules.md
Normal file
43
docs/git/submodules.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue