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.
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.
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.
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.
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"
--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"
--annotate
option to modify the patches before sending them.--compose
option to add an introductory message to the patches
before sending them.--dry-run
option to test what git send-email
does without
actually sending any mails.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.
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.
commit b104302f8b09f2aa02ff9adb0b31d9f18ba3b2bb Author: Robin Krahl <robin.krahl@ireas.org> Date: 2020-09-22T14:26:30+02:00 Mention --annotate, --compose, --dry-run options