diff options
Diffstat (limited to 'git.sr.ht/send-email.md')
| -rw-r--r-- | git.sr.ht/send-email.md | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/git.sr.ht/send-email.md b/git.sr.ht/send-email.md new file mode 100644 index 0000000..db259d8 --- /dev/null +++ b/git.sr.ht/send-email.md @@ -0,0 +1,221 @@ +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][sr.ht-discuss] mailing list for +help. + +[sr.ht-discuss]: https://lists.sr.ht/~sircmpwn/sr.ht-discuss + +# 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][sr.ht-dev] mailing list. + +[sr.ht-dev]: https://lists.sr.ht/~sircmpwn/sr.ht-dev + +# For contributors + +## Preparing your changes + +There's no need to "fork" the repository you want to contribute to - simply use +[`git clone`][git-clone] to obtain a local copy of the git repository and [work +normally][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. + +[git-clone]: https://www.git-scm.com/docs/git-clone +[work-normally]: https://www.git-scm.com/book/en/v2 + +## 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](/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`][git-blame] to find people who have recently +worked on similar code. + +[git-blame]: https://www.git-scm.com/docs/git-blame + +## Configure git send-email + +When you've collected a list of email addresses to send your work to, we can use +[`git send-email`][git-send-email] to do the job. Its purpose is to convert your +git commits into emails with [`git format-patch`][git-format-patch] and connect +to your mail server to deliver them with SMTP. + +[git-send-email]: https://www.git-scm.com/docs/git-send-email +[git-format-patch]: https://www.git-scm.com/docs/git-send-email + +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][gmail]. + +[gmail]: https://www.git-scm.com/docs/git-send-email#_use_gmail_as_the_smtp_server + +You can also set your SMTP password as `sendemail.smtppass`. If you don't, you +will be prompted for it it's needed. You can also configure it to use your local +keyring; consult [`git credential`][git-credential] for details. + +[git-credential]: https://www.git-scm.com/docs/git-credential + +## 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-list...]`. +The `rev-list` is the same as any other [revision specification][rev-spec]. 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 you've authored since diverging from + `origin/master` + +[rev-spec]: https://www.git-scm.com/docs/gitrevisions + +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 should 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. +If you're sending a few patches, 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 +the first time you send the patch. + +## Handling feedback + +You will likely receive replies to your email with feedback on your changes. +This is normal! Use tools like [`git commit --amend`][amend] and [`git +rebase`][git-rebase] to continue curating your patch set and iterating on +feedback (tip: check out our [rebase guide][rebase.md]). 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. + +[amend]: https://www.git-scm.com/docs/git-commit#git-commit---amend +[git-rebase]: https://www.git-scm.com/docs/git-rebase + +## 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](/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`][amend] and [`git +rebase`][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`][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][mutt] make +this easy (in mutt, you can use the `|` key to pipe an email directly to `git +am`) or tools like [offlineimap][offlineimap] (or a combination of the two!). +Most popular end-user clients do not. 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. + +[git-am]: https://www.git-scm.com/docs/git-am +[mutt]: http://www.mutt.org +[offlineimap]: http://www.offlineimap.org/ + +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`][git-push] normally. Don't forget to send the contributor a thank you +email! + +[git-push]: https://www.git-scm.com/docs/git-push |