sr.ht leverages git's built-in collaboration tools for contributing to projects hosted here. This guide will help you get started. If you run into any trouble, please send an email to the sr.ht-discuss mailing list for help.

Golden rule: Do not copy-paste the output of git format-patch into your typical mail client.

For everyone

Before you dig too far into this guide, you should make sure that your email client is configured to use plain text emails. By default, many email clients compose emails with HTML, so you can use rich text formatting. Rich text is not desirable for development-oriented email conversations, so you should disable this feature and send your email as "plain text". Every email client is different, you should research the options for your specific client. HTML emails are rejected by all sr.ht services.

For real-world examples of how the discussions described in this document play out, check out the sr.ht-dev mailing list.

For contributors

Preparing your changes

There's no need to "fork" the repository you want to contribute to - simply use git clone to obtain a local copy of the git repository and work normally. Be deliberate about your commits - use meaningful commit messages and take special care to commit your work in the form of logically separate changes. When it comes time to review your work, your commit history is an important tool for the reviewer and will be closely examined.

Find out where to send your changes

This workflow is optional for projects hosted on sr.ht and each project will have different requirements - review them carefully. To use this guide, you need to find an email address to send your work to - this will often be a mailing list on lists.sr.ht. You will also want to find people who can help review your changes - look for dedicated maintainers for the modules you're working on, or use git blame to find people who have recently worked on similar code.

Configure git send-email

When you've collected a list of email addresses to send your work to, we can use git send-email to do the job. Its purpose is to convert your git commits into emails with git format-patch and connect to your mail server to deliver them with SMTP.

If you've never used git send-email before, you will need to do some one-time setup to introduce it to your SMTP server. The connection details vary between mail providers, but you're looking for information which is suitable for filling out these config fields in ~/.config/git/config:

[sendemail]
    smtpencryption = tls
    smtpserver = mail.example.org
    smtpuser = you@example.org
    smtpserverport = 587

Note: G-Mail users have to take some extra steps, which are documented here.

Note: Protonmail users are advised to use Hydroxide to extend Protonmail with SMTP support, and to choose mail services which support standard, open protocols in the future.

You can also set your SMTP password as sendemail.smtppass. If you don't, you will be prompted for it when it's needed. You can also configure git to use your local keyring; consult git credential for details.

Send the patches along

When you've configured git send-email, completed your work, and you're ready to send your patches in, you can run git send-email --annotate [rev-spec...]. The rev-spec is the same as any other revision specification, and send-email will prepare patches from that commit to the tip (unless you specify -1, -2, etc, in which case it will prepare up to that many patches). If you're in a hurry, here are a few quick examples:

  • HEAD^ just includes the last commit
  • HEAD~3 includes the last three commits
  • origin/master includes all commits since diverging from origin/master
  • 0fdbc0da only includes commit 0fdbc0da when specified with -1
  • 0fdbc0da includes commit 0fdbc0da and the 2 commits prior when specified with -3

The --annotate flag will open the emails in your text editor before sending them out. You should take a moment to review these. The subject line and everything above the --- are your commit message, and everything below the --- is the patch itself. Immediately following the ---, you can add what we call "timely commentary" - any information which is useful to the people reviewing your patch, but doesn't necessarily belong in the final git history; plus a blank line between this and the start of the patch. If you're sending a few patches at once, you might also want to specify --cover-letter, which will prepare an additional email summary to be sent first.

Note: When you're prompted for an "In-Reply-To" header, you can ignore it for now.

Handling feedback

You will likely receive replies to your email with feedback on your changes. This is normal! Use tools like git commit --amend and git rebase to continue improving your patch set and iterating on feedback (tip: check out our rebase guide). When you're ready to submit the next version of your patches, use git send-email normally, except:

  • Add -v2 to indicate that this is version 2 of your patch (or whatever number is appropriate).
  • When prompted to fill out In-Reply-To, paste in the message ID of the last email in the thread. On lists.sr.ht you can get this by clicking "details" on the email in question. If you can't find this, don't sweat it, it's no big deal.

