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.
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.
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.
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.
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
[sendemail] smtpencryption = tls smtpserver = mail.example.org smtpuser = firstname.lastname@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.
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...].
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
-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~3includes the last three commits
origin/masterincludes all commits since diverging from
0fdbc0daonly includes commit
0fdbc0dawhen specified with
0fdbc0daand the 2 commits prior when specified with
--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.
You will likely receive replies to your email with feedback on your changes.
This is normal! Use tools like
git commit --amend and
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:
-v2to indicate that this is version 2 of your patch (or whatever number is appropriate).
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.
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
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
-v2 patch upstream when you're done - any conflicts you resolved, your
maintainer will have to address, too. Save them the time!
Here are a few extra tricks you might find useful with
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 email@example.com
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
git send-email, like
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'
If you're asked by a project to "sign off" on your commits, add
git send-email. To set it as the default for that git repository:
git config format.signOff yes
git config --global sendemail.annotate yes
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.
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
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.
In order to integrate the changes, you need to apply the patch. The tool for
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
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
push normally. Don't forget to send the contributor a thank you