You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: code-style/git/README.md
+60-44Lines changed: 60 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,49 +2,52 @@
2
2
3
3
4
4
5
-
We use Git version control for all of our projects at [Sparkbox][]. We host
5
+
We use Git version control for all of our projects at [Sparkbox]. We host
6
6
our code on GitHub. Large features get their own branch and are merged with a
7
7
pull request by a person _other_ than yourself.
8
8
9
-
10
9
## The Sparkbox Git Flow
11
10
12
11
Every place you work will have a different Git flow. At Sparkbox the Git flow is as follows:
13
12
14
-
1.[Create a branch][] off of master to fix an issue assigned to you.
13
+
1.[Create a branch] off of master to fix an issue assigned to you.
14
+
15
+
1. Push this branch up to GitHub, and create a [pull request] when you are ready.
15
16
16
-
1. Push this branch up to GitHub, and create a pull request when you are ready.
17
+
- Protip: Sometimes we create pull requests early as a place to collaborate on a solution. Consider opening a [Draft PR] to prevent your PR from accidentally being merged. You may also consider labeling these PRs as "DO NOT MERGE" or "WIP".
17
18
18
-
- Protip: Sometimes we create pull requests early as a place to collaborate on a solution. Consider labeling these as `DO NOT MERGE` or `WIP`. You might also utilize [Draft PRs][].
19
+
1. To make the pull request process more consistent, your project might include a [pull request template]. An [example PR template] is included in the Standard as a starting point. There is also an [example issue template].
19
20
20
-
1.To make the pull request process more consistent, your project might include a [pull request template][]. An [example PR template][] is included in the Standard as a starting point. There is also an [example issue template][].
21
+
1.Assign a reviewer to your pull request. Leave some nice documentation or even a [screencast](https://viewedit.com/) to give your reviewer a bit more background about the code you wrote in this pull request (include information about any interesting or difficult code, and where the reviewer can see the code that you are referencing). It can also be very helpful to include some instructions in the description of your pull request about how to test the changes you've made to the code.
21
22
22
-
1. Assign a reviewer to your pull request. Leave some nice documentation or even a [screencast](https://viewedit.com/) to give your reviewer a bit more background about the code you wrote in this pull request (include information about any interesting or difficult code, and where the reviewer can see the code that you are referencing). It can also be very helpful to include some instructions in the description of your pull request about how to test the changes you've made to the code.
23
+
- Protip: Use interactive rebasing to [curate your commit history] before requesting a review. Squashing, reordering or rewording your commits will help [onboard the reviewer to your pull request][foundry_curated_commits].
23
24
24
25
1. The reviewer might ask you to [rebase off master](#Rebasing-a-Branch-onto-the-Master-Branch) if the branch has gotten behind master.
25
26
26
27
1. Your reviewer will either approve or request changes on your pull request.
27
-
- If they request changes, please implement or further discuss their comments with them.
28
+
29
+
- If they request changes, please implement or further discuss their comments with them.
30
+
- If no more changes to your code are needed, this will likely be a good time to ["squash your commits"][curate your commit history] before the reviewer merges them back into the main branch.
28
31
29
32
1. If your reviewer approves your pull request, they will fast-forward merge your branch into master using the CLI.
30
33
31
-
```cli
32
-
git merge --ff-only <branch-name>
33
-
```
34
+
```cli
35
+
git merge --ff-only <branch-name>
36
+
```
34
37
35
38
1. The reviewer will then let you know your changes have been merged so you can move your Jira card.
36
39
37
40
1. Once the PR is merged, the reviewer deletes the branch.
38
41
39
-
40
42
## Naming Branches
41
43
42
44
Consistent branch naming can help with team communication. A branch name might be the first peek a reviewer gets at what the work is related to. We use types (feat, fix, docs, etc.) to group our branch names so that we know what part of our workflow the branch belongs to, and a brief subject to describe what the branch does.
43
45
44
46
`feat--onUrlChange-event`
45
47
46
48
### Allowed Values for Types
47
-
There are several types allowed to prefix branches and commits.
49
+
50
+
Sparkbox follows the [Conventional Commits] specification. There are several types allowed to prefix branches and commits.
48
51
49
52
-**feat** (new feature)
50
53
-**fix** (bug fix)
@@ -65,6 +68,7 @@ Subjects need to be short, but descriptive. Multi-word subjects are separated by
65
68
### Branches with Multi-type Commits
66
69
67
70
Even though our branches tend to be named similarly to our commit style, it's ok if you're working on a bug fix branch `fix--` and include other types of commits. For example, maybe you have a branch named `fix--unit-tests-IE9`, but you've done some `refactor`ing and made some `style` adjustments. Your commit messages for the branch might include:
71
+
68
72
```
69
73
fix: unit tests for IE9
70
74
@@ -81,15 +85,14 @@ It's totally ok to include all of those commits on your bug fix branch. You migh
81
85
82
86
If you identify any of these concerns in your branch, it's worth exploring whether all the work you're doing should be reviewed together. Sometimes work does need to be all together, but in a lot of cases we can [break up that work](https://www.netlify.com/blog/2020/03/31/how-to-scope-down-prs/) to make it easier for our code reviewers to provide a thorough review.
83
87
84
-
85
88
## The Art of the Commit Message
86
89
87
90
We use a strict writing style for all of our commit messages. The style we use helps ensure that our commits stay small and are easy to browse.
88
91
89
-
_Never forget all this juicy knowledge! Set your commit message template to
92
+
_Never forget all this juicy knowledge! Set your commit message template to
90
93
[this wonderful example](./.gitmessage), by running:_
@@ -105,10 +108,11 @@ _Never forget all this juicy knowledge! Set your commit message template to
105
108
106
109
The subject consists of the `<type>` and the `<subject>`.
107
110
108
-
> Protip: Find yourself with an _and_ in that commit title? Consider breaking
109
-
> the commit down. `git commit -p` is your friend!
111
+
> Protip: Find yourself with an _and_ in that commit title? Consider breaking
112
+
> the commit down. `git commit -p` is your friend!
110
113
111
114
#### Allowed Types
115
+
112
116
Find the [allowed types above](#Allowed-Values-for-Types).
113
117
114
118
-**feat**
@@ -121,25 +125,26 @@ _changes_.
121
125
122
126
### Funtip
123
127
124
-
Work hard, play hard! Consider prefixing your commit messages with a relevant emoji.
125
-
126
-
* :art: `:art:` when improving the format/structure of the code
127
-
* :racehorse: `:racehorse:` when improving performance
128
-
* :non-potable_water: `:non-potable_water:` when plugging memory leaks
129
-
* :memo: `:memo:` when writing docs
130
-
* :penguin: `:penguin:` when fixing something on Linux
131
-
* :apple: `:apple:` when fixing something on macOS
132
-
* :checkered_flag: `:checkered_flag:` when fixing something on Windows
133
-
* :bug: `:bug:` when fixing a bug
134
-
* :fire: `:fire:` when removing code or files
135
-
* :green_heart: `:green_heart:` when fixing the CI build
136
-
* :white_check_mark: `:white_check_mark:` when adding tests
137
-
* :lock: `:lock:` when dealing with security
138
-
* :arrow_up: `:arrow_up:` when upgrading dependencies
139
-
* :arrow_down: `:arrow_down:` when downgrading dependencies
140
-
* :shirt: `:shirt:` when removing linter warnings
128
+
Work hard, play hard! Consider prefixing your commit messages with a relevant emoji.
129
+
130
+
-:art:`:art:` when improving the format/structure of the code
131
+
-:racehorse:`:racehorse:` when improving performance
132
+
-:non-potable_water:`:non-potable_water:` when plugging memory leaks
133
+
-:memo:`:memo:` when writing docs
134
+
-:penguin:`:penguin:` when fixing something on Linux
135
+
-:apple:`:apple:` when fixing something on macOS
136
+
-:checkered_flag:`:checkered_flag:` when fixing something on Windows
137
+
-:bug:`:bug:` when fixing a bug
138
+
-:fire:`:fire:` when removing code or files
139
+
-:green_heart:`:green_heart:` when fixing the CI build
140
+
-:white_check_mark:`:white_check_mark:` when adding tests
141
+
-:lock:`:lock:` when dealing with security
142
+
-:arrow_up:`:arrow_up:` when upgrading dependencies
143
+
-:arrow_down:`:arrow_down:` when downgrading dependencies
144
+
-:shirt:`:shirt:` when removing linter warnings
141
145
142
146
Example:
147
+
143
148
```
144
149
:fire: refactor: removed unused container elements
145
150
```
@@ -150,7 +155,7 @@ The body of the commit message should use a style similar to the one proposed
150
155
in this [article by tpope][tpope]. The body, just like the subject, should use
151
156
an imperative tone.
152
157
153
-
Another nice thing you can do in the body of your commit is to state what the `issue` is that you worked on, and what your code changes and `fix` entailed. The `fix`, or the _why_ of your code is really interesting, as well as important, and helps others understand the solution you chose.
158
+
Another nice thing you can do in the body of your commit is to state what the `issue` is that you worked on, and what your code changes and `fix` entailed. The `fix`, or the _why_ of your code is really interesting, as well as important, and helps others understand the solution you chose.
154
159
155
160
Example:
156
161
@@ -270,16 +275,23 @@ scope: {
270
275
The removed `inject` wasn't generally useful for directives so there should be no code using it.
271
276
```
272
277
278
+
## Curating Your Commit History
279
+
280
+
There are a number of reasons why you may want to "rewrite" the history of your work.
281
+
282
+
**Before requesting a review of your work**, you may want to clean up your commit history to better "tell the story" of what you did. Using interactive rebasing, you can curate your commit history to combine (squash or fixup), reorder, or reword your commits to better [onboard the reviewer to your pull request][foundry_curated_commits].
283
+
284
+
**After your work has been approved**, there is no longer a need to preserve every step of your process for the record. Of course, your code changes must be preserved, but when merging them back into the main branch it's more important to communicate the high-level reasoning for the overall PR. This makes the flow of changes to the main branch more easily digestible for later viewers. Once again, you will use interactive rebasing to combine all of your changes into 1 or 2 commits, communicating notable changes in the body of the commit message. This is often referred to as "squashing your commits."
273
285
274
286
## Rebasing a Branch onto the Master Branch
275
287
276
-
Rather than merging commits from another branch into the master branch, Sparkbox prefers to rebase commits on top of the master branch. One of the best reasons for why Sparkbox does this is that rebasing creates a very clear and clean commit history, free of "Merged branch `other-branch`" commits (which can muddy up the history). To learn a bit more about why rebasing is preferred over merging at Sparkbox, read Ryan Cromwell's post on [Taking Control of Your Commit History](https://seesparkbox.com/foundry/take_control_of_your_commit_history). Additionally, here is a diagram that depicts the differences between merging and rebasing:
288
+
Rather than merging commits from another branch into the master branch, Sparkbox prefers to rebase commits on top of the master branch. One of the best reasons for why Sparkbox does this is that rebasing creates a very clear and clean commit history, free of "Merged branch `other-branch`" commits (which can muddy up the history). To learn a bit more about why rebasing is preferred over merging at Sparkbox, read Ryan Cromwell's post on [Taking Control of Your Commit History]. Additionally, here is a diagram that depicts the differences between merging and rebasing:
277
289
278
290
279
291
280
292
281
293
282
-
For the purposes of this example explaining rebasing, let's say that the branch you need to rebase is called `chore-teaching-example`, and that this branch has gone through all of the Git flow discussed above for a pull request. Follow these next steps to rebase a branch onto master:
294
+
For the purposes of this example explaining rebasing, let's say that the branch you need to rebase is called `chore-teaching-example`, and that this branch has gone through all of the Git flow discussed above for a pull request. Follow these next steps to rebase a branch onto master:
283
295
284
296
1. Open your terminal and checkout the branch to be rebased: `git checkout chore-teaching-example`.
285
297
@@ -291,10 +303,11 @@ For the purposes of this example explaining rebasing, let's say that the branch
291
303
292
304
1. If your branch is behind the master branch's commits, run `git rebase origin/master`. You can also run `git rebase origin/master -i` which will allow you to _interactively_ (that's where the `-i` comes from) select which commits you want to be added to the master branch, and also permit you to squash commits and reword commit messages. If your branch is already rebased, you can skip to step 7.
293
305
294
-
- Upon rebasing, you may run into merge conflicts. Follow the helpful instructions offered by Git in your terminal, and fix all of the merge conflicts until you have rebased your branch on top of master.
306
+
- Upon rebasing, you may run into merge conflicts. Follow the helpful instructions offered by Git in your terminal, and fix all of the merge conflicts until you have rebased your branch on top of master.
295
307
296
308
1. After rebasing your branch on top of the master branch, you'll need to force push these changes to your GitHub version of the branch. Run `git push origin chore-teaching-example --force-with-lease`.
297
-
- Make sure any and all tests that run when you push your branch to GitHub succeed (this may include Circle CI, or Code Climate tests).
309
+
310
+
- Make sure any and all tests that run when you push your branch to GitHub succeed (this may include Circle CI, or Code Climate tests).
298
311
299
312
1. When you have made sure that your newly rebased branch did not break any tests on GitHub, you can checkout the master branch in your terminal by running: `git checkout master` and `git pull origin master` to grab any new changes to the master branch that you might not have.
300
313
@@ -304,8 +317,8 @@ For the purposes of this example explaining rebasing, let's say that the branch
304
317
305
318
Voila! You're done. You've successfully rebased a branch onto the master branch!
306
319
307
-
308
320
## Additional Resources
321
+
309
322
-[GitHub Pull Requests for Everyone](https://seesparkbox.com/foundry/github_pull_requests_for_everyone) by Catherine Meade
310
323
-[Give Better Pull Requests With Screencasts](https://seesparkbox.com/foundry/give_better_pull_requests_with_screencasts) by Ethan Muller
311
324
-[Stop Giving Depressing Code Reviews](https://seesparkbox.com/foundry/stop_giving_depressing_code_reviews) by Bryan Braun
@@ -319,11 +332,14 @@ Voila! You're done. You've successfully rebased a branch onto the master branch!
0 commit comments