@@ 5,7 5,7 @@ guidelines and information to help you get started.
## Workflow
-The project is hosted primarily on Sourcehut, which uses an email-driven
+The project is hosted primarily on Sourcehut, which uses a largely email-driven
workflow. If that is something you're unfamiliar with, head over to the
[Workflow](docs/contributing/workflow.md) page for more information.
@@ 3,27 3,39 @@
Contributing to `bytes` is done primarily through email, which means that if
you have an email address and know how to send emails, you're already familiar
with 90% of `bytes`'s development workflow! The other 10% can be broken down
-into two things:
+as follows:
-* Knowing where to send emails.
-* Knowing how to work with patches.
+- How do I set up Git to use email?
+- Where do I send development emails?
+- How do I work with patches?
-## Mailing Lists and Trackers
+## How to Set Up Git
-In Sourcehut, emails go to one of two places: mailing lists or trackers.
-Generally, mailing lists are used for patches and discussions while trackers
-are used for issues and feature requests.
+To set up Git to use email, follow this super easy [guide](https://git-send-email.io/).
-Every `bytes` mailing list uses `lists.sr.ht` as its email domain, and every
-tracker uses `todo.sr.ht`. For example, a project made by `~john` could have a
-list at `~john/foo@lists.sr.ht` and a tracker at `~john/bar@todo.sr.ht>`.
+## Where to Send Emails
-You can find the various mailing lists and trackers for `bytes` below:
+Now that your Git can send emails, where do you send them? In Sourcehut, you
+send them to one of two places:
-* Patches & Discussion: [Mailing Lists](https://sr.ht/~satchmo/bytes/lists)
-* Bugs & Features: [Trackers](https://sr.ht/~satchmo/bytes/trackers)
+- **Mailing lists** — Patches and discussions.
+- **Trackers** — Issues and feature requests.
-## Patches
+The addresses of mailing lists and trackers on Sourcehut all follow the same
+convention: `<user>/<name>@(list|todo).sr.ht`, where `<user>` is the username
+of the project's owner and `<name>` is the name of the list or tracker. For
+example, `bytes`, owned by me (`~satchmo`), has a list at
+`~satchmo/bytes-devel@lists.sr.ht` and a tracker at
+`~satchmo/bytes@todo.sr.ht`.
+
+There can be multiple mailing lists and trackers for a single project on
+Sourcehut, so be sure to check their project page for more information. For
+`bytes`, you can find our various mailing lists and trackers below:
+
+- [Mailing Lists](https://sr.ht/~satchmo/bytes/lists)
+- [Trackers](https://sr.ht/~satchmo/bytes/trackers)
+
+## How to Send Patches
The general process for patch submission is as follows:
@@ 34,20 46,19 @@ The general process for patch submission is as follows:
5. **Send out a patch to the appropriate mailing list.**
Step 5 is the only part that may be unfamiliar to users coming from other
-workflows, so we'll focus on that. In short, `git-send-email` is your friend.
-The command takes care of creating and sending out patches; all you have to do
-is tell it where to send a patch and what commits should be included:
+workflows, so we'll focus on that.
+
+In short, use `git-send-email`. The command takes care of creating and sending
+out patches; all you have to do is tell it where to send and what commits
+should be included in the patch:
```sh
git send-email --to="~satchmo/bytes-devel@lists.sr.ht" <patch>
```
-Here, `<patch>` is typically a commit ID or [revision
-list](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection). If
-`<patch>` is a commit ID, you can optionally use the flag `-<N>`, where `<N>`
-is a number, to specify that you want to include the last `<N>` commits
-starting at `<patch>`. If `-<N>` is specified but `<patch>` is not provided,
-`HEAD` is used as the starting point.
+Here, `<patch>` is a [revision list](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection).
+Generally, you'll either specify a commit ID (e.g., `1066b58`) or an ancestry
+reference (e.g., `HEAD^`).
After the patch is sent, a maintainer will review it and push it upstream if
everything checks out. If there's a problem with your patch, simply fix any
@@ 96,6 107,6 @@ cover letter's "Subject" header appropriately.
## Resources
-* For a tutorial on sending patches: [git-send-email](https://git-send-email.io/)
-* For general guidelines on email etiquette: [man.sr.ht](https://man.sr.ht/lists.sr.ht/etiquette.md)
-* For more information on Git revision lists: [git-scm](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection)
+- For a tutorial on sending patches: [git-send-email](https://git-send-email.io/)
+- For general guidelines on email etiquette: [man.sr.ht](https://man.sr.ht/lists.sr.ht/etiquette.md)
+- For more information on Git revision lists: [git-scm](https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection)