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