doc/maintainer-guidelines.txt

   1 Maintainer guidelines
   2 *********************
   3
   4 This document is intended for the maintainers of the BlueZ project. It
   5 serves as basic guidelines for handling patch review and commit access.
   6
   7
   8 Rule 1: Keep the GIT tree clean and linear
   9 ==========================================
  10
  11 The bluetooth.git, bluetooth-next.git and bluez.git trees are not your
  12 private playground. The history is meant to be clean and linear.
  13
  14         - NO merges
  15         - NO branches
  16         - NO tags
  17
  18 If anyone needs testing or work on a feature, clone the tree and do
  19 it in your own copy. The master trees are off limits.
  20
  21 One advise to avoid any accidental errors in this area to set proper
  22 options in global ~/.gitconfig or local .git/config files.
  23
  24         [merge]
  25                 ff = only
  26
  27 Violations of this rule are not acceptable. This rule is enforced. If
  28 in doubt ask one of the seasoned maintainers.
  29
  30
  31 Rule 2: Enforce clean commit messages
  32 =====================================
  33
  34 The commit messages are required to be clean and follow style guidelines
  35 to be consistent.
  36
  37 Commit messages should adhere to a 72 characters by line limit. That
  38 makes it easy to read them via git log in a terminal window. Exceptions
  39 to this rule are logs, trace or other verbatim copied information.
  40
  41 Every commit requires full names and email addresses. No synonyms or
  42 nicknames are allowed. It is also important that the Outlook style
  43 names with lastname, firstname are not allowed. It is the maintainers
  44 job to ensure we get proper firstname lastname <email> authorship.
  45
  46 It is also important that the committer itself uses a valid name and
  47 email address when committing patches. So ensure that either the
  48 global ~/.gitconfig or local .git/config provides proper values.
  49
  50         [user]
  51                 name = Peter Mustermann
  52                 email = peter@mustermann.de
  53
  54 Commit messages for bluez.git shall not contain Signed-off-by
  55 signatures. They are not used in userspace and with that it is the
  56 maintainers job to ensure they do not get committed to the repository.
  57
  58 For bluetooth.git and bluetooth-next.git The Signed-off-by process is
  59 used and the signatures are required.
  60
  61 Tags like Change-Id generated from Gerrit are never acceptable. It is
  62 the maintainers job to ensure that these are not committed into the
  63 repositories.
  64
  65 Violations of this rule create a mess in the tree that can not be
  66 reversed. If in doubt ask one of the seasoned maintainers.
  67
  68
  69 Rule 3: Enforce correct coding style
  70 ====================================
  71
  72 The coding style follows roughly the kernel coding style with any
  73 exceptions documented in doc/coding-style.txt.
  74
  75 To ensure trivial white-space errors don't get committed, have the
  76 following in your .gitconfig:
  77
  78         [apply]
  79                 whitespace = error
  80
  81 It can also be helpful to use the checkpatch.pl script coming with the
  82 Linux kernel to do some automated checking. Adding the following to your
  83 .git/hooks/pre-commit and .git/hooks/pre-applypatch is a simple way to
  84 do this:
  85
  86         exec git diff --cached | ~/src/linux/scripts/checkpatch.pl -q \
  87                 --no-tree --no-signoff --show-types \
  88                 --ignore CAMELCASE,NEW_TYPEDEFS,INITIALISED_STATIC -
  89
  90 The above assumes that a kernel tree resides in ~/src/linux/.
  91
  92
  93 Rule 4: Pay extra attention to adding new files to the tree
  94 ===========================================================
  95
  96 New files that are added to the tree require several things to be
  97 verified first:
  98
  99         - Check that the names are acceptible with other maintainers
 100         - Ensure that the file modes are correct
 101         - Verify that the license & copyright headers are correct
 102         - If the file is supposed to be part of the release tarball,
 103           make sure that it gets picked up by 'make dist' (particularly
 104           important for documentation or other files that are not code)
 105
 106
 107 Rule 5: Keep the mailing list in sync with the commit process
 108 =============================================================
 109
 110 When applying patches, be sure to send a response to the mailing list as
 111 soon as the code has been pushed to the upstream tree. Usually this
 112 means one email per patch, however patch-sets may only have one response
 113 covering the entire set. If applying a subset of a patch-set clearly
 114 state what was applied in your response.