Pulling from upstream

As you continue to work, you may want to pull from the upstream, and you almost certainly don't want to create a merge commit when you have WIP or unmerged patches in your history. To this end, you should generally use git pull --rebase to fetch the latest changes from upstream.

If you get a conflict, read the information git prints. You have two choices - skip the patch or fix it. If your patch has already been merged, the maintainer likely made some minor changes that prevents git from detecting it's the same commit you have locally - in this case, just git rebase --skip the patch. If your patch still hasn't been merged upstream, you should resolve the conflicts in your editor, using git add some/file.c to mark the conflicts as resolved, and then using git rebase --continue to move on. You will probably want to send a -v2 patch upstream when you're done - any conflicts you resolved, your maintainer will have to address, too. Save them the time!

Extra tips

Here are a few extra tricks you might find useful with git send-email.

Sending emails to the same address every time

If you send emails for a project to the same mailing list every time, you might find it useful to set the default To address. Run this command from that repository:

git config sendemail.to patches@example.org
Specifying a subproject for shared lists

Some projects have several repositories being discussed on a single mailing list, and it's often helpful to specify the particular repository your patch pertains to.

If you're just doing this once, add --subject-prefix to git send-email, like so:

git send-email --subject-prefix='PATCH example' HEAD^

You can also specify this as the default for that git repository:

git config format.subjectPrefix 'PATCH example'
Signing off on your commits

If you're asked by a project to "sign off" on your commits, add --signoff (or -s) to git send-email. To set it as the default for that git repository:

git config format.signOff yes
Using --annotate every time
git config --global sendemail.annotate yes

For maintainers

Tell people how to contribute

The first thing you need to do is help potential contributors figure out how to contact you. The easiest way is to do nothing - git records your email with every commit, so someone with a copy of your git repository can figure out how to contact you. You'll probably want to make it a bit easier on them, though.

We recommend setting up a mailing list on lists.sr.ht for this purpose. Once you do, you will get an email address for contributors to submit patches to. Write this into your docs! You will probably also want to link to the archives so that potential contributors can read other people's work to get a feel for your submission process.

Reviewing patches

When a patch comes in, you should review it carefully. Read the code, apply the patch locally and make sure it compiles, test the changes, and so on. During this process you'll probably come up with feedback on the patch. Pull open that email client and compose a reply to the patch author. When your client composes the reply, don't be afraid to slice and dice the email you're replying to - trim out the fat and only include specific lines that you want to comment on.

If you only have small comments here and there, feel free to make the changes yourself, again utilizing git commit --amend and git rebase to your heart's content. You may be wise to point out these small errors when you thank the submitter for their patch, however, if you don't want to see the same errors in future patches.

Applying patches

In order to integrate the changes, you need to apply the patch. The tool for this is git am. The difficult part here is going to be obtaining a copy of the email to provide to git am. Some clients like mutt make this easy (in mutt, you can use the | key to pipe an email directly to git am), or tools like offlineimap can help (or a combination of the two!). Most popular end-user clients do not provide this option. If you're in this boat, the easiest way to get a raw email is to use the "raw" link on lists.sr.ht, which is hidden away under the "details" button.

If you copy the link to the raw email from lists.sr.ht, the command might look like this:

curl -s https://lists.sr.ht/... | git am

You can also just run git am alone and paste the patch into it, followed by Ctrl+D. You can then make these commits available upstream by using git push normally. Don't forget to send the contributor a thank you email!

Table of Contents

This commit

commit 118d9ed010807a82b1f4a1f772040971132568cc
Author: Euan Torano <euan@torano.co.uk>
Date:   2018-12-05T01:41:06

Spelling and structural changes for Git documentation.

Fixed some minor spelling mistakes in the index of the Git documentation, and fixed what appears to be an incorrect heading level.
Clone this wiki
man@man.sr.ht:root
https://man.sr.ht/root