HACKING

   1 SCM
   2 ===
   3
   4  - anonymous checkouts
   5
   6    $ git clone git://git.freedesktop.org/git/PolicyKit.git
   7
   8  - checkouts if you got an ssh account on fd.o (username@ is optional)
   9
  10    $ git clone ssh://[username@]git.freedesktop.org/git/PolicyKit.git
  11
  12  - commit to local repository
  13
  14    $ git commit -a
  15
  16  - push local repository to master repository at fd.o (remember most patches
  17    requires review at the mailing list)
  18
  19    $ git push
  20
  21  - pull changes from master repository at fd.o
  22
  23    $ git pull
  24
  25  - diff of working tree versus local repository
  26
  27    $ git diff
  28
  29  - diff of local repository vs. master repository at fd.o
  30
  31    synchronize with upstream repo:
  32    $ git pull
  33
  34    (possibly merge changes)
  35
  36    generate the diff:
  37    $ git diff origin HEAD
  38
  39  - influential environment variables (set these in e.g. .bash_profile)
  40
  41    export GIT_AUTHOR_NAME='Your Full Name'
  42    export GIT_COMMITTER_NAME='Your Full Name'
  43    export GIT_COMMITTER_EMAIL=youremail@domain.net
  44    export GIT_AUTHOR_EMAIL=youremail@domain.net
  45
  46  - see also
  47
  48     http://www.kernel.org/pub/software/scm/git/docs/
  49
  50
  51 Committing code
  52 ===
  53
  54  - Commit messages should be of the form (the five lines between the
  55    lines starting with ===)
  56
  57 === begin example commit ===
  58 short explanation of the commit
  59
  60 Longer explanation explaining exactly what's changed, whether any
  61 external or private interfaces changed, what bugs were fixed (with bug
  62 tracker reference if applicable) and so forth. Be concise but not too brief.
  63 === end example commit ===
  64
  65  - Always add a brief description of the commit to the _first_ line of
  66    the commit and terminate by two newlines (it will work without the
  67    second newline, but that is not nice for the interfaces).
  68
  69  - First line (the brief description) must only be one sentence and
  70    must not start with a capital letter. Don't use a trailing period
  71    either.
  72
  73  - The main description (the body) is normal prose and should use normal
  74    punctuation and capital letters where appropriate. Normally, for patches
  75    sent to a mailing list it's copied from there.
  76
  77  - When committing code on behalf of others use the --author option, e.g.
  78    git commit -a --author "Joe Coder <joe@coder.org>"
  79
  80 Coding Style
  81 ===
  82
  83  - Please follow the coding style already used.
  84
  85  - Write docs for all functions and structs and so on. We use gtkdoc format.
  86
  87  - All external interfaces (network protocols, file formats, etc.)
  88    should have documented specifications sufficient to allow an
  89    alternative implementation to be written. Our implementation should
  90    be strict about specification compliance (should not for example
  91    heuristically parse a file and accept not-well-formed
  92    data). Avoiding heuristics is also important for security reasons;
  93    if it looks funny, ignore it (or exit, or disconnect).