From 32a05647bd080c17d8586b68c8c031d6eb88218b Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Thu, 8 Apr 2021 09:11:42 -0400 Subject: git.sr.ht: add detailed send-email web instructions --- git.sr.ht/index.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) (limited to 'git.sr.ht/index.md') 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. + +
+ Head's up: git also has a built-in tool for preparing patches + to send upstream. Check out our tutorial + here. +
+ +### 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 — 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 — 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 — 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 — 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 -- cgit