docs/CONTRIBUTING

   1                __________               __   ___.
   2      Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
   3      Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
   4      Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
   5      Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
   6                        \/            \/     \/    \/            \/
   7                                  Contribution Policies
   8
   9
  10 In order for the project to run as smoothly as possible, it's best if all
  11 contributors adhere to a few simple source code conventions:
  12
  13 Exceptions
  14 ----------
  15 This project borrows and imports quite a lot of code from other free software
  16 projects. We do not change style of such code unless we really have to, even
  17 though they might be using style very different from others.
  18
  19 Language
  20 --------
  21 Write all code in C. Sometimes assembly is faster, but C is always more
  22 readable and maintainable.
  23
  24 Language features
  25 -----------------
  26 Write normal C code. Keep it simple. Don't redefine the language. No new types
  27 (structs are structs, not typedefs). No C++isms or Javaisms. No code in .h
  28 files or #defines.
  29
  30 Identifiers
  31 -----------
  32 We do not want mixed case identifiers.
  33 Variables and function names should be all lower case.
  34 Struct and enum names should be all lower case.
  35 Preprocessor symbols and enum constants should be all upper case.
  36
  37 Comments
  38 --------
  39 We only use plain old /* C standard comments */.
  40 If you want to comment out large blocks containing other comments, use #if 0.
  41
  42 Style
  43 -----
  44 When changing code, follow the code style of the file you are editing.
  45
  46 When writing new files, you may use the brace placement style of your choice.
  47
  48 Braces for function declarations are put in a new line under the name, as in:
  49
  50   int foo(char *name)
  51   {
  52      return FOO_NAME:
  53   }
  54
  55 Always indent your code with four spaces. Don't use TAB characters, as that
  56 will mess up code display, printing, and a zillion other places.
  57
  58 Keep lines below 80 columns length. Use whitespace and newlines to make the
  59 code easy to browse/read.
  60
  61 Text format
  62 -----------
  63 Use "unix style" line feeds: "LF" only. Do not use "CR+LF".
  64
  65 Use UTF-8 character set, but try to refrain from using any non-ascii
  66 letters as they will only appear weird in some camps no matter what.
  67
  68 Contributing code
  69 -------
  70 We have a public code review system based on git, which is also how you can
  71 check out the latest version of the Rockbox sources.
  72 See http://www.rockbox.org/wiki/UsingGit for details on how to setup your
  73 environment and how to upload a change you have made for review.
  74
  75 We'd prefer that you don't submit patches to the bug tracker any more,
  76 as it's much harder to read and discuss them there.
  77
  78 Credits
  79 -------
  80 We believe in crediting all contributors by name. Before committing a patch to
  81 Git, we ask that you give us your full real name (no pseudonyms or nicknames)
  82 for adding to the credits list.