Skip to content

Commit be4d4de

Browse files
kgrytekgryte
committed
Update Git style guide
1 parent 4c9c080 commit be4d4de

File tree

1 file changed

+210
-13
lines changed

1 file changed

+210
-13
lines changed

‎docs/style-guides/git/README.md‎

Lines changed: 210 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,30 +3,227 @@
33
> Style guide for [Git][git].
44
55

6-
TODO: add branching policy
7-
TODO: add note about submitting PR against `develop`
8-
TODO: add `rebase` note
9-
TODO: add code review note
10-
TODO: add examples and model after JS guide
11-
6+
## Commits
127

138
* All commits should follow the [seven rules][git-seven-rules] of a [Git][git] commit message:
149

15-
- Use the [imperative mood][imperative-mood] in the [Git][git] commit subject line.
16-
- Capitalize the first word of the subject line.
17-
- Do __not__ end the subject line with a period.
18-
- Separate the subject line from the body with a blank line.
19-
- Try to limit the subject line to `50` characters.
20-
- Use the body to explain the *what* and *why*, and not the *how*.
21-
- Try to wrap the body at `72` characters.
10+
1. Use the [imperative mood][imperative-mood] in the [Git][git] commit subject line.
11+
12+
``` text
13+
# Do not...
14+
Fixed Markdown lint errors
15+
```
16+
17+
``` text
18+
# Do...
19+
Fix Markdown lint errors
20+
```
21+
22+
1. Capitalize the first word of the subject line.
23+
24+
``` text
25+
# Do not...
26+
fix Markdown lint errors
27+
```
28+
29+
``` text
30+
# Do...
31+
Fix Markdown lint errors
32+
```
33+
34+
1. Do __not__ end the subject line with a period.
35+
36+
``` text
37+
# Do not...
38+
Fix Markdown lint errors.
39+
```
40+
41+
``` text
42+
# Do...
43+
Fix Markdown lint errors
44+
```
45+
46+
1. Separate the subject line from the body with a blank line.
47+
48+
``` text
49+
# Do not...
50+
This is the subject line
51+
This is the body body body body body body body body body body body body
52+
body body body body body body body body body body body body body body
53+
```
54+
55+
``` text
56+
# Do...
57+
This is the subject line
58+
59+
This is the body body body body body body body body body body body body
60+
body body body body body body body body body body body body body body
61+
```
62+
63+
1. Try to limit the subject line to `50` characters.
64+
65+
``` text
66+
# Do not...
67+
This is the subject line line line line line line line line line line line line line line
68+
```
69+
70+
``` text
71+
# Do...
72+
This is the subject line
73+
```
74+
75+
1. Use the body to explain the *what* and *why*, and not the *how*.
76+
77+
``` text
78+
# Do not...
79+
Change Markdown heading style
80+
81+
Update various Markdown files to stop lint errors. Change the heading
82+
style from `===` to `#`.
83+
```
84+
85+
``` text
86+
# Do...
87+
Change Markdown heading style
88+
89+
Change the heading style to ensure consistency with `remark` output.
90+
This ensures that all Markdown files are all of the same style, thus
91+
reducing the number of edge cases Markdown parsers need to consider.
92+
```
93+
94+
1. Try to wrap the body at `72` characters.
95+
96+
``` text
97+
# Do not...
98+
This is the subject line
99+
100+
This is the body body body body body body body body body body body body body body body body body body body body body body body body body body
101+
```
102+
103+
``` text
104+
# Do...
105+
This is the subject line
106+
107+
This is the body body body body body body body body body body body body
108+
body body body body body body body body body body body body body body
109+
```
110+
111+
---
112+
113+
## Branching
114+
115+
This project follows the branching model articulated in ["A successful Git branching model"][git-flow].
116+
117+
### Master
118+
119+
* The `master` branch is __protected__.
120+
121+
* The `master` branch should __only__ include source code which is stable, tested, and peer reviewed. In short, the source code should __always__ reflect a "production-ready" state.
122+
123+
* Each commit on the `master` branch should have an associated tag.
124+
125+
``` bash
126+
$ git tag -a 2.0.0
127+
$ git push origin --tags
128+
```
129+
130+
131+
### Develop
132+
133+
* The `develop` branch is __protected__.
134+
* The `develop` branch should __only__ include code which is tested, peer reviewed, and passes continuous integration tests.
135+
* The source code should __always__ reflect the latest development changes for the __next__ release.
136+
137+
138+
### Features
139+
140+
* A feature branch should use the naming convention: `feature/<name>`.
141+
142+
* A feature branch should branch from the `develop` branch.
143+
144+
``` bash
145+
$ git checkout -b feature/<name> develop
146+
```
147+
148+
* Once a feature is complete, [squash][git-squash] commits into a single commit.
149+
150+
* In order to merge a feature branch into the `develop` branch, submit a pull request against the `develop` branch.
151+
152+
* Before merging a feature branch into the `develop` branch, the source code __must__ be peer reviewed.
153+
154+
155+
### Releases
156+
157+
* A release branch should use the naming convention: `release-<major>.<minor>.<patch>`.
158+
159+
* The release number should follow [semantic versioning][semver].
160+
161+
* A release branch should branch from the `develop` branch.
162+
163+
``` bash
164+
$ git checkout -b release-2.0.0 develop
165+
```
166+
167+
* Active development should __not__ occur on a release branch. A release branch is a preparation branch (vetting, testing, updating meta data, et cetera) before merging into the `master` branch.
168+
169+
* Once a release branch is complete, submit a pull request against the `master` branch.
170+
171+
* Before merging the release branch into the `master` branch, the changes __must__ be peer reviewed.
172+
173+
* Once merged into `master`, submit a pull request against the `develop` branch to retain the changes made in the release branch.
174+
175+
176+
### Hotfixes
177+
178+
* A hotfix branch should use the naming convention: `hotfix/<name>`.
179+
180+
* The purpose of a hotfix branch is to immediately patch a bug on the `master` branch. Accordingly, a hotfix branch should branch from the `master` branch.
181+
182+
``` bash
183+
$ git checkout -b hotfix/<name> master
184+
```
185+
186+
* The hotfix branch should increment the ["patch"][semver] version number.
187+
188+
* Once a hotfix is complete, [squash][git-squash] commits into a single commit.
189+
190+
* Submit a pull request against the `master` branch.
191+
192+
* Before merging a hotfix branch into the `master` branch, the changes __must__ pass continuous integration tests and be peer reviewed.
193+
194+
* Once merged into `master`, if a release branch currently exists, submit a pull request against the `release` branch. Otherwise, submit a pull request against the `develop` branch. By merging a hotfix into a release branch, the hotfix changes should be propagated to the `develop` branch upon merging the release branch into the `develop` branch.
195+
196+
197+
---
198+
199+
## Pull Requests
200+
201+
* All feature pull requests should be [rebased][git-rebase] against the latest `develop` branch.
202+
* All feature pull requests should be submitted against the `develop` branch.
203+
204+
205+
---
206+
207+
## License
208+
209+
This document may be reused under a [Creative Commons Attribution-ShareAlike License][license].
22210

23211

24212
<section class="links">
25213

26214
[git]: https://git-scm.com/
215+
[git-rebase]: https://git-scm.com/docs/git-rebase
216+
[git-squash]: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits
217+
27218
[git-seven-rules]: http://chris.beams.io/posts/git-commit/
28219
[imperative-mood]: https://en.wikipedia.org/wiki/Imperative_mood
29220

221+
[git-flow]: http://nvie.com/posts/a-successful-git-branching-model/
222+
223+
[semantic-versioning]: http://semver.org/
224+
225+
[license]: https://creativecommons.org/licenses/by-sa/4.0/
226+
30227
</section>
31228

32229
<!-- /.links -->

0 commit comments

Comments
 (0)