Skip to content

Latest commit

 

History

History
131 lines (93 loc) · 5.57 KB

contributing.md

File metadata and controls

131 lines (93 loc) · 5.57 KB
Raw

Contributing Patches to Zircon

At this point in time, Zircon is under heavy, active development, and we're not seeking major changes or new features from new contributors, however, if you desire to contribute, small bugfixes are welcome.

Here are some general guidelines for patches to Zircon. This list is incomplete and will be expanded over time.

[TOC]

Process

  • GitHub pull requests are not accepted. Patches are handled via Gerrit Code Review at: https://fuchsia-review.googlesource.com/#/q/project:zircon

  • The #fuchsia channel on the freenode irc network is a good place to ask questions.

  • Include [tags] in the commit subject flagging which module, library, app, etc, is affected by the change. The style here is somewhat informal. Look at past changes to get a feel for how these are used. Gerrit will flag your change with Needs Label: Commit-Message-has-tags if these are missing.

  • Include a line like Test: <how this was tested> in the commit message, or else Gerrit will flag your change with Needs Label: Commit-Message-has-TEST-line.

    • The full (Java-style) regex is (?i:test|tests|tested|testing)[ \t]*[=:], so lines like TESTED=asdf or Testing : 1234 are also valid, along with lines that only contain Test: with the details on the following lines.

  • [Googlers only] Commit messages may reference issue IDs, which will be turned into links in the Gerrit UI. Issues may also be automatically closed using the syntax BUG-123 #done. Note: Zircon's issue tracker is not open to external contributors at this time.

  • Zircon should be buildable for all major targets (x86-64, arm64) at every change. ./scripts/build-all-zircon can help with this.

  • Avoid breaking the unit tests. Boot Zircon and run "runtests" to verify that they're all passing.

  • Avoid whitespace or style changes. Especially do not mix style changes with patches that do other things as the style changes are a distraction.

  • Avoid changes that touch multiple modules at once if possible. Most changes should be to a single library, driver, app, etc.

Style

  • Code style mostly follows the Google C++ Style Guide, except:

    • When editing existing code, match local style. This supersedes the other style rules.

    • Maximum line width is 100 characters rather than 80.

    • Indentation is four spaces, not two. Still never use tabs. Do not leave trailing whitespace on lines. Gerrit will flag bad whitespace usage with a red background in diffs.

    • Zircon declares pointers as char* p and not as char *p;. The Google style guide is ambivalent about this; Zircon standardized on asterisk-with-type instead of asterisk-with-name.

    • Inside a switch statement, the case labels are not indented. Example:

      void foo(int which) {
    switch (which) {
    case 0:
        foo_zero();
        break;
    case 17:
        foo_seventeen();
        break;
    default:
        panic("I don't know how to foo here (which = %d)\n", which);
    }
}

    • Put curly braces around the body of any loop and in any if statement where the body is on another line (including any if statement that has an else if or else part). Trivial if statements can be written on one line, like this:

      if (result != ZX_OK) return result;

      However, do not write:

      if (result == ZX_OK)
    return do_more_stuff(data);
else
    return result;

      and do not write:

      while (result == ZX_OK)
    result = do_another_step(data);

      Note that this rule isn't enforced by clang-fmt, so please pay attention to it when writing code and reviewing commits.

  • You can run ./scripts/clang-fmt to reformat files. Pass in the filenames as arguments, e.g.

    scripts/clang-fmt kernel/top/main.c kernel/top/init.c

    The clang-fmt script will automatically download and run the clang-format binary. This fixes most style problems, except for line length (since clang-format is too aggressive about re-wrapping modified lines).

Documentation

  • Documentation is one honking great idea — let's do more of that!

    • Documentation should be in Markdown files. Our Markdown is rendered both in Gitiles in the main repo browser and in Github in the mirrored repo. Please check how your docs are rendered on both websites.

    • Some notable docs: there's a list of syscalls in docs/syscalls.md and a list of kernel cmdline options in docs/kernel_cmdline.md. When editing or adding syscalls or cmdlines, update the docs!

    • The h2md tool can scrape source files and extract embedded Markdown. It's currently used to generate API docs for DDK. ./scripts/make-markdown runs h2md against all source files in the system/ tree.