vmm: Remove lapic_timer_frequency from the cmd line
[akaros.git] / Documentation / Contributing.md
1 Akaros Contribution Policies
2 ===========================
3 **2016-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 Our coding standard is similar to the Linux kernel style (but with a tabstop of
152 4), so when in doubt, do what they do.
153
154 + If you are bringing in code from another project other than Linux, such as
155 Plan 9, run clang-format on it.  We have a format file in the root of the Akaros
156 repo.  clang-format isn't perfect, but it's close enough.  Linux code is usually
157 fine (even with 8 space tabs), and formatters sometimes do more harm than good
158 on that code.  You can try clang-format for Linux code and see how it works.
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 + No spaces after the name of a function in a call.  For example,
166   `printk("hello")` not `printk ("hello")`.
167
168 + Functions that take no arguments are declared `f(void)` not `f()`.
169
170 + Function names are all lower-case, separated by underscores.
171
172 + One space after commas.  For example `foo(x, y, z)`, not `foo(x,y,z)`.
173
174 + One space after keywords `if`, `for`, `while`, `switch`.  For example,
175   `if (x)` not `if(x)`.
176
177 + Space before braces.  For example, `if (x) {` not `if (x){`.
178
179 + For `if/while/etc`, the opening brace is on the same line as the `if`.  If you
180   have just one line, no brace is necessary.  If you have an `if / else` clause,
181   and one of them has braces, put braces on both.  An `else` line should start
182   with a brace.
183
184 + Beginning-of-line indentation via tabs, not spaces.  Use spaces for
185   additional formatting (such as lining up text when word wrapping).
186
187 + Preprocessor macros are usually upper-case.  Try to avoid using macros
188   unless necessary (I prefer static inlines).
189
190 + Pointer declarations have the `*` on the variable: `void *x`, not `void* x`.
191
192 + Multi-word names are lower_case_with_underscores.  Keep your names short,
193   especially for local variables.
194
195 + 'Permanent' comments in are C `/* ... */` comments.  Only use C++ style (`//`)
196   for temporary commenting-out, such as if you want to not call a function.
197   If you want to block out large chunks of code, use `#if 0 ... #endif`
198
199 + In a function definition, the function name should NOT start a new line.  Old
200   code incorrectly does this, and should be changed over time.
201
202 + Feel free to use `goto`, especially in functions that have cleanup before
203   they exit, or in other places that enhance readability.
204
205 + 80 characters per line.  When you wrap, try to line things up so they make
206   sense, such as space-indenting so function arguments line up vertically.
207
208 + Do not `typedef` structs.  You can `typedef` function pointers when convenient.
209   Keep in mind that typedefs require people to look up the real type when they
210   analyze the code.
211
212 + Try to avoid making lots of separate files or extravagant directory
213   hierarchies.  Keep in mind that people will need to work with and find these
214   files (even via tab completion, it can be a pain).
215
216
217 Git Workflow
218 ------------------------------------
219 Git allows us to do a lot of cool things.  One of its primary purposes is to
220 provide a means for us to review each others code.  In this section, I'll
221 describe how I use git to make changes to Akaros and send those changes to the
222 mailing list.
223
224 There are a bunch of scripts and tools in scripts/git/.  I'll use some of them
225 below.
226
227 ### Setup
228
229 First off, visualizing the git tree is extremely useful.  I use:
230
231 `$ gitk --all &`
232
233 If you only have a terminal, you can use git log for a similar effect:
234
235 `$ 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"`
236
237 That's pretty crazy, so I have the following in my `~/.gitconfig`
238
239 ```
240 [alias]
241             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"
242         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
243 ```
244
245 With those aliases, I only need to do `git gr`.
246
247
248 ### A Basic Commit
249
250 Let's say you want to make a minor change to say, the kernel monitor.  To start
251 things off, make sure you are up to date.
252
253 ```
254 $ git checkout master           # make sure you're on master
255 $ git fetch                             # grab the latest from origin/
256 $ git merge origin/master
257 ```
258
259 Many people simply do a git pull to get the latest.  I tend to fetch, then
260 merge manually after glancing at the stream of changes.  If you ever see a
261 (XCC) in one of the commit messages, then you may need to rebuild your
262 toolchain.
263
264 Time to make our change.  Let's make a branch called `monitor-change`:
265
266 `$ git checkout -b monitor-change`
267
268 Edit, compile, and test a change, say in `kern/src/monitor.c`
269
270 `$ git add -p kern/src/monitor.c`
271
272 The `-p` flag allows you to incrementally add and review each diff chunk.  It's
273 very useful for committing only what you want from a set of changes in your
274 working directory.
275
276 `$ git status`
277
278 Take a look at things before you commit; see if you missed any files or added
279 anything you don't want.
280
281 `$ git commit -s`
282
283 The -s is to append your "Signed-off-by" line.
284
285 Write a descriptive message, with a short, one-line summary first.  e.g.
286
287 ```
288 commit 52cc9b19c6edfc183276b1ebf24af9baea4d20d2
289 Author: Barret Rhoden <brho@cs.berkeley.edu>
290 Date:   Mon Jan 19 18:36:07 2015 -0500
291
292     Fixes kernel argument checking in "m"
293
294     Need at least one argument before dereferencing.
295
296     Also, debugcmd is pretty handy.
297 ```
298
299 Oh wait, say you messed up the commit message or some part of the code.  You
300 can make the change and amend the commit.
301
302 ```
303 $ vi kern/src/monitor.c
304 $ git add -p kern/src/monitor.c
305 $ git commit --amend                    # can also change the commit message
306 ```
307
308 Now that you are happy, push it.
309
310 `$ git push origin monitor-change`
311
312 Email the mailing list or your nearest shepherd, and we'll take a look!
313
314
315 ### A Bigger Change: Several Commits!
316
317 Say you are working on the monitor, and you realize your change is quite large
318 and probably should be several smaller, logically consistent commits.
319
320 You may have already added some of the changes to the index.  To reset the
321 index (what git will commit in the next commit):
322
323 `$ git reset HEAD`
324
325 Now, your changes are unstaged.  Confirm with:
326
327 `$ git status`
328
329 Now you want to add some, but not all, of your changes to `monitor.c`:
330
331 `$ git add -p kern/src/monitor.c kern/src/other_files_too.c`
332
333 Select only the changes you want, then commit:
334
335 `$ git commit -s  # write message`
336
337 Then make further commits:
338
339 ```
340 $ git add -p kern/src/monitor ; git commit -s
341 $ git add -p kern/src/monitor ; git commit -s
342
343 $ git push origin monitor-change
344 ```
345
346
347 ### Someone Changed origin/master; My Branch is Now Old
348
349 Typically, we want branches to descend from `origin/master`.  But if multiple
350 people are working at a time, someone will fall behind.  With git, dealing with
351 this situation is extremely easy.  You just need to rebase your current branch
352 on the new master.
353
354 Say you are on the branch `monitor-change`, and `origin/master` has updated.
355 Here's a reasonable workflow to deal with this situation:
356
357 ```
358 $ git fetch                             # notice origin/master changed
359 $ git checkout master           # switch to master
360 $ git merge origin/master       # fast-forward merge - straight line of commits
361 ```
362
363 Master is now up to date.  `git pull --rebase` does this too, though I prefer to
364 always fetch first.
365
366 ```
367 $ git checkout monitor-change   # needed if you aren't on monitor-change
368 $ git rebase master
369 ```
370
371 Now monitor-change descends from the latest master.
372
373 A short-cut for the last two commands is:
374
375 `$ git rebase master monitor-change`
376
377 The last parameter is simply an implied `git checkout`.
378
379 Don't forget to recompile and skim the log from the master update.  If you
380 already pushed your branch to the repo, you'll want to update that branch.
381
382 `$ git push -f origin monitor-change`
383
384 The `-f` replaces the `origin/monitor-change` with your `monitor-change`.  See below
385 for more on `-f`.
386
387 If you don't want to bother with maintaining your master right now, you can cut
388 it down to a few steps (assuming you are on `SOMEBRANCH`):
389
390 ```
391 $ git fetch
392 $ git rebase origin/master
393 $ git push -f origin/SOMEBRANCH
394 ```
395
396
397 ### Oh No, I Committed and Pushed Something I Want to Change
398
399 Fear not, adjusting git's history is very easy, and we do it all the time on
400 branches other than origin/master.
401
402 Let's say you have a string of commits, e.g.: (edited from my `git gr`)
403
404 ```
405 * 876d5b0        (HEAD, vmmcp, origin/vmmcp) VMM: handle EPT page faults
406 * f926c02        Fixes VMR creating off-by-one
407 * f62dd6c        VMM: Removes the epte_t from pte_t   Crap - bugs!
408 * 08e42d6        VMM: Call EPT ops for every KPT op
409 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
410 * ddb9fa7        x86: EPT and KPT are contiguous
411 * 1234567        (master, origin/master) Some Other Commit
412 ```
413
414 You're working on the `vmmcp` branch, and you realize that `d76b4c6` adds a bunch
415 of debug `printk`s in it and that there is a bug in `HEAD` that you introduced in
416 `f62dd6c`.
417
418 The lousy option would be to make a new commit on top of `876d5b0 (HEAD)` that
419 removes the prints and fixes the bugs.  The problem with this is that there is
420 no reason for people to even know those existed in the first place, and by
421 leaving the bugs and `printk`s in old code you only increase the load on your
422 shepherd.
423
424 Not to worry, you can use `git rebase -i` to interactively replay the commits
425 from `master..vmmcp` and rewrite the commits along the way.
426
427 First up, make sure you are on `vmmcp` and do a `git rebase -i`.
428
429 ```
430 $ git checkout vmmcp
431 $ git rebase -i master
432 ```
433
434 This will replay all commits from (`1234567`, `876d5b0`] (not including `1234567`) on
435 top of `master` (`1234567`).  Check out `git help rebase` for more info,
436 including some nifty diagrams.  In short, that `rebase` command is the shorthand
437 for:
438
439 `$ git rebase -i --onto master master vmmcp`
440
441 The `rebase` command `-i` option (interactive) will pop open an editor, where you
442 can change the order of commits, squash multiple commits into a single commit,
443 or stop and edit the commit.  Note that commits are presented in the order in
444 which they will be committed, which is the opposite of `gitk` and `git gr`, where
445 the newest commit is on top.
446
447 Let's edit the commit `d76b4c6` (change '`pick`' to '`e`').  Save and exit, and the
448 rebase will proceed.  When git hits that commit, it will stop and you can amend
449 your commit.
450
451 ```
452 $ vi somefile                   # make your changes
453 $ git add -p somefile   # add them to the index (building a commit)
454 $ git commit --amend    # amend your *old* commit (d76b4c6)
455 $ git status                    # see how you are doing
456 $ git rebase --continue
457 ```
458
459 Now check it out in `gitk` or `git gr`.  It's like your debug `printk`s never
460 existed.
461
462 Another approach is to build a temporary commit and use it as a fixup commit.
463 Let's do that to fix the bug in `f62dd6c`.
464
465 ```
466 $ git checkout vmmcp    # start from the top of the tree
467 $ vi somefile                   # make your changes
468 $ git add -p somefile   # stage the changes
469 $ git commit -m WIP-fixes-vmm-bug
470 ```
471
472 You now have something like:
473
474 ```
475 * 13a95cc        (HEAD, vmmcp) WIP-fixes-vmm-bug
476 * 876d5b0        (origin/vmmcp) VMM: handle EPT page faults
477 * f926c02        Fixes VMR creating off-by-one
478 * f62dd6c        VMM: Removes the epte_t from pte_t   Crap - bugs!
479 * 08e42d6        VMM: Call EPT ops for every KPT op
480 * d76b4c6        Redefines PTE present vs mapped      Crap - debug prints!
481 * ddb9fa7        x86: EPT and KPT are contiguous
482 * 1234567        (master, origin/master) Some Other Commit
483 ```
484
485 Clearly you don't want that WIP commit (WIP = work in progress).  Let's rebase!
486
487 `$ git rebase -i master`
488
489 Reorder the commits so that the WIP happens after `f62dd6c`, and change the WIP's
490 command from '`pick`' to '`f`'.
491
492 Assuming everything applies cleanly, you're done.  The WIP approach is even
493 easier than the `rebase` with `amend`.  I use it when a change applies to both the
494 current tip as well as the faulty commit.
495
496 You can even use `git rebase` to logically reorder commits so that together, the
497 'story' is more cohesive.
498
499 But wait, your version of `vmmcp` differs from `origin/vmmcp`!  The repo's `vmmcp`
500 branch still looks like the old one.  You need to `push -f` to force the repo's
501 branch to agree with yours:
502
503 `$ git push -f origin vmmcp`
504
505 This will destroy the original `origin/vmmcp` and replace it with your `vmmcp`.
506 Anyone who was tracking `origin/vmmcp` will need to reset their branch.  Do not
507 do this to `origin/master`.
508
509 Just remember: `gitk`, `git rebase`, and `git commit --amend` are your friends.
510
511
512 ### Crap, Someone Reset a Branch I was Tracking!
513
514 Say you were working on `origin/vmmcp` while someone else did the steps from the
515 previous section.  You do a `git fetch` and see that you differ!
516
517 If you don't have any changes from the original `origin/vmmcp`, then you can
518 simply:
519
520 ```
521 $ git checkout vmmcp
522 $ git reset --hard origin/vmmcp
523 ```
524
525 This throws away any differences between your tree and `origin/vmmcp`, in essence
526 making it replicate the current state of `origin/vmmcp`.  If you had any changes,
527 you just lost them.  Yikes!  If in doubt, you can make a temp branch before
528 doing anything dangerous with reset.
529
530 `$ git branch temp              # keeps a pointer called 'temp' to the current tip`
531
532 Say you do have changes.  Now what?  If they are just diffs, but not commits,
533 you can stash them, then replay the changes on the new `vmmcp` branch:
534
535 ```
536 $ git stash
537 $ git reset --hard origin/vmmcp
538 $ git stash pop         # might not apply cleanly
539 ```
540
541 If you did have commits, you'll want to rebase.  You are trying to rebase the
542 commits from your old `vmmcp` branch to the new one:
543
544 `$ git rebase --onto origin/vmmcp PREVIOUS-ORIGIN-VMMCP`
545
546 You'll need to look at `gitk`, `git log`, `git gr`, or whatever to find the commit
547 name (SHA1) of the original `origin/vmmcp` (before you fetched).  For this
548 reason, you could have a branch called vmmcp-mine for all of your changes, and
549 keep your branch `vmmcp` around to just track `origin/vmmcp`.  This is what many
550 people do with `master`: it only tracks `origin/master`, and all changes happen on
551 separate branches.
552
553 Note that you can probably just do a:
554
555 `$ git rebase origin/vmmcp`
556
557 and git will figure out and exclude which commits you have in common with
558 `origin/vmmcp` from the rebase.  Check your results in `gitk` or `git gr`.
559
560 This can be rather tricky, which is part of the reason why you shouldn't reset
561 branches that other people rely on (e.g. `origin/master`).  It's fine for small
562 group or individual work.
563
564 Just remember: `gitk` and `git rebase` are your friends.
565
566
567 ### What Happens When Two People `push -f`
568
569 Whoever pushes most recently is the one to clobber the branch.  The previous
570 person's commits would only exist in that person's personal repo!  Yikes!
571
572 In general, don't clobber (`push -f`) other people's branches without
573 coordinating first.  I reset my origin branches all the time.  I won't usually
574 reset other people's branches without checking with them.
575
576 If clobbering repo branches is a problem, you can always create your own repo
577 branch; branches are very cheap and easy.
578
579 To delete a remote branch, say after it is merged into `origin/master`:
580
581 `$ git push -f origin :BRANCH-NAME`
582
583 The : is part of the "refspec"; whatever is on the left is the source (in this
584 case, nothing).  Check out `git help push` for more info.
585
586 Again, these techinques work well with small groups, but not for big branches
587 like `origin/master`.
588
589
590 ### Before You Submit Patches: checkpatch
591
592 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:
593
594 ```
595 $ git checkpatch master..my_branch_head
596 ```
597
598 That will generate the patches from master..my_branch_head and run checkpatch on each of them in series.
599 If you don't have the git scripts in your path, you'll have to do something like:
600
601 ```
602 $ ./scripts/git/git-checkpatch master..my_branch_head
603 ```
604
605 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:
606 ```
607         $ cat >.git/hooks/pre-commit
608         #!/bin/bash
609         exec git diff --cached | scripts/checkpatch.pl --no-signoff -q -
610         ^D
611         $ chmod 755 .git/hooks/pre-commit
612 ```
613 If checkpatch throws false-positives, then you'll have to bypass the precommit hook with a -n.
614
615 For more info on checkpatch, check out http://www.tuxradar.com/content/newbies-guide-hacking-linux-kernel.  We use it just like Linux.
616
617
618 ### How To Submit Patches: adt
619
620 adt is a script that sends patches to our gerrit repository for a review.
621 It allows you to send patches for review from the command line, but the
622 resulting code review is done on our gerrit page.
623
624 First, visit https://akaros-review.googlesource.com and sign in with a gmail
625 account to make sure it creates an account for you.
626
627 Next, make sure that you have a remote setup for gerrit.
628
629 ```
630 git remote add gerrit https://akaros.googlesource.com/akaros
631 ```
632
633 Next, make sure that you have the gerrit hooks installed. This will generate a
634 Change-ID when you do a commit. If you do this, ignore the checkpatch error
635 about gerrit Change-IDs.
636
637 ```
638 # Install Gerrit Git hooks
639 curl -Lo .git/hooks/commit-msg https://akaros-review.googlesource.com/tools/hooks/commit-msg
640 chmod +x .git/hooks/commit-msg
641 ```
642
643 Next, suppose you have a branch that contains changes you want to push up,
644 called vmm. You first do a rebase on top of brho/master, to ensure that your
645 changes are up to date.
646
647 ```
648 git pull --rebase brho master
649 ```
650
651 To send the patches up for review, you can then do:
652
653 ```
654 scripts/git/adt mail -m dcross,ganshun@google.com,rminnich,brho -t mytopic
655 ```
656
657 The three current flags for adt are as follows:
658 -m specifies your reviewers for this patch,
659
660 -cc specifies people you want to be cc'ed on this set of commits.
661
662 -t specifies the topic for this set of commits. If this flag is not provided,
663 the local current branch name will be used as the topic.
664
665 ### How To Submit Patches: git send-email
666
667 git send-email is a simple way to send patches.  It works from the command line
668 and you don't need a github account or remote repo.
669
670 Akaros is no different than Linux or any of a number of projects in our use of
671 send-email.  For a good overview, check out:
672 https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/.
673
674 Here's the basics for Akaros:
675
676 Use the config stub for sendemail in scripts/git/config to send emails to the mailing list.
677
678 If your patchset consists of more than one patch, use the --cover-letter option.
679 This will send an introductory email, called PATCH 0/n, in which you explain
680 your patch a bit.  If you have just one patch, you don't need to bother with a
681 cover letter.  Make the subject and message for the cover letter reasonably
682 descriptive of your overall change.
683
684 If you have a remote branch tracking your patchset and are not overwhelmed with
685 git commands yet, you can put the output of scripts/git/pre-se.sh in the
686 cover-letter email.  This provides a convenient github link to browse the changes.
687
688 If you are using send-email to send new versions of a patch, do it in-reply-to
689 your original email.  See git help send-email for an example.
690
691 Here's an example.  Say I have a branch called 'vmm' and want to send the patches from master to it:
692
693 ```
694 $ git send-email --cover-letter master..vmm
695 ```
696 That sent emails to the mailing list, thanks to the config setting for sendemail.
697 For your first time, you can send-email to yourself instead:
698
699 ```
700 $ git send-email --to=you@gmail.com --cover-letter master..vmm
701 ```
702
703 If you want to send a single patch from the tip of the vmm branch:
704
705 ```
706 $ git send-email -1 vmm
707 ```
708
709 For more info, check out:
710 + git help send-email
711 + https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/
712 + http://www.tuxradar.com/content/newbies-guide-hacking-linux-kernel
713
714
715 ### How To Submit Patches: git request-pull
716
717 If you have a github account or any place where you can push a branch, you can
718 use request-pull to submit a patchset.  We also have a custom version of
719 request-pull that adds extra info into the output:
720 scripts/git/git-akaros-request-pull.
721
722 The usage is simple.  Make sure your branch is up to date on your repo, then do
723 a request-pull.  'FROM' is the point from which your branch diverges from the
724 Akaros mainline.  Usually, it'll be 'master'.
725
726 ```
727 $ git push REPO BRANCH
728 $ git akaros-request-pull FROM REPO BRANCH
729 ```
730
731 Here's how I would do a request-pull for my example 'vmm' branch:
732
733 ```
734 $ git akaros-request-pull master origin vmm
735 ```
736
737 Then copy-paste the output into an email and send it to the mailing list.
738
739 If you don't have scripts/git/ in your PATH, you can either:
740
741 ```
742 $ ./scripts/git/git-akaros-request-pull master origin vmm
743 ```