~sircmpwn/sr.ht-docs

32a05647bd080c17d8586b68c8c031d6eb88218b — Drew DeVault 5 days ago 04e3e40
git.sr.ht: add detailed send-email web instructions
1 files changed, 89 insertions(+), 0 deletions(-)

M git.sr.ht/index.md
M git.sr.ht/index.md => git.sr.ht/index.md +89 -0
@@ 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