From a13f59e74355f85665e7445ebb4aeda17c3c6bc7 Mon Sep 17 00:00:00 2001 From: Malfurious Date: Fri, 13 Aug 2021 05:28:41 -0400 Subject: Document git submission process Signed-off-by: Malfurious --- www/contributing.html | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++ www/push-fail.png | Bin 0 -> 85187 bytes 2 files changed, 174 insertions(+) create mode 100644 www/contributing.html create mode 100644 www/push-fail.png 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 @@ + + + + + git contribution submission + + + + +
+ ! [rejected] (non-fast-forward)
+ <<<home +
+ +

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.

+ +
+ +

License

+

Unless otherwise specified, the content hosted here is released in + the public domain; specificly, according to the language of the + Unlicense. Some projects even make + this explicit by including a copy of the text in their source trees.

+ +

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.

+ +

Developer Certificate of Origin

+

Every contribution is expected to carry a + Developer Certificate of Origin + signoff statement. The DCO is an attestation that:

+ + + +

See the link above for the exact text of the DCO.

+ +

You can add a Signed-off-by trailer automatically while creating + commits, applying patches, or rebasing commits.

+ +
+ $ git commit -s
+ $ git am -s
+ $ git rebase --signoff +
+ +
+ +

Code Style

+

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:

+ + + +

Commit Messages

+

Format your commit messages according to + https://commit.style/ (written by + Tim Pope). Its text is given below:

+ +
+ Commit message style guide for Git

+ + The first line of a commit message serves as a summary. When displayed
+ on the web, it's often styled as a heading, and in emails, it's
+ typically used as the subject. As such, you should capitalize it and
+ omit any trailing punctuation. Aim for about 50 characters, give or
+ take, otherwise it may be painfully truncated in some contexts. Write
+ it, along with the rest of your message, in the imperative tense: "Fix
+ bug" and not "Fixed bug" or "Fixes bug". Consistent wording makes it
+ easier to mentally process a list of commits.

+ + Oftentimes a subject by itself is sufficient. When it's not, add a
+ blank line (this is important) followed by one or more paragraphs hard
+ wrapped to 72 characters. Git is strongly opinionated that the author
+ is responsible for line breaks; if you omit them, command line tooling
+ will show it as one extremely long unwrapped line. Fortunately, most
+ text editors are capable of automating this. +
+ +
+ +

Select your submission method

+ +

Patches via email

+

Ideal for small submissions / infrequent + contributors

+ +

Unless more specific advice is given by the project, send patches + directly to me: m@lfurio.us and include the + project name in the [PATCH] subject prefix, since the address is not a + dedicated list for any specific project.

+ +

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.

+ +

The -v option should be used when sending a + follow-up edit for a previous patch -- eg: -v2, -v3, -v4, etc...

+ +

For more information on this process, see + this resource or the manpages + for git-format-patch + or git-send-email. + See example command below:

+ +
+ $ git send-email --to=m@lfurio.us [-v<n>] origin/master \
+       --subject-prefix='PATCH <project_name>'

+ + # to include cover-letter, add:
+ --cover-letter --annotate +
+ + Assuming 'origin' refers to my public repository. + +

Pull request via email

+

Ideal for large submissions / frequent + contributors

+ +

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, + pull-new-feature-x.

+ +

It is strongly 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 may not be rejected for + this reason alone.

+ +

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.

+ +

Once everything is pushed, generate your request to send using + git-request-pull. + 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.

+ +

Copy the output text into an email message. Unless more specific + advice is given by the project, send PRs directly to me: + m@lfurio.us 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 + [GIT PULL <project_name>] ##Your PR subject here##.

+ +

See example commands below:

+ +
+ $ git tag -s pull-new-feature-x
+ $ git push --all --tags

+ + $ git request-pull origin/master fork pull-new-feature-x >pr.txt
+ # email contents of pr.txt +
+ + Assuming 'origin' refers to my public repository, + and 'fork' refers to yours. + + diff --git a/www/push-fail.png b/www/push-fail.png new file mode 100644 index 0000000..540cb37 Binary files /dev/null and b/www/push-fail.png differ -- cgit v1.2.3