Browse Source

Add a section on rebashing and squashing

master
Peter J. Jones 2 years ago
parent
commit
10b843ad21
Signed by: Peter Jones <pjones@devalot.com> GPG Key ID: 9DAFAA8D01941E49
1 changed files with 75 additions and 0 deletions
  1. 75
    0
      CONTRIBUTING.md

+ 75
- 0
CONTRIBUTING.md View File

@@ -59,6 +59,81 @@ Here are some tips for getting your changes merged into xmonad:
59 59
     repository.  Include a new configuration file that shows off your
60 60
     changes if possible by creating a PR on that repository as well.
61 61
 
62
+  * Make sure you read the section on rebasing and squashing commits
63
+    below.
64
+
65
+## Rebasing and Squashing Commits
66
+
67
+Under no circumstances should you ever merge the master branch into
68
+your feature branch.  This makes it nearly impossible to review your
69
+changes and we *will not accept your PR* if you do this.
70
+
71
+Instead of merging you should rebase your changes on top of the master
72
+branch.  If a core team member asks you to "rebase your changes" this
73
+is what they are talking about.
74
+
75
+It's also helpful to squash all of your commits so that your pull
76
+request only contains a single commit.  Again, this makes it easier to
77
+review your changes and identify the changes later on in the Git
78
+history.
79
+
80
+### How to Rebase Your Changes
81
+
82
+The goal of rebasing is to bring recent changes from the master branch
83
+into your feature branch.  This often helps resolve conflicts where
84
+you have changed a file that also changed in a recently merged pull
85
+request (i.e. the `CHANGES.md` file).  Here is how you do that.
86
+
87
+  1. Make sure that you have a `git remote` configured for the main
88
+     repository.  I like to call this remote `upstream`:
89
+
90
+        $ git remote add upstream https://github.com/xmonad/xmonad-contrib.git
91
+
92
+  2. Pull from upstream and rewrite your changes on top of master.  For
93
+     this to work you should not have any modified files in your
94
+     working directory.  Run these commands from within your feature
95
+     branch (the branch you are asking to be merged):
96
+
97
+        $ git fetch --all
98
+        $ git pull --rebase upstream master
99
+
100
+  3. If the rebase was successful you can now push your feature branch
101
+     back to GitHub.  You need to force the push since your commits
102
+     have been rewritten and have new IDs:
103
+
104
+        $ git push --force-with-lease
105
+
106
+  4. Your pull request should now be conflict-free and only contain the
107
+     changes that you actually made.
108
+
109
+### How to Squash Commits
110
+
111
+The goal of squashing commits is to produce a clean Git history where
112
+each pull request contains just one commit.
113
+
114
+  1. Use `git log` to see how many commits you are including in your
115
+     pull request.  (If you've already submitted your pull request you
116
+     can see this in the GitHub interface.)
117
+
118
+  2. Rebase all of those commits into a single commit.  Assuming you
119
+     want to squash the last four (4) commits into a single commit:
120
+
121
+        $ git rebase -i HEAD~4
122
+
123
+  3. Git will open your editor and display the commits you are
124
+     rebasing with the word "pick" in front of them.
125
+
126
+  4. Leave the first listed commit as "pick" and change the remaining
127
+     commits from "pick" to "squash".
128
+
129
+  5. Save the file and exit your editor.  Git will create a new commit
130
+     and open your editor so you can modify the commit message.
131
+
132
+  6. If everything was successful you can push your changed history
133
+     back up to GitHub:
134
+
135
+        $ git push --force-with-lease
136
+
62 137
 [xmonad]: https://github.com/xmonad/xmonad
63 138
 [xmonad-contrib]: https://github.com/xmonad/xmonad-contrib
64 139
 [xmonad-testing]: https://github.com/xmonad/xmonad-testing

Loading…
Cancel
Save