diff options
Diffstat (limited to 'www/contributing.html')
| -rw-r--r-- | www/contributing.html | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/www/contributing.html b/www/contributing.html new file mode 100644 index 0000000..7a31a08 --- /dev/null +++ b/www/contributing.html @@ -0,0 +1,174 @@ +<!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 --all --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> |