From 45868951abe47b818da3faf25538fbadaee3bdff Mon Sep 17 00:00:00 2001 From: Peter Sanchez Date: Tue, 21 Jul 2020 12:39:37 -0700 Subject: [PATCH] Adding basic lists documentation. Updating index for lists addition --- index.md | 3 ++ lists/etiquette.md | 88 +++++++++++++++++++++++++++++++++ lists/index.md | 120 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 211 insertions(+) create mode 100644 lists/etiquette.md create mode 100644 lists/index.md diff --git a/index.md b/index.md index 9cdd351..4d4faf9 100644 --- a/index.md +++ b/index.md @@ -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 diff --git a/lists/etiquette.md b/lists/etiquette.md new file mode 100644 index 0000000..79e7c31 --- /dev/null +++ b/lists/etiquette.md @@ -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). diff --git a/lists/index.md b/lists/index.md new file mode 100644 index 0000000..afccdc5 --- /dev/null +++ b/lists/index.md @@ -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. -- 2.43.0