diff options
Diffstat (limited to 'hg.sr.ht/email.md')
-rw-r--r-- | hg.sr.ht/email.md | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/hg.sr.ht/email.md b/hg.sr.ht/email.md new file mode 100644 index 0000000..9172f2c --- /dev/null +++ b/hg.sr.ht/email.md @@ -0,0 +1,238 @@ +sr.ht leverages mercurial'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 + +**Golden rule**: Do not copy-paste the output of `hg export` 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][sr.ht-dev] mailing list. + +[sr.ht-dev]: https://lists.sr.ht/~sircmpwn/sr.ht-dev + +Unsure if your setup is correct? Try sending the patch to sir@cmpwn.com for +feedback first - make sure you mention in the email that you want feedback. + +# For contributors + +## Preparing your changes + +There's no need to "fork" the repository you want to contribute to -- simply use +[`hg clone`][hg-clone] to obtain a local copy of the mercurial 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. + +[hg-clone]: https://www.mercurial-scm.org/doc/hg.1.html#clone +[work-normally]: https://book.mercurial-scm.org/read/ + +# 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 [`hg annotate`][hg-annotate] to find people who have recently +worked on similar code. + +[hg-annotate]: https://www.mercurial-scm.org/doc/hg.1.html#annotate + +# Configure hg email + +When you've collected a list of email addresses to send your work to, we can use +[`hg email`][hg-email] to do the job. Its purpose is to convert your mercurial +commits into emails with [`hg export`][hg-export] and connect to your mail +server to deliver them with SMTP. + +[hg-email]: https://www.mercurial-scm.org/doc/hg.1.html#email +[hg-export]: https://www.mercurial-scm.org/doc/hg.1.html#export + +If you've never used hg email before, you will need to do some one-time setup to +enable the `email` command (which isn't accessible by default, but is available +in the `patchbomb` extension which ships with Mercurial), and 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 +[mercurial's configuration file][hgrc]: + +[hgrc]: https://www.selenic.com/mercurial/hgrc.5.html + + [extensions] + patchbomb = + + [smtp] + host = mail.example.org + port = 587 + tls = smtps + username = you@example.org + +You can also set your SMTP password as `smtp.password`. If you don't, you +will be prompted for it when it's needed. + +## Send the patches along + +When you've configured `hg email`, completed your work, and you're ready to send +your patches in, you can run `hg email -r [rev]`. The `[rev]` here is the same +as any other [revision number, identifier, or name][hg-rev]. The command will +prepare a patch for that commit and send it through your mail server. + +A few things of note: + +- `hg email -o [dest]` will prepare patches for any revision not already in the + upstream `[dest]` repository (_i.e._ anything that would show up with `hg + outgoing [dest]`). If you have configured the `default` destination (in the + `[paths]` section), you can even just do `hg email -o`! +- `hg email -r tip` includes the last commit. +- You can use [revsets][hg-rev] to specify revision ranges, like, say, `hg + email -r 3000:3005` for sending patches for revisions 3000 through 3005. +- Add the `--confirm` option to give you an extra step to catch mistakes. + +[hg-rev]: https://www.mercurial-scm.org/doc/hg.1.html#specifying-revisions + +Mercurial might prompt you for more information before sending the email. For +instance, it might ask you what your email address is. Although it uses what it +found in your config's `ui.username`, it wants to be sure. You can skip that +step by setting the `email.from` option in your config too: + + [email] + from = Your Name <you@example.org> + +If you're sending more than one patch at once, Mercurial will ask you to write +an introduction email to the patch series. In many cases, this is unnecessary, +so you can optionally disable this feature in your config (you can always pass +`--intro` to `hg email` if you want it back): + + [patchbomb] + intro = never + +## Handling feedback + +You will likely receive replies to your email with feedback on your changes. +This is normal! Use tools like [`hg commit --amend`][amend] and [`hg +rebase`][hg-rebase] to continue improving your patch set and iterating on +feedback. When you're ready to submit the next version of your patches, use `hg +email` normally, except: + +- Add `--flag V2` to indicate that this is version 2 of your patch (or whatever + number is appropriate). +- Optionally, add `--in-reply-to [msgid]`, where `[msgid]` is 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. + +[hg-commit]: https://www.mercurial-scm.org/doc/hg.1.html#commit +[hg-rebase]: https://www.mercurial-scm.org/doc/hg.1.html#rebase + +## 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 work in progress or +unmerged changes in your history. To this end, you should generally use `hg pull +--rebase` to fetch the latest changes from upstream. + +## Extra tips + +Here are a few extra tricks you might find useful with `hg 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 destination address. Edit the project's +repository config (`.hg/hgrc`) with: + + [email] + 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 `--flags` to `hg email`. You can specify it +multiple times if you also need to specify `--flags V2`. For instance: + + hg email --flags 'example' -o + +You can also specify this as the default for that git repository by editing its +config (`.hg/hrc`): + + [patchbomb] + flagtemplate = example {flags} + +The `{flags}` placeholder indicates where other `--flags` will go in the email +subject (in thise case: after "`example`"). + +# 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 - mercurial records your email +with every commit, so someone with a copy of your mercurial 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 [`hg commit --amend`][hg-commit] and [`hg +rebase`][hg-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 [`hg import`][hg-import]. The difficult part here is going to be +obtaining a copy of the email to provide to `hg import`. Some clients like +[mutt][mutt] make this easy (in mutt, you can use the `|` key to pipe an email +directly to `hg import -`), or tools like [offlineimap][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. + +[hg-import]: https://www.mercurial-scm.org/doc/hg.1.html#import +[mutt]: http://www.mutt.org +[offlineimap]: http://www.offlineimap.org/ + +If you copy the link to the raw email from lists.sr.ht, you can pass that +directly to `hg import` and it will download it for you: + + hg import https://lists.sr.ht/... + +You can also just run `hg import -` paste the patch into it, followed by Ctrl+D. + +One applied, you can make these commits available upstream by using [`hg +push`][hg-push] normally. Don't forget to send the contributor a thank you +email! + +[hg-push]: https://www.mercurial-scm.org/doc/hg.1.html#push |