1# Contributing Patches to Zircon
2
3At this point in time, Zircon is under heavy, active development, and we're
4not seeking major changes or new features from new contributors, however, if
5you desire to [contribute](https://fuchsia.googlesource.com/docs/+/master/CONTRIBUTING.md), small bugfixes are welcome.
6
7Here are some general guidelines for patches to Zircon.  This list is
8incomplete and will be expanded over time.
9
10[TOC]
11
12## Process
13
14*   GitHub pull requests are not accepted. Patches are handled via Gerrit Code
15    Review at: https://fuchsia-review.googlesource.com/#/q/project:zircon
16
17*   The #fuchsia channel on the freenode irc network is a good place to ask
18    questions.
19
20*   Include [tags] in the commit subject flagging which module, library, app,
21    etc, is affected by the change. The style here is somewhat informal. Look at
22    past changes to get a feel for how these are used. Gerrit will flag your
23    change with `Needs Label: Commit-Message-has-tags` if these are missing.
24
25*   Include a line like `Test: <how this was tested>` in the commit message, or
26    else Gerrit will flag your change with `Needs Label:
27    Commit-Message-has-TEST-line`.
28
29    *   The full (Java-style) regex is `(?i:test|tests|tested|testing)[
30        \t]*[=:]`, so lines like `TESTED=asdf` or `Testing : 1234` are also
31        valid, along with lines that only contain `Test:` with the details on
32        the following lines.
33
34*   [Googlers only] Commit messages may reference issue IDs, which will be
35    turned into links in the Gerrit UI. Issues may also be automatically closed
36    using the syntax `BUG-123 #done`. *Note*: Zircon's issue tracker is not open
37    to external contributors at this time.
38
39*   Zircon should be buildable for all major targets (x86-64, arm64) at every
40    change. ./scripts/build-all-zircon can help with this.
41
42*   Avoid breaking the unit tests. Boot Zircon and run "runtests" to verify that
43    they're all passing.
44
45*   Avoid whitespace or style changes. Especially do not mix style changes with
46    patches that do other things as the style changes are a distraction.
47
48*   Avoid changes that touch multiple modules at once if possible. Most changes
49    should be to a single library, driver, app, etc.
50
51## Style
52
53* Code style mostly follows the [Google C++ Style Guide][google-style-guide], except:
54
55    - When editing existing code, match local style.  This supersedes the other style rules.
56
57    - Maximum line width is 100 characters rather than 80.
58
59    - Indentation is four spaces, not two.  Still never use tabs.  Do not leave trailing whitespace
60      on lines.  Gerrit will flag bad whitespace usage with a red background in diffs.
61
62    - Zircon declares pointers as `char* p` and **not** as `char *p;`.  The Google style guide is
63      ambivalent about this; Zircon standardized on asterisk-with-type instead of
64      asterisk-with-name.
65
66    - Inside a `switch` statement, the `case` labels are not indented.  Example:
67
68          void foo(int which) {
69              switch (which) {
70              case 0:
71                  foo_zero();
72                  break;
73              case 17:
74                  foo_seventeen();
75                  break;
76              default:
77                  panic("I don't know how to foo here (which = %d)\n", which);
78              }
79          }
80
81    - Put curly braces around the body of any loop and in any `if` statement where the body is on
82      another line (including any `if` statement that has an `else if` or `else` part). Trivial `if`
83      statements can be written on one line, like this:
84
85          if (result != ZX_OK) return result;
86
87       However, do **not** write:
88
89          if (result == ZX_OK)
90              return do_more_stuff(data);
91          else
92              return result;
93
94       and do **not** write:
95
96          while (result == ZX_OK)
97              result = do_another_step(data);
98
99      Note that this rule isn't enforced by `clang-fmt`, so please pay attention to it when writing
100      code and reviewing commits.
101
102* You can run `./scripts/clang-fmt` to reformat files.  Pass in the filenames as arguments, e.g.
103
104      scripts/clang-fmt kernel/top/main.c kernel/top/init.c
105
106  The `clang-fmt` script will automatically download and run the `clang-format` binary.  This fixes
107  most style problems, except for line length (since `clang-format` is too aggressive about
108  re-wrapping modified lines).
109
110## Documentation
111
112* Documentation is one honking great idea &mdash; let's do more of that!
113
114    - Documentation should be in Markdown files.  Our Markdown is rendered both in Gitiles in
115      [the main repo browser][googlesource-docs] and in Github in [the mirrored repo][github-docs].
116      Please check how your docs are rendered on both websites.
117
118    - Some notable docs: there's a list of syscalls in [docs/syscalls.md][syscall-doc] and a list of
119      kernel cmdline options in [docs/kernel_cmdline.md][cmdline-doc].  When editing or adding
120      syscalls or cmdlines, update the docs!
121
122    - [The `h2md` tool][h2md-doc] can scrape source files and extract embedded Markdown.  It's
123      currently used to generate API docs for DDK.  `./scripts/make-markdown` runs `h2md` against
124      all source files in the `system/` tree.
125
126[google-style-guide]: https://google.github.io/styleguide/cppguide.html
127[googlesource-docs]: https://fuchsia.googlesource.com/zircon/+/master/docs/
128[github-docs]: https://github.com/fuchsia-mirror/zircon/tree/master/docs
129[syscall-doc]: https://fuchsia.googlesource.com/zircon/+/master/docs/syscalls.md
130[cmdline-doc]: https://fuchsia.googlesource.com/zircon/+/master/docs/kernel_cmdline.md
131[h2md-doc]: https://fuchsia.googlesource.com/zircon/+/master/docs/h2md.md
132