Skip to content

Commit 4960e6e

Browse files
andyleejordanandyleejordan
committed
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.
1 parent 62ebca1 commit 4960e6e

4 files changed

Lines changed: 58 additions & 35 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,6 @@ Rules
66

77
**Do not commit code changes to the master branch!**
88

9-
**Read the documentation on [submodules][]!**
10-
11-
**Do not commit submodule updates accidentally!**
12-
139
Don't forget to commit early and often!
1410

1511
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][]:
2420
* The rest should be a wrapped, detailed explanation of the what and why
2521
* The tone should be imperative
2622

27-
[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
2823
[guidelines]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
2924

3025
New to Git?
@@ -71,7 +66,9 @@ Particularly:
7166
* Checkout a new local branch for every change you want to make (bugfix, feature).
7267
* Use `alias/feature-name` pattern.
7368
* Use lowercase-with-dashes for naming.
74-
* Use same branch name in super-project and all [submodules][].
69+
* Use same branch name in superproject and all [submodules][].
70+
71+
[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
7572

7673
Permissions
7774
-----------
@@ -87,29 +84,6 @@ repositories, as you can also just [fork a repo][].
8784

8885
[fork a repo]: https://help.github.com/articles/fork-a-repo/
8986

90-
Rebase and Fast-Forward Merge Pull Requests in Submodules
91-
---------------------------------------------------------
92-
93-
*This is not necessary in the superproject, only submodules!*
94-
95-
Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an
96-
extra merge commit will always be created. This can be especially
97-
annoying when trying to commit updates to submodules. Therefore our
98-
policy is to merge using the Git CLI after approval, with a rebase
99-
onto master to enable a fast-forward merge.
100-
101-
Submodules
102-
----------
103-
104-
This repository is a superproject with a half-dozen [submodules][].
105-
**DO NOT** commit updates unless absolutely necessary. When submodules
106-
must be updated, a separate Pull Request must be submitted, reviewed,
107-
and merged before updating the superproject. When committing submodule
108-
updates, ensure no other changes are in the same commit. Submodule
109-
bumps may be included in feature branches for ease of work, but the
110-
update must be independently approved before merging into master.
111-
112-
11387
Recommended Git configurations
11488
------------------------------
11589

‎docs/git/basics.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,8 @@ git fetch --all -p
7676
# you should call this command ONLY from master branch
7777
git pull origin master
7878

79-
# update submodules
80-
git submodule update --recursive
79+
# update submodules: this checks the submodules out to the commit recorded in the superproject
80+
git submodule update
8181
```
8282

8383
Then switch to your branch and do rebase

‎docs/git/committing.md‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
1-
#Commit Dance
1+
Commit Dance
2+
============
23

3-
**Update:** commit dance became much simpler after [removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656).
4-
Meahwhile, there are still few submodules. If you need to touch their content, this doc provides the overview of the process.
5-
Remember that it's written against `src/monad` submodule, which doesn't exist anymore.
4+
**Update:** commit dance became much simpler after
5+
[removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656).
6+
Thus, this really only applies to `src/windows-build` and
7+
`src/Modules/Pester`. If you need to touch their content, this doc
8+
provides the overview of the process. Remember that it's written
9+
against `src/monad` submodule, which doesn't exist anymore.
10+
11+
Also see the [submodules documentation](./submodules.md).
612

713
Sometimes, you need to do the work in a submodule (i.e. you added a new string in `.resx` file).
814
The submodule has a relationship to the SuperProject (PowerShell), but in order to be sure that CI is

‎docs/git/submodules.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
Submodules
2+
==========
3+
4+
While most developers will not have to deal with submodules on a
5+
regular basis, those who do should read this information. The
6+
submodules currently in this project are:
7+
8+
- `src/Modules/Pester`: The Pester testing framework for PowerShell
9+
10+
- `src/libpsl-native/test/googletest`: The GoogleTest framework for
11+
Linux native code
12+
13+
- `src/windows-build`: Collection of pre-generated artifacts required
14+
until .NET CLI deprecates them (C# resource bindings) and NuGet
15+
packages that will soon be moved to a MyGet feed
16+
17+
- `src/omi`: The Open Management Infrastructure project for PSRP on
18+
Linux (to be removed)
19+
20+
- `src/omi-provider`: The OMI provider for PSRP on Linux (to be
21+
removed)
22+
23+
[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
24+
25+
Rebase and Fast-Forward Merge Pull Requests in Submodules
26+
=========================================================
27+
28+
*This is not necessary in the superproject, only submodules!*
29+
30+
**DO NOT** commit updates unless absolutely necessary. When submodules
31+
must be updated, a separate Pull Request must be submitted, reviewed,
32+
and merged before updating the superproject.
33+
34+
Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an
35+
extra merge commit will always be created. This is especially annoying
36+
when trying to commit updates to submodules. Therefore our policy is
37+
to merge using the Git CLI after approval, with a rebase onto master
38+
to enable a fast-forward merge.
39+
40+
When committing submodule updates, ensure no other changes are in the
41+
same commit. Submodule bumps may be included in feature branches for
42+
ease of work, but the update must be independently approved before
43+
merging into master.

0 commit comments

Comments
 (0)