This document explains how to contribute to my projects that are hosted on Sourcehut.

Sourcehut is a software forge that provides Git and Mercurial hosting, continuous integration, mailing lists, issue tracking and more. You can use most of its features via the web interface, a mail-based workflow or the API. For more information, see man.sr.ht.

#Mailing Lists

All projects use mailing lists for discussions and patch submissions. The archives of the mailing lists are public. Most projects use a shared mailing list, ~ireas/public-inbox@lists.sr.ht (archive). Some projects have their own mailing list. To find out which mailing list to use, check the project’s readme or follow the “mailing list” tab in the project directory.

When sending a mail to the shared mailing list, please make sure to add the project name as a prefix to the subject of your message, for example [merge-rs] or [PATCH merge-rs] for the merge-rs project.

#Submitting Patches

Please submit patches to the project’s mailing list. The preferred way to do that is git send-email (see this step-by-step guide for more information).

Alternatively, you can push your changes to a public repository, for example hosted on your own Git server, on Sourcehut, Gitlab or GitHub, and use git request-pull to send a pull request to the mailing list.

If these options don’t work for you, just use your mail client to send a mail with a link to your changes and a short description to the mailing list.

#git send-email Example

This example shows how to prepare a patch for the merge-rs project. First you have to check out the Git repository and configure the mailing list address and the subject prefix:

$ git clone https://git.sr.ht/~ireas/merge-rs && cd merge-rs
$ git config sendemail.to "~ireas/public-inbox@lists.sr.ht"    # see README.md
$ git config format.subjectPrefix "PATCH merge-rs"             # only when sending to ~ireas/public-inbox@lists.sr.ht

Then you can make your changes, for example:

$ echo test > test.txt
$ git add test.txt
$ git commit -m "Test"

Use git send-email to generate a patch for the last commit and to send it to the mailing list:

$ git send-email HEAD^

This example assumes that you have already configured git send-email for sending mails.

#Tips for git send-email

• Use the sendemail.to configuration option to set the mail address for your patch submissions, for example:

  $ git config sendemail.to "~ireas/public-inbox@lists.sr.ht"
  

• Use the --subject-prefix option or the format.subjectPrefix configuration option to add the project name to the subject prefix when submitting a patch to the shared mailing list (public inbox):

  $ git send-email --subject-prefix "PATCH merge-rs" ...
  $ git config format.subjectPrefix "PATCH merge-rs"
  

• Use the --annotate option to modify the patches before sending them.
• Use the --compose option to add an introductory message to the patches before sending them.
• Use the --dry-run option to test what git send-email does without actually sending any mails.

#Continuous Integration

Most projects use continuous integration to check the commits. The CI jobs are triggered by pushing to the Git repository and are listed on builds.sr.ht. If activated for the project, the checks are also executed for all patches that have been submitted to the mailing list.

The configuration for the build jobs is stored in the .builds directory of the project repository.

#Contact

If you have any questions, please contact me – either using my public inbox or my private mail address (PGP key).

The source code of this guide is available in the guides repository. Contributions are welcome! Please send patches to ~ireas/public-inbox@lists.sr.ht using the [PATCH guides] subject prefix.