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.
12 1. Find a git server that can be reached from anywhere in internet
13 anonymously. Github is for example a popular choice.
15 2. Create your own util-linux contributor repository, and push an upstream
18 3. In these instructions the upstream remote repository is called
19 'origin' and the 'yourgit' is the contributor repo.
22 git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
24 git remote add yourgit git@github.com:yourlogin/util-linux.git
31 1. Use the name of the subsystem, such as blkid, libmount, misc-utils,
32 that is the common thing for changes in the change set.
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.
38 3. Do not use 'master' branch to your contributions. The 'master' branch
39 is needed to stay up to date with upstream.
41 4. When done push your branch to your remote git server.
45 # spent here most of the effort
46 git push yourgit textual:textual
48 5. Do not worry if you used stupid-and-wrong branch name, it can be fixed
51 git branch -m stupid-and-wrong brilliant
52 git push yourgit brilliant:brilliant :stupid-and-wrong
58 1. Ensure you have the latest from all remote repositories.
60 2. Merge upstream 'master' branch if needed to your local 'master'.
62 3. Rebase your working contribution branches.
64 4. Push the changes to 'yourgit'.
67 git log --graph --decorate --pretty=oneline --abbrev-commit --all
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:
72 6. Push a backup of your branch 'textual' to 'yourgit', then
75 git merge origin/master
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
84 7. Assuming rebase went fine push the latest to 'yourgit'.
86 git push yourgit master:master
87 git push yourgit --force textual:textual
89 The contributor branch tends to need --force every now and then, don't be
92 8. Push error with master branch
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
99 git push --mirror yourgit
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.
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).
114 2. Check the next day the changes compile without errors or warnings, and
115 that regression tests run fine.
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
125 3. If you need to change something.
129 git push -f yourgit textual:textual
131 4. You have two ways how to send your pull request:
133 4.1 Github pull request
135 This is recommended way for your small and trivial changes, or for
136 work-in-progress projects (rewrites, new commands, etc.). All you
137 need is to press "pull request" button on GitHub.
139 4.2. Send your work to the mailing list
141 Assuming the changes look good send them to mail list. Yes, the all
142 of them! Sending pull request with github is not visible for project
143 contributors, and they will not have change to review your changes.
145 Sending only the pull request, i.e., not each patch, to mail-list is also
146 bad. Nothing is as good as seeing the changes as they are, and being
147 able to find them from with your favourite web search engine from
148 mail-list archive. Obviously the pull request content does not get
149 indexed, and that is why it is worse.
151 git format-patch --cover-letter master..textual
152 git request-pull upstream/master git://github.com/yourlogin/util-linux.git textual > tempfile
154 Take from the 'tempfile' the header:
156 ----------------------------------------------------------------
157 The following changes since commit 17bf9c1c39b4f35163ec5c443b8bbd5857386ddd:
159 ipcrm: fix usage (2015-01-06 11:55:21 +0100)
161 are available in the git repository at:
163 git://github.com/yourlogin/util-linux.git textual
164 ----------------------------------------------------------------
166 and copy paste it to 0000-cover-letter.patch file somewhere near 'BLURB
167 HERE'. Rest of the 'request-pull' output should be ignored.
169 In same go fix the Subject: line to have reasonable description, for
172 Subject: [PATCH 00/15] pull: various textual improvements
175 Feedback and resubmissions
176 --------------------------
178 1. Since you sent each patch to mail-list you can see which ones got to
179 be responded. In case the feedback will result in changes to the
180 submission then rebase, perform the changes, and push again to your
183 # you probably should use 'Stay up to date' instructions now
189 # Add 'Reviewed-by:', 'Tested-by:', 'Signed-off-by:', 'Reference:', and
190 # other lines near signoff when needed. Attributing the reviewers is a
191 # virtue, try to do it.
192 git rebase --continue
193 git push -f yourgit textual:textual
195 2. Send a message to mail-list that the submitted change has changed, and
196 that the new version can be found from
198 https://github.com/yourlogin/util-linux/commit/0123456789abcdef0123456789abcdef01234567
200 3. There is no need to update the pull request cover letter. The project
201 maintainer has done enough of this stuff to know what to do.
204 Repository maintenance
205 ----------------------
207 1. When your remote branch is merged, or you got final reject, it is time
210 git branch textual -d
211 git push yourgit :textual
213 2. If you have other contributor repositories configured you may also
214 want to clean up the branches the others are done with.
216 for I in $(git remote); do
221 3. When all of your contributions are processed you should tidy up the
224 git reflog expire --all
225 git gc --aggressive --prune=now
227 Warning. That tidying is not good idea while you are actively working
228 with the change set. You never know when you need to recover something
229 from reflog, so keep that option available until you know the reflog is
233 More branches, on top of branches, on top of ...
234 ------------------------------------------------
236 Here is a one way of laying out multiple branches.
238 git log --graph --decorate --pretty=oneline --abbrev-commit --all
239 * 13bfff3 (HEAD, docs-update) docs: small improvements to howto-contribute.txt
240 * 5435d28 (sami/more, more) more: do not call fileno() for std{in,out,err} streams
241 * 3e1ac04 more: remove unnecessary braces
242 * c19f31c more: check open(3) return value
243 * 651ec1b more: move skipping forewards to a function from command()
244 * bf0c2a7 more: move skipping backwards to a function from command()
245 * 53a438d more: move editor execution to a function from command()
246 * b11628b more: move runtime usage output away from command()
247 * 6cab04e more: avoid long else segment in prbuf()
248 * a2d9fbb more: remove 'register' keywords
249 * c6b2d29 more: remove pointless functions
250 * b41fe34 more: remove function like preprocessor defines
251 * 1aaa1ce more: use paths.h to find bourne shell and vi editor
252 * 016a019 more: return is statement, not a function
253 * ff7019a more: remove dead code and useless comments
254 * 1705c76 more: add struct more_control and remove global variables
255 * 3ad4868 more: reorder includes, declarations, and global variables
256 * 7220e9d more: remove function declarations - BRANCH STATUS: WORK IN PROGRESS
257 * 04b9544 (sami/script) script: add noreturn function attributes
258 * e7b8d50 script: use gettime_monotonic() to get timing file timestamps
259 * 11289d2 script: use correct input type, move comment, and so on
260 * 524e3e7 script: replace strftime() workaround with CFLAGS = -Wno-format-y2k
261 * 0465e7f script: move do_io() content to small functions
262 * 751edca script: add 'Script started' line always to capture file
263 * f831657 script: remove io vs signal race
264 * eefc1b7 script: merge doinput() and output() functions to do_io()
265 * 9eba044 script: use poll() rather than select()
266 * a6f04ef script: use signalfd() to catch signals
267 * 4a86d9c script: add struct script_control and remove global variables
268 * d1cf19c script: remove function prototypes
269 * 6a7dce9 (sami/2015wk00) fsck.minix: fix segmentation fault
270 * 5e3bcf7 lslocks: fix type warning
271 * 3904423 maint: fix shadow declarations
272 * 17bf9c1 (upstream/master, sami/master, kzgh/master, master) ipcrm: fix usage
275 The above gives a hint to maintainer what is the preferred merge order.
276 The branches '2015wk00' and 'script' are ready to be merged, and they
277 were sent to mail-list.
279 The 'more' branch was not submitted at the time of writing this text.
280 Mark-up the branch is not ready is clearly marked in the commit subject,
281 that will need some rebaseing to before submission.
283 Good order of the branches is;
285 1. First the minor & safe changes.
286 2. Then the ready but less certain stuff.
287 3. Followed by work-in-progress.
289 If you go down this route you will get used to typing a lot of
291 git rebase previous-branch
292 git push -f yourgit branch:branch
294 Alternatively rebase each branch on top of origin/master, which is not
295 quite as good. How do you ensure your own changes are not in conflict
296 with each other? And there is no hint of preferred merging order.