HACKING.txt

   1 How to hack on Waffle
   2 =====================
   3
   4 How to submit patches
   5 ---------------------
   6 Do not send patches as email attachments.
   7
   8 Choose one of the below methods to submit patches to Waffle. Choose whichever
   9 method you feel most comfortable with.
  10
  11 - Sending invidual patches to the mailing list.
  12
  13   Suppose you want to submit the patches for your branch 'fix-sprocket' to the
  14   upstream branch 'master'.
  15
  16   > # Create temporary directory for your patches.
  17   > mkdir $tmp_patch_dir
  18   >
  19   > # Fill that temporary directory with patch emails.
  20   > git format-patch \
  21         -o $tmp_patch_dir \
  22         --subject-prefix="PATCH (master)" \
  23         --notes \
  24         --cover-letter \
  25         --thread=shallow \
  26         --to="waffle@lists.freedesktop.org" \
  27         origin/master..fix-sprocket
  28   >
  29   > # Edit the cover letter email and send to the mailing list.
  30   > $EDITOR $tmp_patch_dir/0000-cover-letter.patch
  31   > git send-email --cc-cover $tmp_patch_dir/*.patch
  32
  33 - Sending a pull request to the mailing list.
  34
  35   Create your pull request with 'git request-pull' and send to
  36   <waffle@lists.freedesktop.org>. Please format the email's subject line as:
  37
  38     Subject: [PULL ($upstream_branch)] $description_of_pull_request
  39
  40   where '$upstream_branch' is the destination upstream branch, such as 'master'
  41   or 'next'.
  42
  43 - Sending a pull request through GitHub.
  44
  45   TODO: If you know how to send GitHub pull requests , then please send a pull
  46   request that updates this file with instructions ;) .
  47
  48
  49 How to write commit messages
  50 ----------------------------
  51 The commit message is no less important than the code. So write it well.
  52
  53 The commit message should first convey the patch's *intent* or *motivation*,
  54 and secondly describe its *content*.  Usually the message should describe *why*
  55 the patch is needed, *how* it accomplishes its goal.
  56
  57 Example of a good commit message:
  58
  59     commit 7b2be42a92899ff6f857758e57656285168ba791
  60     Author: Emil Velikov <emil.l.velikov@gmail.com>
  61     Date:   Sat May 31 03:22:06 2014 +0100
  62
  63         cgl: avoid leaking the PixelFormat
  64
  65         According to apple developer page, starting with OS X v10.
  66         pixelformat is reference counted. The object is created at
  67         CGLChoosePixelFormat and should be unrefeferenced via
  68         CGLReleasePixelFormat/CGLDestroyPixelFormat.
  69
  70         The latter two are identical accoring to the documentation
  71
  72         Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
  73         Reviewed-by: Chad Versace <chad.versace@linux.intel.com>
  74
  75 The commit's subject line should begin with the name of the component it
  76 touches. Examples:
  77
  78     (commit 7b2be42) cgl: avoid leaking the PixelFormat
  79     (commit a643da0) wflinfo: silence signed/unsiged comparison warning
  80     (commit d78bd29) glx: glx_context_create_native returns GLXContext not bool
  81
  82 Try to keep the textwidth of your patch's commit message within 80 columns.
  83 Exceptions are unavoidable, however, so use common sense.
  84
  85
  86 Sign your work
  87 --------------
  88 Waffle follows the sign-off process of the Linux kernel.  This gives a clear
  89 chain of trust for every patch received.
  90
  91 Each patch submitted to Waffle requires a 'Signed-off-by' tag in the commit
  92 message. For example, below is a commit submitted by Emil:
  93
  94     commit 3413e4f32ac63679d685b686eee48442459ec835
  95     Author: Emil Velikov <emil.l.velikov@gmail.com>
  96     Date:   Fri Jul 4 04:15:02 2014 +0100
  97
  98         third_party/getopt: include BSD licensed getopt implementation
  99
 100         This module has been ripped out of the apitrace project
 101         https://github.com/apitrace/apitrace
 102
 103         Used by utils/wflinfo and examples/gl_basic.
 104
 105         Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
 106
 107 By placing your sign-off on a patch, you agree to the below certificate of
 108 origin [DCO-1.1], as found in the Linux kernel v3.15.
 109
 110     Developer's Certificate of Origin 1.1
 111
 112     By making a contribution to this project, I certify that:
 113
 114     (a) The contribution was created in whole or in part by me and I
 115         have the right to submit it under the open source license
 116         indicated in the file; or
 117
 118     (b) The contribution is based upon previous work that, to the best
 119         of my knowledge, is covered under an appropriate open source
 120         license and I have the right under that license to submit that
 121         work with modifications, whether created in whole or in part
 122         by me, under the same open source license (unless I am
 123         permitted to submit under a different license), as indicated
 124         in the file; or
 125
 126     (c) The contribution was provided directly to me by some other
 127         person who certified (a), (b) or (c) and I have not modified
 128         it.
 129
 130     (d) I understand and agree that this project and the contribution
 131         are public and that a record of the contribution (including all
 132         personal information I submit with it, including my sign-off) is
 133         maintained indefinitely and may be redistributed consistent with
 134         this project or the open source license(s) involved.
 135
 136
 137 Copyright
 138 ---------
 139 When making substantial changes to existing files, you may add yourself or your
 140 organization to that file's copyright header.
 141
 142 If adding new files, do not use a copyleft license (such as the GPL). All
 143 Waffle source code must be licensed under a liberal opensource license (such as
 144 BSD).  To reduce license proliferation, Waffle prefers (but does not require)
 145 that new code be licensed under one of the following licenses: BSD, MIT.
 146
 147
 148 References
 149 ----------
 150 [DCO-1.1] "Developer's Certificate of Origin 1.1".
 151     (https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches?id=v3.15#n332)