How to submit
-------------

Submit patches to waffle@lists.freedesktop.org.

Use `git send-email`. Don't send patches as attachments.


Commit messages
---------------

Try to keep the textwidth of your patch's commit message within 80 columns.

Prefix the patch's subject with the directory that it touches. For example:
    include: Fix comment for waffle_init()
If the patch touches multiple directories, then consider breaking it into
multiple patches; but don't take that advice too strictly.

The commit message should fully describe *why* the patch is needed, *how* it
accomplishes its goal, and *what* code it changes. Consider that most people
who will read your commit message will encounter it while exploring the git
log, and hence may not see the diff. The commit message should fully convey to
such a reader the patch's intent and content. Exceptions to this rule are 1)
trivial patches and 2) patches that add a large number of new files without
touching existing files.


Copyright
---------

If the patch adds a new file, the file must contain the BSD copyright
header.  Just copy the same header block used throughout Waffle. You may
assign the copyright to yourself, your organization, or Intel, Waffle's
dominant copyright holder.

If the patch substantially alters an existing file, you may add yourself or
your organization to that file's copyright holders.


Sign your work
--------------

A Signed-off-by tag is required for all patches.  I defer to the kernel's
discussion of this topic.

[Copied from the linux kernel, /Documentation/SubmittingPatches.]

To improve tracking of who did what, especially with patches that can
percolate to their final resting place in the kernel through several
layers of maintainers, we've introduced a "sign-off" procedure on
patches that are being emailed around.

The sign-off is a simple line at the end of the explanation for the
patch, which certifies that you wrote it or otherwise have the right to
pass it on as a open-source patch.  The rules are pretty simple: if you
can certify the below:

        Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (a) The contribution was created in whole or in part by me and I
            have the right to submit it under the open source license
            indicated in the file; or

        (b) The contribution is based upon previous work that, to the best
            of my knowledge, is covered under an appropriate open source
            license and I have the right under that license to submit that
            work with modifications, whether created in whole or in part
            by me, under the same open source license (unless I am
            permitted to submit under a different license), as indicated
            in the file; or

        (c) The contribution was provided directly to me by some other
            person who certified (a), (b) or (c) and I have not modified
            it.

	(d) I understand and agree that this project and the contribution
	    are public and that a record of the contribution (including all
	    personal information I submit with it, including my sign-off) is
	    maintained indefinitely and may be redistributed consistent with
	    this project or the open source license(s) involved.

then you just add a line saying

	Signed-off-by: Random J Developer <random@developer.example.org>

using your real name (sorry, no pseudonyms or anonymous contributions.)

Some people also put extra tags at the end.  They'll just be ignored for
now, but you can do this to mark internal company procedures or just
point out some special detail about the sign-off.

If you are a subsystem or branch maintainer, sometimes you need to slightly
modify patches you receive in order to merge them, because the code is not
exactly the same in your tree and the submitters'. If you stick strictly to
rule (c), you should ask the submitter to rediff, but this is a totally
counter-productive waste of time and energy. Rule (b) allows you to adjust
the code, but then it is very impolite to change one submitter's code and
make him endorse your bugs. To solve this problem, it is recommended that
you add a line between the last Signed-off-by header and yours, indicating
the nature of your changes. While there is nothing mandatory about this, it
seems like prepending the description with your mail and/or name, all
enclosed in square brackets, is noticeable enough to make it obvious that
you are responsible for last-minute changes. Example :

	Signed-off-by: Random J Developer <random@developer.example.org>
	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
	Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>

This practise is particularly helpful if you maintain a stable branch and
want at the same time to credit the author, track changes, merge the fix,
and protect the submitter from complaints. Note that under no circumstances
can you change the author's identity (the From header), as it is the one
which appears in the changelog.
