akaros/Documentation/Contributing.md
<<
>>
Prefs
   1Akaros Contribution Policies
   2===========================
   3**2019-03-14** Barret Rhoden (`brho`)
   4
   5Interested in contributing to Akaros?  This document covers coding standards,
   6version control usage, and other contribution policies.
   7
   8Contents
   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
  28Licensing
  29---------------------------
  30By contributing to Akaros, you are agreeing with the Developer Certificate of
  31Origin (found in [Documentation/Developer_Certificate_of_Origin](Developer_Certificate_of_Origin)
  32and at <http://developercertificate.org/>).
  33
  34All contributions of any sort, including code from other projects, must be
  35compatible with the GPLv2.
  36
  37All new code should be licensed "GPLv2 or later".
  38
  39You (or your employer) may retain the copyright to your contributions, if
  40applicable.  We do not require copyright assignment.
  41
  42Your git 'Sign-off' indicates your agreement with these rules.
  43
  44
  45Contribution Philosophy
  46---------------------------
  47"Do the right thing."  If you've discovered a problem, figure out how to fix it
  48and fix it right.  You do not need to solve every problem, but think a little
  49and don't be short-sighted.  (Grep the codebase for TODO.)  For example, if you
  50want to disable the legacy USB devices, then go ahead.  You do not need to
  51write an entire USB stack, but you should expect that stack to be written in
  52the future.
  53
  54You 'own' your patches and changes, meaning both that they are your
  55responsibility and you are free to pursue a solution in your own way.  You must
  56be happy with your commits; I must be ok with them.  If you're happy with
  57something half-assed, then you're in the wrong line of work.
  58
  59Expect push-back on various things and plan on reworking your commits.  We
  60should be able to reach a good solution through discussion and, on occasion,
  61arguments.
  62
  63Discussion and arguments about patches and technical content is fine.
  64Attacking people is not.
  65
  66
  67Contribution Steps
  68---------------------------
  69Contributing to Akaros is much like contributing to the Linux kernel.
  70
  71The 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
  77Contact the list before starting on a major project.  I may already have plans
  78or initial thoughts on the matter, and someone on the list can provide advice.
  79Likewise, don't break long term plans or be too invasive for no reason.
  80Otherwise, I might not accept the change at all.
  81
  82The end goal for a major change is to have a sane series of patches that
  83applies cleanly to `origin/master`.  Sane, means there are not a lot of "oh wait,
  84this patch is wrong, reverting".  The patch series should tell a story of
  85getting from A to B, where each patch is easily reviewable.
  86
  87If your change is minor, like a bug fix, then feel free to just fix it and
  88submit the patch; you don't need to ask before fixing a bug.
  89
  90Before you submit your patch, run scripts/checkpatch.pl on it.  Checkpatch has
  91both false positives and false negatives, but at least run it and fix the
  92obviously incorrect changes.  Email the mailing list if you have any questions.
  93See below for how to use checkpatch.
  94
  95To submit your patchset, you have two options: git send-email or git
  96request-pull.  Send-email will take each of your patches and send it to the
  97mailing list.  Request-pull requires you to push your work to a branch in your
  98own repo (probably on github), and it will output a block of text.  You then
  99email that output to the mailing list with a suitable subject.  See below for
 100how to do a send-email or request-pull.
 101
 102Once your patches or request-pull has been emailed to the list, someone, usually
 103me, will shepherd your work, providing feedback and TODOs.  The TODOs usually
 104consist of fixing commits, such that your patchset does not introduce errors at
 105intermediate patches.  This means you will need to rewrite commits and git's
 106history.  It is not enough to just add an extra commit on top of broken patches
 107in your patchset. (See below for some git commands and examples).
 108
 109After you fixed a patchset, you send-email or request pull again, and you do so
 110in response to your original email.  For request-pull, this is easy: you just
 111hit reply to the first message.  For send-email, you use the --in-reply-to=
 112option.
 113
 114In general, I prefer not to merge, but it may be necessary based on the age of
 115the changed branch.  If we scale out and have various submaintainers, we'll
 116merge those branches into the main repo.  But at this point, the `brho:origin/`
 117repo is a 'leaf' (the one and only leaf).  We'll hold off on merging until we
 118have many leaves.
 119
 120If you bring in code from another project:
 121+ First add the code, unaltered if possible, in a single commit.  That commit
 122must say where you got the code from, such as a URL, project name and version,
 123etc.  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
 126easier to diagnose problems if spatch and reformatting was done before any
 127other changes.  Sometimes these tools fail.  Just fix up any mistakes in this
 128commit.
 129
 130+ Add your own changes, such that it compiles.  This is the point where you add
 131the .c files to Kbuild so that we actually build the files.
 132
 133
 134A 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
 138logically consistent, easily verifiable changes.  Each commit should compile,
 139but 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
 142commit message.  If the script is likely to be useful beyond your patch, then
 143put 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
 146commits.
 147
 148
 149Coding Standard
 150---------------------------
 151We 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
 227Git Workflow
 228------------------------------------
 229Git allows us to do a lot of cool things.  One of its primary purposes is to
 230provide a means for us to review each others code.  In this section, I'll
 231describe how I use git to make changes to Akaros and send those changes to the
 232mailing list.
 233
 234There are a bunch of scripts and tools in scripts/git/.  I'll use some of them
 235below.
 236
 237### Setup
 238
 239First off, visualizing the git tree is extremely useful.  I use:
 240
 241`$ gitk --all &`
 242
 243If 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
 247That'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
 255With those aliases, I only need to do `git gr`.
 256
 257
 258### A Basic Commit
 259
 260Let's say you want to make a minor change to say, the kernel monitor.  To start
 261things 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
 269Many people simply do a git pull to get the latest.  I tend to fetch, then
 270merge 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
 272toolchain.
 273
 274Time to make our change.  Let's make a branch called `monitor-change`:
 275
 276`$ git checkout -b monitor-change`
 277
 278Edit, compile, and test a change, say in `kern/src/monitor.c`
 279
 280`$ git add -p kern/src/monitor.c`
 281
 282The `-p` flag allows you to incrementally add and review each diff chunk.  It's
 283very useful for committing only what you want from a set of changes in your
 284working directory.
 285
 286`$ git status`
 287
 288Take a look at things before you commit; see if you missed any files or added
 289anything you don't want.
 290
 291`$ git commit -s`
 292
 293The -s is to append your "Signed-off-by" line.
 294
 295Write a descriptive message, with a short, one-line summary first.  e.g.
 296
 297```
 298commit 52cc9b19c6edfc183276b1ebf24af9baea4d20d2
 299Author: Barret Rhoden <brho@cs.berkeley.edu>
 300Date:   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
 309Oh wait, say you messed up the commit message or some part of the code.  You
 310can 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
 318Now that you are happy, push it.
 319
 320`$ git push origin monitor-change`
 321
 322Email the mailing list or your nearest shepherd, and we'll take a look!
 323
 324
 325### A Bigger Change: Several Commits!
 326
 327Say you are working on the monitor, and you realize your change is quite large
 328and probably should be several smaller, logically consistent commits.
 329
 330You may have already added some of the changes to the index.  To reset the
 331index (what git will commit in the next commit):
 332
 333`$ git reset HEAD`
 334
 335Now, your changes are unstaged.  Confirm with:
 336
 337`$ git status`
 338
 339Now 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
 343Select only the changes you want, then commit:
 344
 345`$ git commit -s  # write message`
 346
 347Then 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
 359Typically, we want branches to descend from `origin/master`.  But if multiple
 360people are working at a time, someone will fall behind.  With git, dealing with
 361this situation is extremely easy.  You just need to rebase your current branch
 362on the new master.
 363
 364Say you are on the branch `monitor-change`, and `origin/master` has updated.
 365Here'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
 373Master is now up to date.  `git pull --rebase` does this too, though I prefer to
 374always fetch first.
 375
 376```
 377$ git checkout monitor-change   # needed if you aren't on monitor-change
 378$ git rebase master
 379```
 380
 381Now monitor-change descends from the latest master.
 382
 383A short-cut for the last two commands is:
 384
 385`$ git rebase master monitor-change`
 386
 387The last parameter is simply an implied `git checkout`.
 388
 389Don't forget to recompile and skim the log from the master update.  If you
 390already pushed your branch to the repo, you'll want to update that branch.
 391
 392`$ git push -f origin monitor-change`
 393
 394The `-f` replaces the `origin/monitor-change` with your `monitor-change`.  See
 395below for more on `-f`.
 396
 397If you don't want to bother with maintaining your master right now, you can cut
 398it 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
 409Fear not, adjusting git's history is very easy, and we do it all the time on
 410branches other than origin/master.
 411
 412Let'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
 424You're working on the `vmmcp` branch, and you realize that `d76b4c6` adds a
 425bunch of debug `printk`s in it and that there is a bug in `HEAD` that you
 426introduced in `f62dd6c`.
 427
 428The lousy option would be to make a new commit on top of `876d5b0 (HEAD)` that
 429removes the prints and fixes the bugs.  The problem with this is that there is
 430no reason for people to even know those existed in the first place, and by
 431leaving the bugs and `printk`s in old code you only increase the load on your
 432shepherd.
 433
 434Not to worry, you can use `git rebase -i` to interactively replay the commits
 435from `master..vmmcp` and rewrite the commits along the way.
 436
 437First 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
 444This will replay all commits from (`1234567`, `876d5b0`] (not including
 445`1234567`) on top of `master` (`1234567`).  Check out `git help rebase` for
 446more info, including some nifty diagrams.  In short, that `rebase` command is
 447the shorthand for:
 448
 449`$ git rebase -i --onto master master vmmcp`
 450
 451The `rebase` command `-i` option (interactive) will pop open an editor, where
 452you can change the order of commits, squash multiple commits into a single
 453commit, or stop and edit the commit.  Note that commits are presented in the
 454order in which they will be committed, which is the opposite of `gitk` and `git
 455gr`, where the newest commit is on top.
 456
 457Let's edit the commit `d76b4c6` (change '`pick`' to '`e`').  Save and exit, and
 458the rebase will proceed.  When git hits that commit, it will stop and you can
 459amend 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
 469Now check it out in `gitk` or `git gr`.  It's like your debug `printk`s never
 470existed.
 471
 472Another approach is to build a temporary commit and use it as a fixup commit.
 473Let'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
 482You 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
 495Clearly you don't want that WIP commit (WIP = work in progress).  Let's rebase!
 496
 497`$ git rebase -i master`
 498
 499Reorder the commits so that the WIP happens after `f62dd6c`, and change the
 500WIP's command from '`pick`' to '`f`'.
 501
 502Assuming everything applies cleanly, you're done.  The WIP approach is even
 503easier than the `rebase` with `amend`.  I use it when a change applies to both
 504the current tip as well as the faulty commit.
 505
 506You can even use `git rebase` to logically reorder commits so that together, the
 507'story' is more cohesive.
 508
 509But wait, your version of `vmmcp` differs from `origin/vmmcp`!  The repo's
 510`vmmcp` branch still looks like the old one.  You need to `push -f` to force
 511the repo's branch to agree with yours:
 512
 513`$ git push -f origin vmmcp`
 514
 515This will destroy the original `origin/vmmcp` and replace it with your `vmmcp`.
 516Anyone who was tracking `origin/vmmcp` will need to reset their branch.  Do not
 517do this to `origin/master`.
 518
 519Just remember: `gitk`, `git rebase`, and `git commit --amend` are your friends.
 520
 521
 522### Crap, Someone Reset a Branch I was Tracking!
 523
 524Say you were working on `origin/vmmcp` while someone else did the steps from the
 525previous section.  You do a `git fetch` and see that you differ!
 526
 527If you don't have any changes from the original `origin/vmmcp`, then you can
 528simply:
 529
 530```
 531$ git checkout vmmcp
 532$ git reset --hard origin/vmmcp
 533```
 534
 535This throws away any differences between your tree and `origin/vmmcp`, in
 536essence making it replicate the current state of `origin/vmmcp`.  If you had
 537any changes, you just lost them.  Yikes!  If in doubt, you can make a temp
 538branch before doing anything dangerous with reset.
 539
 540`$ git branch temp              # keeps a pointer called 'temp' to the current tip`
 541
 542Say you do have changes.  Now what?  If they are just diffs, but not commits,
 543you 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
 551If you did have commits, you'll want to rebase.  You are trying to rebase the
 552commits from your old `vmmcp` branch to the new one:
 553
 554`$ git rebase --onto origin/vmmcp PREVIOUS-ORIGIN-VMMCP`
 555
 556You'll need to look at `gitk`, `git log`, `git gr`, or whatever to find the
 557commit name (SHA1) of the original `origin/vmmcp` (before you fetched).  For
 558this reason, you could have a branch called vmmcp-mine for all of your changes,
 559and keep your branch `vmmcp` around to just track `origin/vmmcp`.  This is what
 560many people do with `master`: it only tracks `origin/master`, and all changes
 561happen on separate branches.
 562
 563Note that you can probably just do a:
 564
 565`$ git rebase origin/vmmcp`
 566
 567and 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
 570This can be rather tricky, which is part of the reason why you shouldn't reset
 571branches that other people rely on (e.g. `origin/master`).  It's fine for small
 572group or individual work.
 573
 574Just remember: `gitk` and `git rebase` are your friends.
 575
 576
 577### What Happens When Two People `push -f`
 578
 579Whoever pushes most recently is the one to clobber the branch.  The previous
 580person's commits would only exist in that person's personal repo!  Yikes!
 581
 582In general, don't clobber (`push -f`) other people's branches without
 583coordinating first.  I reset my origin branches all the time.  I won't usually
 584reset other people's branches without checking with them.
 585
 586If clobbering repo branches is a problem, you can always create your own repo
 587branch; branches are very cheap and easy.
 588
 589To delete a remote branch, say after it is merged into `origin/master`:
 590
 591`$ git push -f origin :BRANCH-NAME`
 592
 593The : is part of the "refspec"; whatever is on the left is the source (in this
 594case, nothing).  Check out `git help push` for more info.
 595
 596Again, these techinques work well with small groups, but not for big branches
 597like `origin/master`.
 598
 599
 600### Before You Submit Patches: checkpatch
 601
 602scripts/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
 608That will generate the patches from master..my_branch_head and run checkpatch
 609on each of them in series.  If you don't have the git scripts in your path,
 610you'll have to do something like:
 611
 612```
 613$ ./scripts/git/git-checkpatch master..my_branch_head
 614```
 615
 616Some 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:
 617```
 618        $ cat >.git/hooks/pre-commit
 619        #!/bin/bash
 620        exec git diff --cached | scripts/checkpatch.pl --no-signoff -q -
 621        ^D
 622        $ chmod 755 .git/hooks/pre-commit
 623```
 624If checkpatch throws false-positives, then you'll have to bypass the precommit hook with a -n.
 625
 626For more info on checkpatch, check out http://www.tuxradar.com/content/newbies-guide-hacking-linux-kernel.  We use it just like Linux.
 627
 628
 629### How To Submit Patches: adt
 630
 631adt is a script that sends patches to our gerrit repository for a review.
 632It allows you to send patches for review from the command line, but the
 633resulting code review is done on our gerrit page.
 634
 635First, visit https://akaros-review.googlesource.com and sign in with a gmail
 636account to make sure it creates an account for you.
 637
 638Next, make sure that you have a remote setup for gerrit.
 639
 640```
 641git remote add gerrit https://akaros.googlesource.com/akaros
 642```
 643
 644Next, make sure that you have the gerrit hooks installed. This will generate a
 645Change-ID when you do a commit. If you do this, ignore the checkpatch error
 646about gerrit Change-IDs.
 647
 648```
 649# Install Gerrit Git hooks
 650curl -Lo .git/hooks/commit-msg https://akaros-review.googlesource.com/tools/hooks/commit-msg
 651chmod +x .git/hooks/commit-msg
 652```
 653
 654Next, suppose you have a branch that contains changes you want to push up,
 655called vmm. You first do a rebase on top of brho/master, to ensure that your
 656changes are up to date.
 657
 658```
 659git pull --rebase brho master
 660```
 661
 662To send the patches up for review, you can then do:
 663
 664```
 665scripts/git/adt mail -m dcross,ganshun@google.com,rminnich,brho -t mytopic
 666```
 667
 668The three current flags for adt are as follows:
 669-m specifies your reviewers for this patch,
 670
 671-cc specifies people you want to be cc'ed on this set of commits.
 672
 673-t specifies the topic for this set of commits. If this flag is not provided,
 674the local current branch name will be used as the topic.
 675
 676### How To Submit Patches: git send-email
 677
 678git send-email is a simple way to send patches.  It works from the command line
 679and you don't need a github account or remote repo.
 680
 681Akaros is no different than Linux or any of a number of projects in our use of
 682send-email.  For a good overview, check out:
 683https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/.
 684
 685Here's the basics for Akaros:
 686
 687Use the config stub for sendemail in scripts/git/config to send emails to the mailing list.
 688
 689If your patchset consists of more than one patch, use the --cover-letter option.
 690This will send an introductory email, called PATCH 0/n, in which you explain
 691your patch a bit.  If you have just one patch, you don't need to bother with a
 692cover letter.  Make the subject and message for the cover letter reasonably
 693descriptive of your overall change.
 694
 695If you have a remote branch tracking your patchset and are not overwhelmed with
 696git commands yet, you can put the output of scripts/git/pre-se.sh in the
 697cover-letter email.  This provides a convenient github link to browse the changes.
 698
 699If you are using send-email to send new versions of a patch, do it in-reply-to
 700your original email.  See git help send-email for an example.
 701
 702Here's an example.  Say I have a branch called 'vmm' and want to send the patches from master to it:
 703
 704```
 705$ git send-email --cover-letter master..vmm
 706```
 707That sent emails to the mailing list, thanks to the config setting for sendemail.
 708For your first time, you can send-email to yourself instead:
 709
 710```
 711$ git send-email --to=you@gmail.com --cover-letter master..vmm
 712```
 713
 714If you want to send a single patch from the tip of the vmm branch:
 715
 716```
 717$ git send-email -1 vmm
 718```
 719
 720For more info, check out:
 721+ git help send-email
 722+ https://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/
 723+ http://www.tuxradar.com/content/newbies-guide-hacking-linux-kernel
 724
 725
 726### How To Submit Patches: git request-pull
 727
 728If you have a github account or any place where you can push a branch, you can
 729use request-pull to submit a patchset.  We also have a custom version of
 730request-pull that adds extra info into the output:
 731scripts/git/git-akaros-request-pull.
 732
 733The usage is simple.  Make sure your branch is up to date on your repo, then do
 734a request-pull.  'FROM' is the point from which your branch diverges from the
 735Akaros mainline.  Usually, it'll be 'master'.
 736
 737```
 738$ git push REPO BRANCH
 739$ git akaros-request-pull FROM REPO BRANCH
 740```
 741
 742Here's how I would do a request-pull for my example 'vmm' branch:
 743
 744```
 745$ git akaros-request-pull master origin vmm
 746```
 747
 748Then copy-paste the output into an email and send it to the mailing list.
 749
 750If you don't have scripts/git/ in your PATH, you can either:
 751
 752```
 753$ ./scripts/git/git-akaros-request-pull master origin vmm
 754```
 755