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