991c73cc173d3f3efde63ae0939dba133e526d26
[akaros.git] / Documentation / Contributing.md
1 Akaros Contribution Policies
2 ===========================
3 **2019-03-14** Barret Rhoden (`brho`)
4
5 Interested in contributing to Akaros?  This document covers coding standards,
6 version control usage, and other contribution policies.
7
8 Contents
9 ---------------------------
10 + Licensing
11 + Contribution Philosophy
12 + Contribution Steps
13 + Coding Standard
14 + Git Workflow
15     - Setup
16     - A Basic Commit
17     - A Bigger Change: Several Commits!
18     - Someone Changed origin/master; My Branch is Now Old
19     - Oh No, I Committed and Pushed Something I Want to Change
20     - Crap, Someone Reset a Branch I was Tracking!
21     - What Happens When Two People `push -f`
22     - Before You Submit Patches: checkpatch
23     - How To Submit Patches: adt
24     - How To Submit Patches: git send-email
25     - How To Submit Patches: git request-pull
26
27
28 Licensing
29 ---------------------------
30 By contributing to Akaros, you are agreeing with the Developer Certificate of
31 Origin (found in [Documentation/Developer_Certificate_of_Origin](Developer_Certificate_of_Origin)
32 and at <http://developercertificate.org/>).
33
34 All contributions of any sort, including code from other projects, must be
35 compatible with the GPLv2.
36
37 All new code should be licensed "GPLv2 or later".
38
39 You (or your employer) may retain the copyright to your contributions, if
40 applicable.  We do not require copyright assignment.
41
42 Your git 'Sign-off' indicates your agreement with these rules.
43
44
45 Contribution Philosophy
46 ---------------------------
47 "Do the right thing."  If you've discovered a problem, figure out how to fix it
48 and fix it right.  You do not need to solve every problem, but think a little
49 and don't be short-sighted.  (Grep the codebase for TODO.)  For example, if you
50 want to disable the legacy USB devices, then go ahead.  You do not need to
51 write an entire USB stack, but you should expect that stack to be written in
52 the future.
53
54 You 'own' your patches and changes, meaning both that they are your
55 responsibility and you are free to pursue a solution in your own way.  You must
56 be happy with your commits; I must be ok with them.  If you're happy with
57 something half-assed, then you're in the wrong line of work.
58
59 Expect push-back on various things and plan on reworking your commits.  We
60 should be able to reach a good solution through discussion and, on occasion,
61 arguments.
62
63 Discussion and arguments about patches and technical content is fine.
64 Attacking people is not.
65
66
67 Contribution Steps
68 ---------------------------
69 Contributing to Akaros is much like contributing to the Linux kernel.
70
71 The short version of adding code to Akaros:
72 + Email the list early and often
73 + Send-email or push to your own repo/branch and request-pull
74 + Get someone (brho) to shepherd your work
75 + Fix up your commits until they are merged
76
77 Contact the list before starting on a major project.  I may already have plans
78 or initial thoughts on the matter, and someone on the list can provide advice.
79 Likewise, don't break long term plans or be too invasive for no reason.
80 Otherwise, I might not accept the change at all.
81
82 The end goal for a major change is to have a sane series of patches that
83 applies cleanly to `origin/master`.  Sane, means there are not a lot of "oh wait,
84 this patch is wrong, reverting".  The patch series should tell a story of
85 getting from A to B, where each patch is easily reviewable.
86
87 If your change is minor, like a bug fix, then feel free to just fix it and
88 submit the patch; you don't need to ask before fixing a bug.
89
90 Before you submit your patch, run scripts/checkpatch.pl on it.  Checkpatch has
91 both false positives and false negatives, but at least run it and fix the
92 obviously incorrect changes.  Email the mailing list if you have any questions.
93 See below for how to use checkpatch.
94
95 To submit your patchset, you have two options: git send-email or git
96 request-pull.  Send-email will take each of your patches and send it to the
97 mailing list.  Request-pull requires you to push your work to a branch in your
98 own repo (probably on github), and it will output a block of text.  You then
99 email that output to the mailing list with a suitable subject.  See below for
100 how to do a send-email or request-pull.
101
102 Once your patches or request-pull has been emailed to the list, someone, usually
103 me, will shepherd your work, providing feedback and TODOs.  The TODOs usually
104 consist of fixing commits, such that your patchset does not introduce errors at
105 intermediate patches.  This means you will need to rewrite commits and git's
106 history.  It is not enough to just add an extra commit on top of broken patches
107 in your patchset. (See below for some git commands and examples).
108
109 After you fixed a patchset, you send-email or request pull again, and you do so
110 in response to your original email.  For request-pull, this is easy: you just
111 hit reply to the first message.  For send-email, you use the --in-reply-to=
112 option.
113
114 In general, I prefer not to merge, but it may be necessary based on the age of
115 the changed branch.  If we scale out and have various submaintainers, we'll
116 merge those branches into the main repo.  But at this point, the `brho:origin/`
117 repo is a 'leaf' (the one and only leaf).  We'll hold off on merging until we
118 have many leaves.
119
120 If you bring in code from another project:
121 + First add the code, unaltered if possible, in a single commit.  That commit
122 must say where you got the code from, such as a URL, project name and version,
123 etc.  Do not add the .c files to Kbuild yet.  Otherwise, you'll break the build.
124
125 + Run spatch and clang-format, if applicable, in a single commit.  It's much
126 easier to diagnose problems if spatch and reformatting was done before any
127 other changes.  Sometimes these tools fail.  Just fix up any mistakes in this
128 commit.
129
130 + Add your own changes, such that it compiles.  This is the point where you add
131 the .c files to Kbuild so that we actually build the files.
132
133
134 A few final notes:
135 + You must sign-off your commits.
136
137 + Your commits should be of a reasonable size.  Try to isolate your commits to
138 logically consistent, easily verifiable changes.  Each commit should compile,
139 but you don't want to change everything in one commit.
140
141 + If a patch relied on spatch, provide the commands or scripts used in the
142 commit message.  If the script is likely to be useful beyond your patch, then
143 put it in scripts/spatch/ so we can reuse it or learn from it.
144
145 + Remember that someone other than yourself has to look at each of these
146 commits.
147
148
149 Coding Standard
150 ---------------------------
151 We use the Linux kernel coding style.  When in doubt, do what they do.
152
153 + If you are bringing in code from another project other than Linux, such as
154   Plan 9, consider running clang-format on it.  We have a format file in the
155   root of the Akaros repo.  clang-format isn't perfect, but it's close enough.
156   We do this for Plan 9 code, which we heavily internalize, but if the code is
157   a library (random, crypto, zlib) that we won't touch, then just leave it as
158   is.  That makes it easier to update the library.
159
160 + You'll note that old code may lack the correct style, especially due to the
161   large bodies of code from other systems involved.  Typically, we fix it when
162   fixing the code for other reasons, so that git blame points at the most
163   recent relevant change.
164
165 + We can do major reformatting commits and have git blame ignore them.  Talk
166   with brho before doing major reformatting.
167
168 + Indentation is done with tabs, 8-spaces wide.
169
170 + No spaces after the name of a function in a call.  For example,
171   `printk("hello")` not `printk ("hello")`.
172
173 + Functions that take no arguments are declared `f(void)` not `f()`.
174
175 + Function names are all lower-case, separated by underscores.
176
177 + One space after commas.  For example `foo(x, y, z)`, not `foo(x,y,z)`.
178
179 + One space after keywords `if`, `for`, `while`, `switch`.  For example,
180   `if (x)` not `if(x)`.
181
182 + Space before braces.  For example, `if (x) {` not `if (x){`.
183
184 + For `if/while/etc`, the opening brace is on the same line as the `if`.  If you
185   have just one line, no brace is necessary.  If you have an `if / else` clause,
186   and one of them has braces, put braces on both.  An `else` line should start
187   with a brace.
188
189 + You can use tabs or spaces for indentation, so long as the spaces follow the
190   tabs and they are not intermixed.  Older code used tabs for indentation, and
191   spaces for formatting/aligning.  Using spaces for alignment  was easier when
192   we changed from four-space tabs to eight-space tabs.  That style is also
193   eaiser for some scenarios and editors.  Don't worry too much about it.
194
195 + Preprocessor macros are usually upper-case.  Try to avoid using macros
196   unless necessary (I prefer static inlines).
197
198 + Pointer declarations have the `*` on the variable: `void *x`, not `void* x`.
199
200 + Multi-word names are lower_case_with_underscores.  Keep your names short,
201   especially for local variables.
202
203 + 'Permanent' comments in are C `/* ... */` comments.  Only use C++ style (`//`)
204   for temporary commenting-out, such as if you want to not call a function.
205   If you want to block out large chunks of code, use `#if 0 ... #endif`
206
207 + In a function definition, the function name should NOT start a new line.  Old
208   code incorrectly does this, and should be changed over time.
209
210 + Feel free to use `goto`, especially in functions that have cleanup before
211   they exit, or in other places that enhance readability.
212
213 + 80 characters per line.  When you wrap, try to line things up so they make
214   sense, such as space-indenting so function arguments line up vertically.
215
216 + Do not `typedef` structs.  You can `typedef` function pointers when convenient.
217   Keep in mind that typedefs require people to look up the real type when they
218   analyze the code.
219
220 + Try to avoid making lots of separate files or extravagant directory
221   hierarchies.  Keep in mind that people will need to work with and find these
222   files (even via tab completion, it can be a pain).
223
224 + Consider aligning the members of structs with multiple values.  I often align
225   the members (not the types) at 40 chars.  This is a stylistic choice.
226
227 Git Workflow
228 ------------------------------------
229 Git allows us to do a lot of cool things.  One of its primary purposes is to
230 provide a means for us to review each others code.  In this section, I'll
231 describe how I use git to make changes to Akaros and send those changes to the
232 mailing list.
233
234 There are a bunch of scripts and tools in scripts/git/.  I'll use some of them
235 below.
236
237 ### Setup
238
239 First off, visualizing the git tree is extremely useful.  I use:
240
241 `$ gitk --all &`
242
243 If you only have a terminal, you can use git log for a similar effect:
244
245 `$ git log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m"`
246
247 That's pretty crazy, so I have the following in my `~/.gitconfig`
248
249 ```
250 [alias]
251             gr  = log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m"
252         grs = log --graph --full-history --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s%x20%x1b[33m(%an)%x1b[0m" --simplify-by-decoration
253 ```
254
255 With those aliases, I only need to do `git gr`.
256
257
258 ### A Basic Commit
259
260 Let's say you want to make a minor change to say, the kernel monitor.  To start
261 things off, make sure you are up to date.
262
263 ```
264 $ git checkout master           # make sure you're on master
265 $ git fetch                             # grab the latest from origin/
266 $ git merge origin/master
267 ```
268
269 Many people simply do a git pull to get the latest.  I tend to fetch, then
270 merge manually after glancing at the stream of changes.  If you ever see a
271 (XCC) in one of the commit messages, then you may need to rebuild your
272 toolchain.
273
274 Time to make our change.  Let's make a branch called `monitor-change`:
275
276 `$ git checkout -b monitor-change`
277
278 Edit, compile, and test a change, say in `kern/src/monitor.c`
279
280 `$ git add -p kern/src/monitor.c`
281
282 The `-p` flag allows you to incrementally add and review each diff chunk.  It's
283 very useful for committing only what you want from a set of changes in your
284 working directory.
285
286 `$ git status`
287
288 Take a look at things before you commit; see if you missed any files or added
289 anything you don't want.
290
291 `$ git commit -s`
292
293 The -s is to append your "Signed-off-by" line.
294
295 Write a descriptive message, with a short, one-line summary first.  e.g.
296
297 ```
298 commit 52cc9b19c6edfc183276b1ebf24af9baea4d20d2
299 Author: Barret Rhoden <brho@cs.berkeley.edu>
300 Date:   Mon Jan 19 18:36:07 2015 -0500
301
302     Fixes kernel argument checking in "m"
303
304     Need at least one argument before dereferencing.
305
306     Also, debugcmd is pretty handy.
307 ```
308
309 Oh wait, say you messed up the commit message or some part of the code.  You
310 can make the change and amend the commit.
311
312 ```
313 $ vi kern/src/monitor.c
314 $ git add -p kern/src/monitor.c
315 $ git commit --amend                    # can also change the commit message
316 ```
317
318 Now that you are happy, push it.
319
320 `$ git push origin monitor-change`
321
322 Email the mailing list or your nearest shepherd, and we'll take a look!
323
324
325 ### A Bigger Change: Several Commits!
326
327 Say you are working on the monitor, and you realize your change is quite large
328 and probably should be several smaller, logically consistent commits.
329
330 You may have already added some of the changes to the index.  To reset the
331 index (what git will commit in the next commit):
332
333 `$ git reset HEAD`
334
335 Now, your changes are unstaged.  Confirm with:
336
337 `$ git status`
338
339 Now you want to add some, but not all, of your changes to `monitor.c`:
340
341 `$ git add -p kern/src/monitor.c kern/src/other_files_too.c`
342
343 Select only the changes you want, then commit:
344
345 `$ git commit -s  # write message`
346
347 Then make further commits:
348
349 ```
350 $ git add -p kern/src/monitor ; git commit -s
351 $ git add -p kern/src/monitor ; git commit -s
352
353 $ git push origin monitor-change
354 ```
355
356
357 ### Someone Changed origin/master; My Branch is Now Old
358
359 Typically, we want branches to descend from `origin/master`.  But if multiple
360 people are working at a time, someone will fall behind.  With git, dealing with
361 this situation is extremely easy.  You just need to rebase your current branch
362 on the new master.
363
364 Say you are on the branch `monitor-change`, and `origin/master` has updated.
365 Here's a reasonable workflow to deal with this situation:
366
367 ```
368 $ git fetch                             # notice origin/master changed
369 $ git checkout master           # switch to master
370 $ git merge origin/master       # fast-forward merge - straight line of commits
371 ```
372
373 Master is now up to date.  `git pull --rebase` does this too, though I prefer to
374 always fetch first.
375
376 ```
377 $ git checkout monitor-change   # needed if you aren't on monitor-change
378 $ git rebase master
379 ```
380
381 Now monitor-change descends from the latest master.
382
383 A short-cut for the last two commands is:
384
385 `$ git rebase master monitor-change`
386
387 The last parameter is simply an implied `git checkout`.
388
389 Don't forget to recompile and skim the log from the master update.  If you
390 already pushed your branch to the repo, you'll want to update that branch.
391
392 `$ git push -f origin monitor-change`
393
394 The `-f` replaces the `origin/monitor-change` with your `monitor-change`.  See below
395 for more on `-f`.
396
397 If you don't want to bother with maintaining your master right now, you can cut
398 it down to a few steps (assuming you are on `SOMEBRANCH`):
399
400 ```
401 $ git fetch
402 $ git rebase origin/master
403 $ git push -f origin/SOMEBRANCH
404 ```
405
406
407 ### Oh No, I Committed and Pushed Something I Want to Change
408
409 Fear not, adjusting git's history is very easy, and we do it all the time on
410 branches other than origin/master.
411
412 Let's say you have a string of commits, e.g.: (edited from my `git gr`)
413
414 ```
415 * 876d5b0        (HEAD, vmmcp, origin/vmmcp) VMM: handle EPT page faults
416 * f926c02        Fixes VMR creating off-by-one
417 * f62dd6c        VMM: Removes the epte_t from pte_t   Crap - bugs!
418 * 08e42d6        VMM: Call EPT ops for every KPT op
419 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
420 * ddb9fa7        x86: EPT and KPT are contiguous
421 * 1234567        (master, origin/master) Some Other Commit
422 ```
423
424 You're working on the `vmmcp` branch, and you realize that `d76b4c6` adds a bunch
425 of debug `printk`s in it and that there is a bug in `HEAD` that you introduced in
426 `f62dd6c`.
427
428 The lousy option would be to make a new commit on top of `876d5b0 (HEAD)` that
429 removes the prints and fixes the bugs.  The problem with this is that there is
430 no reason for people to even know those existed in the first place, and by
431 leaving the bugs and `printk`s in old code you only increase the load on your
432 shepherd.
433
434 Not to worry, you can use `git rebase -i` to interactively replay the commits
435 from `master..vmmcp` and rewrite the commits along the way.
436
437 First up, make sure you are on `vmmcp` and do a `git rebase -i`.
438
439 ```
440 $ git checkout vmmcp
441 $ git rebase -i master
442 ```
443
444 This will replay all commits from (`1234567`, `876d5b0`] (not including `1234567`) on
445 top of `master` (`1234567`).  Check out `git help rebase` for more info,
446 including some nifty diagrams.  In short, that `rebase` command is the shorthand
447 for:
448
449 `$ git rebase -i --onto master master vmmcp`
450
451 The `rebase` command `-i` option (interactive) will pop open an editor, where you
452 can change the order of commits, squash multiple commits into a single commit,
453 or stop and edit the commit.  Note that commits are presented in the order in
454 which they will be committed, which is the opposite of `gitk` and `git gr`, where
455 the newest commit is on top.
456
457 Let's edit the commit `d76b4c6` (change '`pick`' to '`e`').  Save and exit, and the
458 rebase will proceed.  When git hits that commit, it will stop and you can amend
459 your commit.
460
461 ```
462 $ vi somefile                   # make your changes
463 $ git add -p somefile   # add them to the index (building a commit)
464 $ git commit --amend    # amend your *old* commit (d76b4c6)
465 $ git status                    # see how you are doing
466 $ git rebase --continue
467 ```
468
469 Now check it out in `gitk` or `git gr`.  It's like your debug `printk`s never
470 existed.
471
472 Another approach is to build a temporary commit and use it as a fixup commit.
473 Let's do that to fix the bug in `f62dd6c`.
474
475 ```
476 $ git checkout vmmcp    # start from the top of the tree
477 $ vi somefile                   # make your changes
478 $ git add -p somefile   # stage the changes
479 $ git commit -m WIP-fixes-vmm-bug
480 ```
481
482 You now have something like:
483
484 ```
485 * 13a95cc        (HEAD, vmmcp) WIP-fixes-vmm-bug
486 * 876d5b0        (origin/vmmcp) VMM: handle EPT page faults
487 * f926c02        Fixes VMR creating off-by-one
488 * f62dd6c        VMM: Removes the epte_t from pte_t   Crap - bugs!
489 * 08e42d6        VMM: Call EPT ops for every KPT op
490 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
491 * ddb9fa7        x86: EPT and KPT are contiguous
492 * 1234567        (master, origin/master) Some Other Commit
493 ```
494
495 Clearly you don't want that WIP commit (WIP = work in progress).  Let's rebase!
496
497 `$ git rebase -i master`
498
499 Reorder the commits so that the WIP happens after `f62dd6c`, and change the WIP's
500 command from '`pick`' to '`f`'.
501
502 Assuming everything applies cleanly, you're done.  The WIP approach is even
503 easier than the `rebase` with `amend`.  I use it when a change applies to both the
504 current tip as well as the faulty commit.
505
506 You can even use `git rebase` to logically reorder commits so that together, the
507 'story' is more cohesive.
508
509 But wait, your version of `vmmcp` differs from `origin/vmmcp`!  The repo's `vmmcp`
510 branch still looks like the old one.  You need to `push -f` to force the repo's
511 branch to agree with yours:
512
513 `$ git push -f origin vmmcp`
514
515 This will destroy the original `origin/vmmcp` and replace it with your `vmmcp`.
516 Anyone who was tracking `origin/vmmcp` will need to reset their branch.  Do not
517 do this to `origin/master`.
518
519 Just remember: `gitk`, `git rebase`, and `git commit --amend` are your friends.
520
521
522 ### Crap, Someone Reset a Branch I was Tracking!
523
524 Say you were working on `origin/vmmcp` while someone else did the steps from the
525 previous section.  You do a `git fetch` and see that you differ!
526
527 If you don't have any changes from the original `origin/vmmcp`, then you can
528 simply:
529
530 ```
531 $ git checkout vmmcp
532 $ git reset --hard origin/vmmcp
533 ```
534
535 This throws away any differences between your tree and `origin/vmmcp`, in essence
536 making it replicate the current state of `origin/vmmcp`.  If you had any changes,
537 you just lost them.  Yikes!  If in doubt, you can make a temp branch before
538 doing anything dangerous with reset.
539
540 `$ git branch temp              # keeps a pointer called 'temp' to the current tip`
541
542 Say you do have changes.  Now what?  If they are just diffs, but not commits,
543 you can stash them, then replay the changes on the new `vmmcp` branch:
544
545 ```
546 $ git stash
547 $ git reset --hard origin/vmmcp
548 $ git stash pop         # might not apply cleanly
549 ```
550
551 If you did have commits, you'll want to rebase.  You are trying to rebase the
552 commits from your old `vmmcp` branch to the new one:
553
554 `$ git rebase --onto origin/vmmcp PREVIOUS-ORIGIN-VMMCP`
555
556 You'll need to look at `gitk`, `git log`, `git gr`, or whatever to find the commit
557 name (SHA1) of the original `origin/vmmcp` (before you fetched).  For this
558 reason, you could have a branch called vmmcp-mine for all of your changes, and
559 keep your branch `vmmcp` around to just track `origin/vmmcp`.  This is what many
560 people do with `master`: it only tracks `origin/master`, and all changes happen on
561 separate branches.
562
563 Note that you can probably just do a:
564
565 `$ git rebase origin/vmmcp`
566
567 and git will figure out and exclude which commits you have in common with
568 `origin/vmmcp` from the rebase.  Check your results in `gitk` or `git gr`.
569
570 This can be rather tricky, which is part of the reason why you shouldn't reset
571 branches that other people rely on (e.g. `origin/master`).  It's fine for small
572 group or individual work.
573
574 Just remember: `gitk` and `git rebase` are your friends.
575
576
577 ### What Happens When Two People `push -f`
578
579 Whoever pushes most recently is the one to clobber the branch.  The previous
580 person's commits would only exist in that person's personal repo!  Yikes!
581
582 In general, don't clobber (`push -f`) other people's branches without
583 coordinating first.  I reset my origin branches all the time.  I won't usually
584 reset other people's branches without checking with them.
585
586 If clobbering repo branches is a problem, you can always create your own repo
587 branch; branches are very cheap and easy.
588
589 To delete a remote branch, say after it is merged into `origin/master`:
590
591 `$ git push -f origin :BRANCH-NAME`
592
593 The : is part of the "refspec"; whatever is on the left is the source (in this
594 case, nothing).  Check out `git help push` for more info.
595
596 Again, these techinques work well with small groups, but not for big branches
597 like `origin/master`.
598
599
600 ### Before You Submit Patches: checkpatch
601
602 scripts/checkpatch.pl is modified from Linux's checkpatch and takes a patchfile as input.  I wrote a wrapper script for it that operates on a branch: scripts/git/git-checkpatch.  I have it in my path, so I can call it like a git subcommand:
603
604 ```
605 $ git checkpatch master..my_branch_head
606 ```
607
608 That will generate the patches from master..my_branch_head and run checkpatch on each of them in series.
609 If you don't have the git scripts in your path, you'll have to do something like:
610
611 ```
612 $ ./scripts/git/git-checkpatch master..my_branch_head
613 ```
614
615 Some developers have a checkpatch pre-commit hook.  It's a personal preference.  This [site](http://blog.vmsplice.net/2011/03/how-to-automatically-run-checkpatchpl.html) suggests the following:
616 ```
617         $ cat >.git/hooks/pre-commit
618         #!/bin/bash
619         exec git diff --cached | scripts/checkpatch.pl --no-signoff -q -
620         ^D
621         $ chmod 755 .git/hooks/pre-commit
622 ```
623 If checkpatch throws false-positives, then you'll have to bypass the precommit hook with a -n.
624
625 For more info on checkpatch, check out http://www.tuxradar.com/content/newbies-guide-hacking-linux-kernel.  We use it just like Linux.
626
627
628 ### How To Submit Patches: adt
629
630 adt is a script that sends patches to our gerrit repository for a review.
631 It allows you to send patches for review from the command line, but the
632 resulting code review is done on our gerrit page.
633
634 First, visit https://akaros-review.googlesource.com and sign in with a gmail
635 account to make sure it creates an account for you.
636
637 Next, make sure that you have a remote setup for gerrit.
638
639 ```
640 git remote add gerrit https://akaros.googlesource.com/akaros
641 ```
642
643 Next, make sure that you have the gerrit hooks installed. This will generate a
644 Change-ID when you do a commit. If you do this, ignore the checkpatch error
645 about gerrit Change-IDs.
646
647 ```
648 # Install Gerrit Git hooks
649 curl -Lo .git/hooks/commit-msg https://akaros-review.googlesource.com/tools/hooks/commit-msg
650 chmod +x .git/hooks/commit-msg
651 ```
652
653 Next, suppose you have a branch that contains changes you want to push up,
654 called vmm. You first do a rebase on top of brho/master, to ensure that your
655 changes are up to date.
656
657 ```
658 git pull --rebase brho master
659 ```
660
661 To send the patches up for review, you can then do:
662
663 ```
664 scripts/git/adt mail -m dcross,ganshun@google.com,rminnich,brho -t mytopic
665 ```
666
667 The three current flags for adt are as follows:
668 -m specifies your reviewers for this patch,
669
670 -cc specifies people you want to be cc'ed on this set of commits.
671
672 -t specifies the topic for this set of commits. If this flag is not provided,
673 the local current branch name will be used as the topic.
674
675 ### How To Submit Patches: git send-email
676
677 git send-email is a simple way to send patches.  It works from the command line
678 and you don't need a github account or remote repo.
679
680 Akaros is no different than Linux or any of a number of projects in our use of
681 send-email.  For a good overview, check out:
682 https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/.
683
684 Here's the basics for Akaros:
685
686 Use the config stub for sendemail in scripts/git/config to send emails to the mailing list.
687
688 If your patchset consists of more than one patch, use the --cover-letter option.
689 This will send an introductory email, called PATCH 0/n, in which you explain
690 your patch a bit.  If you have just one patch, you don't need to bother with a
691 cover letter.  Make the subject and message for the cover letter reasonably
692 descriptive of your overall change.
693
694 If you have a remote branch tracking your patchset and are not overwhelmed with
695 git commands yet, you can put the output of scripts/git/pre-se.sh in the
696 cover-letter email.  This provides a convenient github link to browse the changes.
697
698 If you are using send-email to send new versions of a patch, do it in-reply-to
699 your original email.  See git help send-email for an example.
700
701 Here's an example.  Say I have a branch called 'vmm' and want to send the patches from master to it:
702
703 ```
704 $ git send-email --cover-letter master..vmm
705 ```
706 That sent emails to the mailing list, thanks to the config setting for sendemail.
707 For your first time, you can send-email to yourself instead:
708
709 ```
710 $ git send-email --to=you@gmail.com --cover-letter master..vmm
711 ```
712
713 If you want to send a single patch from the tip of the vmm branch:
714
715 ```
716 $ git send-email -1 vmm
717 ```
718
719 For more info, check out:
720 + git help send-email
721 + https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/
722 + http://www.tuxradar.com/content/newbies-guide-hacking-linux-kernel
723
724
725 ### How To Submit Patches: git request-pull
726
727 If you have a github account or any place where you can push a branch, you can
728 use request-pull to submit a patchset.  We also have a custom version of
729 request-pull that adds extra info into the output:
730 scripts/git/git-akaros-request-pull.
731
732 The usage is simple.  Make sure your branch is up to date on your repo, then do
733 a request-pull.  'FROM' is the point from which your branch diverges from the
734 Akaros mainline.  Usually, it'll be 'master'.
735
736 ```
737 $ git push REPO BRANCH
738 $ git akaros-request-pull FROM REPO BRANCH
739 ```
740
741 Here's how I would do a request-pull for my example 'vmm' branch:
742
743 ```
744 $ git akaros-request-pull master origin vmm
745 ```
746
747 Then copy-paste the output into an email and send it to the mailing list.
748
749 If you don't have scripts/git/ in your PATH, you can either:
750
751 ```
752 $ ./scripts/git/git-akaros-request-pull master origin vmm
753 ```