M index.md => index.md +3 -0
@@ 29,6 29,7 @@ Here are the list of services we currently have running:
- [git.code.netlandish.com][nlgit] - Git Repo Hosting
- [meta.code.netlandish.com][nlmeta] - Account Management
- [todo.code.netlandish.com][nltodo] - Issue Trackers
+- [lists.code.netlandish.com][nllists] - Mailing Lists
- [man.code.netlandish.com][nlman] - Wiki Hosting (Where you're reading this)
@@ 38,6 39,7 @@ Here are some service specific docs:
- [Mercurial Docs](/hg)
- [Git Docs](/git)
+- [Mailing Lists](/lists)
**Note:** This platform is still very new, even to us, and the docs are very
limited. While this platform is mostly for the Netlandish staff and family
@@ 58,4 60,5 @@ updates.
[nlgit]: https://git.code.netlandish.com
[nlmeta]: https://meta.code.netlandish.com
[nltodo]: https://todo.code.netlandish.com
+[nllists]: https://lists.code.netlandish.com
[nlman]: https://man.code.netlandish.com
A lists/etiquette.md => lists/etiquette.md +88 -0
@@ 0,0 1,88 @@
+---
+title: Mailing list etiquette
+---
+
+**Note:** This document was taken from the [sourcehut documentation][srht].
+It's been adapted to fit our setup where appropriate.
+
+[srht]: https://man.sr.ht/lists.sr.ht/etiquette.md
+
+Some email clients have popularized email usage patterns which are considered
+poor form on many mailing lists, including code.netlandish.com. Please review
+some of our suggestions for participating more smoothly in discussions on the
+platform. This advice will likely serve you well outside of
+code.netlandish.com as well. Thank you for taking the time to adjust your
+habits!
+
+# Plain text
+
+Please make sure that your email client is configured to use plain text emails.
+By default, many email clients compose emails with HTML, so you can use rich
+text formatting. Rich text is not desirable for development-oriented email
+conversations, so you should disable this feature and send your email as "plain
+text". Every email client is different, you should research the options for
+your specific client. HTML emails are rejected by all code.netlandish.com
+services.
+
+To learn about recommended clients for plaintext users and how to setup
+plaintext with your email client check out our guide at
+[useplaintext.email](https://useplaintext.email/).
+
+# Top-posting
+
+Some email clients will paste the entire email you're replying to into your
+response and encourage you to write your message over it. This behavior is
+called "top posting" and is discouraged on code.netlandish.com. Instead, cut
+out any parts of the reply that you're not directly responding to and write
+your comments inline. Feel free to edit the original message as much as you
+like. For example, if I emailed you:
+
+ Hey Casey,
+
+ Can you look into the bug which is causing 2.34 clients to disconnect
+ immediately? I think this is related to the timeouts change last week.
+
+ Also, your fix to the queueing bug is confirmed for the next release,
+ thanks!
+
+You might respond with:
+
+ Hey Drew, I can look into that for sure.
+
+ > I think this is related to the timeouts change last week.
+
+ I'm not so sure. I think reducing the timeouts would *improve* this issue,
+ if anything.
+
+ > Also, your fix to the queueing bug is confirmed for the next release,
+ > thanks!
+
+ Sweet! Happy to help.
+
+- A: Because it reverses the logical flow of conversation.
+- Q: Why is top posting frowned upon?
+
+# Wrap lines
+
+Please wrap lines in your email at 72 columns. Many people use email readers
+designed to faithfully display plaintext and won't break lines at a width which
+is comfortable for reading, or won't break lines at all, which is useful when
+reviewing patches. Some readers also have many things open in addition to their
+mail client, and may not allocate as much screen real-estate to email as you do.
+
+Don't worry about re-wrapping lines written by anyone you're quoting unless you
+want to.
+
+# PGP Signatures
+
+If you use PGP, please attach your signature to the message instead of using an
+inline signature. Look in your local PGP implementation's documentation for
+`PGP/MIME` options.
+
+# Patches
+
+To learn about using email for sending patches, check out our docs for
+contributing patches for [Mercurial](../hg/email.md) or [Git](../git/email.md).
+
+To see a more in-depth tutorial for git, check out
+[git-send-email.io](https://git-send-email.io).
A lists/index.md => lists/index.md +120 -0
@@ 0,0 1,120 @@
+---
+title: lists.code.netlandish.com docs
+---
+
+[lists.code.netlandish.com][lists] is the code.netlandish.com mailing list
+service.
+
+[lists]: https://lists.code.netlandish.com
+
+**Note:** This document was taken from the [sourcehut documentation][srht].
+It's been adapted to fit our setup where appropriate.
+
+[srht]: https://man.sr.ht/lists.sr.ht/
+
+# New to mailing lists?
+
+We have some resources for you:
+
+- [Mailing list etiquette](etiquette.md)
+
+If you plan on contributing patches, we also have these guides:
+
+- [Using git-send-email for sending and reviewing patches](../git/email.md)
+- [Using hg-email for sending and retrieving patches](../hg/email.md)
+
+# lists.code.netlandish.com manual
+
+The following sections document various features of lists.code.netlandish.com.
+
+# Posting
+
+You may post to a list that you have posting permissions on by writing a
+plaintext email to `~user/list-name@lists.code.netlandish.com`. If your MTA
+doesn't support characters like ~ and / in emails, please write to
+postmaster@your-mta.com asking them to fix the bug, then use
+`u.username.list-name@lists.code.netlandish.com` instead.
+
+# Email controls
+
+You may subscribe to any list by emailing
+`~user/list-name+subscribe@lists.code.netlandish.com`. You may unsubscribe with
+`+unsubscribe`. You may post new threads to this list by writing to the address
+with no `+` command.
+
+# Dashboard
+
+Your [dashboard][lists] shows you recent emails on mailing lists
+you're subscribed to. You can reply to one by clicking the author's name, or
+view the thread by clicking the subject.
+
+# Profile
+
+Your public profile page shows a feed of emails authored by you, as well as a
+list of mailing lists you administrate. Like the dashboard, emails can be
+replied to by clicking the authors name and you can view the thread by clicking
+the subject.
+
+# Archive
+
+Each list shows a list of archives, sorted by which has seen the most recent
+activity. In each thread's heading, you can see the number of participants,
+number of replies, and subject of the initial message. Click the subject to see
+the full thread.
+
+## Search filters
+
+List archives can be searched using the search bar at the top. Filters that can
+be used include:
+
+- `from:` the author of the message. Use `me` to search for messages sent by
+yourself
+- `is:patch` only show messages that contain a patch
+- `In-Reply-To:` show messages that are replies to a given message ID
+- `message-id:` find message with a given message ID
+- Other arbitrary mail headers can be used
+
+Search terms can be surrounded by double-quotes to return exact matches.
+
+# Threads
+
+Email threads can become trees as participants reply to different messages. In
+the simple case of a linear thread, you will see replies written linearly.
+However, if a thread becomes split, you may see several linear trees of
+discussion form.
+
+To reply to a message, click the author's email address.
+
+## Downloading messages
+
+Additionally, messages in the thread can be downloaded in raw form, either
+individually or as a whole in an mbox format. This is useful for applying
+submitted patches via `git am`/`hg import` among other uses.
+
+Raw individual messages can be found by clicking on "Details" and following
+the link there.
+
+Mbox files can be downloaded by clicking on "Export thread (mbox)" on the
+sidebar.
+
+# List Administration
+
+List access controls are available on your list settings, which can be accessed
+with the "List settings" button on the list archive. The controls are
+fine-grained enough to support many access scenarios, here are some examples:
+
+## Announcement lists
+
+A list that only you can write to is useful for announcements. Remove all user's
+"post" and "reply" permissions to prevent them from submitting - owners are
+always able to post. You can optionally leave the "reply" permission enabled to
+allow people to respond to announcements, but be aware that their responses will
+be sent out to all subscribers, which is usually undesirable for low-volume
+announcement lists.
+
+## Write-only security lists
+
+If you want a mailing list where people can write to you about security
+vulnerabilities in your software, you can remove the "browse" permission without
+removing the "post" or "reply" permissions from the list. This will allow people
+to send emails to the list, but not view the archives or subscribe.