<!DOCTYPE html>
<html>
<head>
<title>git contribution submission</title>
<link type="text/css" rel="stylesheet" href="style.css" />
</head>
<body>
<div class="heading">
<img src="push-fail.png" alt="! [rejected] (non-fast-forward)" /><br />
<a href="/"><<<home</a>
</div>
<p>Thanks for your interest in contributing to my projects! This
document describes the patch submission process, my expectations for
submissions, and contains information to know before getting started.</p>
<hr />
<h1>License</h1>
<p>Unless otherwise specified, the content hosted here is released in
the public domain; specificly, according to the language of the
<a href="https://unlicense.org/">Unlicense</a>. Some projects even make
this explicit by including a copy of the text in their source trees.</p>
<p>In general, by contributing, you agree that the contribution is made
available to me, and to the public, under the terms of the applicable
license. If in doubt, check with a file named UNLICENSE, LICENSE, or
COPYING in the project source tree.</p>
<h2>Developer Certificate of Origin</h2>
<p>Every contribution is expected to carry a
<a href="https://developercertificate.org/">Developer Certificate of Origin</a>
signoff statement. The DCO is an attestation that:</p>
<ul>
<li>The contribution is your own</li>
<li>You have the right to submit it per the effective license</li>
<li>You irrevocably grant permission for it to be used and recorded</li>
</ul>
<p>See the link above for the exact text of the DCO.</p>
<p>You can add a Signed-off-by trailer automatically while creating
commits, applying patches, or rebasing commits.</p>
<div class="literal">
$ git commit -s<br />
$ git am -s<br />
$ git rebase --signoff
</div>
<hr />
<h1>Code Style</h1>
<p>There are no global, hard-and-fast rules on code style. However,
patches may not be accepted if they are much different than their
surrounding context. Beyond that, keep the following preferences in
mind:</p>
<ul>
<li>4-space indents, instead of tabs</li>
<li>Linebreaks at 80 characters, if possible</li>
</ul>
<h1>Commit Messages</h1>
<p>Format your commit messages according to
<a href="https://commit.style/">https://commit.style/</a> (written by
<a href="https://tpo.pe/">Tim Pope</a>). Its text is given below:</p>
<div class="literal">
Commit message style guide for Git<br /><br />
The first line of a commit message serves as a summary. When displayed<br />
on the web, it's often styled as a heading, and in emails, it's<br />
typically used as the subject. As such, you should capitalize it and<br />
omit any trailing punctuation. Aim for about 50 characters, give or<br />
take, otherwise it may be painfully truncated in some contexts. Write<br />
it, along with the rest of your message, in the imperative tense: "Fix<br />
bug" and not "Fixed bug" or "Fixes bug". Consistent wording makes it<br />
easier to mentally process a list of commits.<br /><br />
Oftentimes a subject by itself is sufficient. When it's not, add a<br />
blank line (this is important) followed by one or more paragraphs hard<br />
wrapped to 72 characters. Git is strongly opinionated that the author<br />
is responsible for line breaks; if you omit them, command line tooling<br />
will show it as one extremely long unwrapped line. Fortunately, most<br />
text editors are capable of automating this.
</div>
<hr />
<h1>Select your submission method</h1>
<h2>Patches via email</h2>
<p class="note" align="center">Ideal for small submissions / infrequent
contributors</p>
<p>Unless more specific advice is given by the project, send patches
directly to me: <span class="note">m@lfurio.us</span> and include the
project name in the [PATCH] subject prefix, since the address is not a
dedicated list for any specific project.</p>
<p>It is recommended to include a cover-letter when sending multiple
commits, though this is not required. Keep in mind that the
cover-letter contents do not get recorded in the commit history.</p>
<p>The <span class="note">-v</span> option should be used when sending a
follow-up edit for a previous patch -- eg: -v2, -v3, -v4, etc...</p>
<p>For more information on this process, see
<a href="https://git-send-email.io/">this resource</a> or the manpages
for <a href="https://git-scm.com/docs/git-format-patch">git-format-patch</a>
or <a href="https://git-scm.com/docs/git-send-email">git-send-email</a>.
See example command below:</p>
<div class="literal">
$ git send-email --to=m@lfurio.us [-v<n>] origin/master \<br />
--subject-prefix='PATCH <project_name>'<br /><br />
# to include cover-letter, add:<br />
--cover-letter --annotate
</div>
<i>Assuming 'origin' refers to <strong>my</strong> public repository.</i>
<h2>Pull request via email</h2>
<p class="note" align="center">Ideal for large submissions / frequent
contributors</p>
<p>This method will require you to push your commits to a
publicly-accessible git repository, along with an annotated tag
associated with your pull request. Your tag should have a descriptive
name which I prefer to begin with the word 'pull'. For example,
<span class="note">pull-new-feature-x</span>.</p>
<p>It is <strong>strongly</strong> preferred that your tag be signed by
a PGP key whose name and email match the address you are sending the
request from. However, your request <em>may</em> not be rejected for
this reason alone.</p>
<p>Please write a descriptive message in the body of the git tag,
following the same style for commit messages. This message will be
recorded in the git commit history (via the merge commit) and should
summarize the changes introduced by your branch.</p>
<p>Once everything is pushed, generate your request to send using
<a href="https://git-scm.com/docs/git-request-pull">git-request-pull</a>.
Giving it the correct 'start' revision is important, so that the
generated log and diffstat are accurate. Remember to use your tag name
for 'end' instead of master or HEAD.</p>
<p>Copy the output text into an email message. Unless more specific
advice is given by the project, send PRs directly to me:
<span class="note">m@lfurio.us</span> and include the project name in
the [GIT PULL] subject prefix, since the address is not a dedicated
list for any specific project. The full subject line should look like
<span class="note">[GIT PULL <project_name>] ##Your PR subject here##</span>.</p>
<p>See example commands below:</p>
<div class="literal">
$ git tag -s pull-new-feature-x<br />
$ git push --tags<br /><br />
$ git request-pull origin/master fork pull-new-feature-x >pr.txt<br />
# email contents of pr.txt
</div>
<i>Assuming 'origin' refers to <strong>my</strong> public repository,
and 'fork' refers to <strong>yours</strong>.</i>
</body>
</html>
