45868951abe47b818da3faf25538fbadaee3bdff — Peter Sanchez 3 years ago dff42ed
Adding basic lists documentation. Updating index for lists addition
3 files changed, 211 insertions(+), 0 deletions(-)

M index.md
A lists/etiquette.md
A lists/index.md
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

# 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

To learn about recommended clients for plaintext users and how to setup
plaintext with your email client check out our guide at

# 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,

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

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

[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
- `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

# 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.