]>
Commit | Line | Data |
---|---|---|
5de50f26 SK |
1 | Introduction |
2 | ------------ | |
3 | ||
4 | These instructions are wrote to contributors who tend to send lots of | |
5 | changes. The basics from howto-contribute.txt file are assumed to be | |
6 | read and understood by the time this file becomes useful. | |
7 | ||
8 | ||
9 | Setup | |
10 | ----- | |
11 | ||
12 | 1. Find a git server that can be reached from anywhere in internet | |
13 | anonymously. Github is for example a popular choice. | |
14 | ||
3c560686 | 15 | 2. Create your own util-linux contributor repository, and push an upstream |
5de50f26 SK |
16 | clone to there. |
17 | ||
18 | 3. In these instructions the upstream remote repository is called | |
19 | 'origin' and the 'yourgit' is the contributor repo. | |
20 | ||
21 | cd ~/projects | |
22 | git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git | |
23 | cd util-linux | |
24 | git remote add yourgit git@github.com:yourlogin/util-linux.git | |
25 | git push yourgit | |
26 | ||
27 | ||
28 | Branches | |
29 | -------- | |
30 | ||
31 | 1. Use the name of the subsystem, such as blkid, libmount, misc-utils, | |
a7349ee3 | 32 | that is the common thing for changes in the change set. |
5de50f26 SK |
33 | |
34 | 2. If the changes do not have anything in common use some random name, | |
35 | such as YYYY-MM-DD of the first patch in the branch. Name of the branch | |
36 | does not really matter that much, with one exception. | |
37 | ||
38 | 3. Do not use 'master' branch to your contributions. The 'master' branch | |
39 | is needed to stay up to date with upstream. | |
40 | ||
41 | 4. When done push your branch to your remote git server. | |
42 | ||
43 | git checkout master | |
44 | git branch textual | |
45 | # spent here most of the effort | |
ca8a129a | 46 | git push yourgit textual:textual |
5de50f26 SK |
47 | |
48 | 5. Do not worry if you used stupid-and-wrong branch name, it can be fixed | |
49 | before submission. | |
50 | ||
51 | git branch -m stupid-and-wrong brilliant | |
52 | git push yourgit brilliant:brilliant :stupid-and-wrong | |
53 | ||
54 | ||
55 | Stay up to date | |
56 | --------------- | |
57 | ||
58 | 1. Ensure you have the latest from all remote repositories. | |
59 | ||
60 | 2. Merge upstream 'master' branch if needed to your local 'master'. | |
61 | ||
62 | 3. Rebase your working contribution branches. | |
63 | ||
64 | 4. Push the changes to 'yourgit'. | |
65 | ||
66 | git fetch --all | |
67 | git log --graph --decorate --pretty=oneline --abbrev-commit --all | |
68 | ||
69 | 5. If you notice upstream has changed while you were busy with your | |
70 | changes rebase on top of the master, but before that: | |
71 | ||
72 | 6. Push a backup of your branch 'textual' to 'yourgit', then | |
73 | ||
74 | git checkout master | |
75 | git merge origin/master | |
76 | git checkout textual | |
77 | git rebase master | |
78 | ||
79 | If rebase reports conflicts fix the conflicts. In case the rebase | |
80 | conflict is difficult to fix rebase --abort is good option, or recover | |
81 | from 'yourgit', either way there is some serious re-work ahead with the | |
82 | change set. | |
83 | ||
84 | 7. Assuming rebase went fine push the latest to 'yourgit'. | |
85 | ||
86 | git push yourgit master:master | |
87 | git push yourgit --force textual:textual | |
88 | ||
89 | The contributor branch tends to need --force every now and then, don't be | |
90 | afraid using it. | |
91 | ||
92 | 8. Push error with master branch | |
93 | ||
94 | If 'master' needs --force then something is really messed up. In that | |
95 | case it is probably the wise to abandon(*) local clone, and start all | |
96 | over from cloning upstream again. Once the upstream is cloned add again | |
97 | 'yourgit' remote and | |
98 | ||
99 | git push --mirror yourgit | |
100 | ||
101 | But be WARNED. The --mirror will nuke all of your stuff had in | |
102 | 'yourgit', that can cause data loss. (*)So don't remove the local clone, | |
103 | just move the directory to broken repos area. | |
104 | ||
105 | ||
106 | Sending pull request | |
107 | -------------------- | |
108 | ||
109 | 1. When you are happy with your changes sleep over night. This is not a | |
110 | speed competition, and for some reason looking the changes the next day | |
111 | often makes one to realize how things could be improved. The best this | |
112 | way you avoid changing the changes (that is always confusing). | |
113 | ||
114 | 2. Check the next day the changes compile without errors or warnings, and | |
115 | that regression tests run fine. | |
116 | ||
117 | make clean && | |
118 | make -j3 && | |
119 | make check | |
120 | ||
121 | Notice that regression tests will not cover all possible cases, so you | |
122 | most likely need to use the commands, features, and fixes you did | |
123 | manually. | |
124 | ||
125 | 3. If you need to change something. | |
126 | ||
127 | git rebase -i master | |
128 | # change something | |
129 | git push -f yourgit textual:textual | |
130 | ||
131 | 4. Assuming the changes look good send them to mail list. Yes, the all | |
132 | of them! Sending pull request with github is not visible for project | |
133 | contributors, and they will not have change to review your changes. | |
134 | ||
135 | Sending only the pull request, i.e., not each patch, to mail-list is also | |
136 | bad. Nothing is as good as seeing the changes as they are, and being | |
137 | able to find them from with your favourite web search engine from | |
138 | mail-list archive. Obviously the pull request content does not get | |
139 | indexed, and that is why it is worse. | |
140 | ||
141 | git format-patch --cover-letter master..textual | |
142 | git request-pull upstream/master git://github.com/yourlogin/util-linux.git textual > tempfile | |
143 | ||
144 | Take from the 'tempfile' the header: | |
145 | ||
146 | ---------------------------------------------------------------- | |
147 | The following changes since commit 17bf9c1c39b4f35163ec5c443b8bbd5857386ddd: | |
148 | ||
149 | ipcrm: fix usage (2015-01-06 11:55:21 +0100) | |
150 | ||
151 | are available in the git repository at: | |
152 | ||
153 | git://github.com/yourlogin/util-linux.git textual | |
154 | ---------------------------------------------------------------- | |
155 | ||
156 | and copy paste it to 0000-cover-letter.patch file somewhere near 'BLURB | |
157 | HERE'. Rest of the 'request-pull' output should be ignored. | |
158 | ||
159 | In same go fix the Subject: line to have reasonable description, for | |
160 | example | |
161 | ||
162 | Subject: [PATCH 00/15] pull: various textual improvements | |
163 | ||
164 | ||
165 | Feedback and resubmissions | |
166 | -------------------------- | |
167 | ||
168 | 1. Since you sent each patch to mail-list you can see which ones got to | |
169 | be responded. In case the feedback will result in changes to the | |
170 | submission then rebase, perform the changes, and push again to your | |
171 | remote. | |
172 | ||
173 | # you probably should use 'Stay up to date' instructions now | |
174 | git checkout textual | |
175 | git rebase master -i | |
176 | # edit something | |
177 | git add files | |
178 | git commit --amend | |
179 | # Add 'Reviewed-by:', 'Tested-by:', 'Signed-off-by:', 'Reference:', and | |
180 | # other lines near signoff when needed. Attributing the reviewers is a | |
181 | # virtue, try to do it. | |
182 | git rebase --continue | |
183 | git push -f yourgit textual:textual | |
184 | ||
185 | 2. Send a message to mail-list that the submitted change has changed, and | |
186 | that the new version can be found from | |
187 | ||
188 | https://github.com/yourlogin/util-linux/commit/0123456789abcdef0123456789abcdef01234567 | |
189 | ||
190 | 3. There is no need to update the pull request cover letter. The project | |
191 | maintainer has done enough of this stuff to know what to do. | |
192 | ||
193 | ||
194 | Repository maintenance | |
195 | ---------------------- | |
196 | ||
197 | 1. When your remote branch is merged, or you got final reject, it is time | |
198 | to clean it up. | |
199 | ||
200 | git branch textual -d | |
201 | git push yourgit :textual | |
202 | ||
203 | 2. If you have other contributor repositories configured you may also | |
204 | want to clean up the branches the others are done with. | |
205 | ||
206 | for I in $(git remote); do | |
207 | echo "pruning: $I" | |
208 | git remote prune $I | |
209 | done | |
210 | ||
211 | 3. When all of your contributions are processed you should tidy up the | |
212 | git's guts. | |
213 | ||
214 | git reflog expire --all | |
215 | git gc --aggressive --prune=now | |
216 | ||
217 | Warning. That tidying is not good idea while you are actively working | |
218 | with the change set. You never know when you need to recover something | |
219 | from reflog, so keep that option available until you know the reflog is | |
220 | not needed. | |
221 | ||
222 | ||
223 | More branches, on top of branches, on top of ... | |
224 | ------------------------------------------------ | |
225 | ||
226 | Here is a one way of laying out multiple branches. | |
227 | ||
228 | git log --graph --decorate --pretty=oneline --abbrev-commit --all | |
229 | * 13bfff3 (HEAD, docs-update) docs: small improvements to howto-contribute.txt | |
230 | * 5435d28 (sami/more, more) more: do not call fileno() for std{in,out,err} streams | |
231 | * 3e1ac04 more: remove unnecessary braces | |
232 | * c19f31c more: check open(3) return value | |
233 | * 651ec1b more: move skipping forewards to a function from command() | |
234 | * bf0c2a7 more: move skipping backwards to a function from command() | |
235 | * 53a438d more: move editor execution to a function from command() | |
236 | * b11628b more: move runtime usage output away from command() | |
237 | * 6cab04e more: avoid long else segment in prbuf() | |
238 | * a2d9fbb more: remove 'register' keywords | |
239 | * c6b2d29 more: remove pointless functions | |
240 | * b41fe34 more: remove function like preprocessor defines | |
241 | * 1aaa1ce more: use paths.h to find bourne shell and vi editor | |
242 | * 016a019 more: return is statement, not a function | |
243 | * ff7019a more: remove dead code and useless comments | |
244 | * 1705c76 more: add struct more_control and remove global variables | |
245 | * 3ad4868 more: reorder includes, declarations, and global variables | |
246 | * 7220e9d more: remove function declarations - BRANCH STATUS: WORK IN PROGRESS | |
247 | * 04b9544 (sami/script) script: add noreturn function attributes | |
248 | * e7b8d50 script: use gettime_monotonic() to get timing file timestamps | |
249 | * 11289d2 script: use correct input type, move comment, and so on | |
250 | * 524e3e7 script: replace strftime() workaround with CFLAGS = -Wno-format-y2k | |
251 | * 0465e7f script: move do_io() content to small functions | |
252 | * 751edca script: add 'Script started' line always to capture file | |
253 | * f831657 script: remove io vs signal race | |
254 | * eefc1b7 script: merge doinput() and output() functions to do_io() | |
255 | * 9eba044 script: use poll() rather than select() | |
256 | * a6f04ef script: use signalfd() to catch signals | |
257 | * 4a86d9c script: add struct script_control and remove global variables | |
258 | * d1cf19c script: remove function prototypes | |
259 | * 6a7dce9 (sami/2015wk00) fsck.minix: fix segmentation fault | |
260 | * 5e3bcf7 lslocks: fix type warning | |
261 | * 3904423 maint: fix shadow declarations | |
262 | * 17bf9c1 (upstream/master, sami/master, kzgh/master, master) ipcrm: fix usage | |
263 | [...] | |
264 | ||
265 | The above gives a hint to maintainer what is the preferred merge order. | |
266 | The branches '2015wk00' and 'script' are ready to be merged, and they | |
267 | were sent to mail-list. | |
268 | ||
269 | The 'more' branch was not submitted at the time of writing this text. | |
270 | Mark-up the branch is not ready is clearly marked in the commit subject, | |
271 | that will need some rebaseing to before submission. | |
272 | ||
273 | Good order of the branches is; | |
274 | ||
275 | 1. First the minor & safe changes. | |
276 | 2. Then the ready but less certain stuff. | |
277 | 3. Followed by work-in-progress. | |
278 | ||
279 | If you go down this route you will get used to typing a lot of | |
280 | ||
281 | git rebase previous-branch | |
282 | git push -f yourgit branch:branch | |
283 | ||
284 | Alternatively rebase each branch on top of origin/master, which is not | |
285 | quite as good. How do you ensure your own changes are not in conflict | |
286 | with each other? And there is no hint of preferred merging order. |