git.sr.ht: add detailed send-email web instructions

1 files changed, 89 insertions, 0 deletions

diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md
index 104607b..47f6e36 100644
--- a/git.sr.ht/index.md
+++ b/git.sr.ht/index.md
@@ -49,6 +49,95 @@ a friendly email if we notice that you're using too much.
 
 The following sections document various features of git.sr.ht.
 
+## Sending patches upstream
+
+git.sr.ht provides a web-based patch preparation UI, which you can use to
+prepare changes to send upstream online. You can even use this to prepare
+patches for projects which use email for submission, but are not hosted on
+SourceHut. This tool may be helpful to users who are used to the "pull request"
+style contribution popularized by GitHub, GitLab, and others.
+
+<div class="alert alert-info">
+  <strong>Head's up:</strong> git also has a built-in tool for preparing patches
+  to send upstream. <a href="https://git-send-email.io">Check out our tutorial
+  here</a>.
+</div>
+
+### 1. Getting the source onto git.sr.ht
+
+If the project is already on git.sr.ht, look for the large blue "Clone repo to
+your account" button to add a copy of it to your git.sr.ht repos. If the project
+is hosted elsewhere, clone the upstream source code and [add it to git.sr.ht
+like any other repository](/tutorials/set-up-account-and-git.md).
+
+Write your changes locally with your normal workflow. We recommend studying [git
+rebase](https://git-rebase.io) as well, because many projects which use the
+email-based workflow may expect you to be proficient with it. When you've
+completed your work, push it to your git.sr.ht repository.
+
+### 2. Preparing the patchset
+
+On the git.sr.ht website, visit your repository's summary page, and the large
+blue button is replaced with "Prepare a patchset". Click this to start up the
+patchset editor.
+
+On the first page, you'll select the *oldest* commit to include in the
+patchset. Click "Continue" to select the *newest* commit to include &mdash; the
+default is probably correct. On this second page, you can add some notes to the
+patchset. Here's an explanation of the options:
+
+**Add a cover letter**
+
+A cover letter is added ahead of your patchset. It includes a brief
+auto-generated summary of the changes, and gives you an opportunity to add any
+notes or set a subject line for the whole patchset. If you're coming from
+GitHub, think of this as settting the pull request title and description.
+
+**Add commentary**
+
+For each commit that you include, you have a space to add some notes specific to
+that commit. The notes you add here supplement the commit message with
+additional details which are useful for the reviewer, but shouldn't be
+immortalized in the commit log.
+
+**Patchset revision**
+
+After you receive feedback (see below), you'll want to update ths number to
+reflect how many revisions you've sent upstream. You can leave this at "1" for
+the first submission.
+
+### 3. Sending it upstream
+
+After reviewing all of the details, click "Continue" to proceed to the final
+step. You'll have to figure out who the emails should be sent to before
+completing this step. Most projects have a mailing list address listed in their
+contributor documentation &mdash; find that and stick it in the "To" box. You
+might also want to use tools like [git blame](https://www.git-scm.com/docs/git-blame)
+to find other people who have recently worked in relevant parts of the code, and
+add them to the "Cc" field.
+
+Have one more quick look over the emails that have been prepared for you (you
+can press "back" in your browser to revise any mistakes), then hit "Send
+patchset" to send your work to the email addresses you've listed. You're done!
+
+### 4. How to deal with feedback
+
+When the reviewers look over your work, they may have some comments for things
+that you should change or clarify. Comments will arrive at your email address,
+and you can simply reply to them to answer their questions or provide follow-up
+questions of your own. Please double check our [email ettiquite
+guide](https://man.sr.ht/lists.sr.ht/etiquette.md) to avoid any faux paus!
+
+To incorporate their feedback, you'll want to edit the commits in your git
+repository. Note that you need to *edit* your commits &mdash; you can't just add
+new commits which fix the issues introduced by earlier commits. Check out our
+[git rebase](https://git-rebase.io) guide if you're not comfortable with this
+workflow. Once you're satisfied with your changes, use `git push -f` to push the
+new commits up to your repository on git.sr.ht, and follow this procedure again
+to send the new version. Update the **patchset revision** field on step two when
+you get there &mdash; set it to the number of patchset versions you've sent so
+far.
+
 ## Attaching files to releases
 
 git.sr.ht allows you to attach files, such as executables (aka binaries), PGP