Documentation/design_notes.txt

   1 Design notes
   2 ------------
   3
   4 Challenges to running normal mailing lists
   5 ------------------------------------------
   6 1) spam
   7 2) bounce processing of invalid/bad email addresses
   8 3) processing subscribe/unsubscribe requests
   9
  10 Issues 2) and 3) are side-stepped entirely by moving reader
  11 subscriptions to git repository synchronization and Atom feeds.  There's
  12 no chance of faked subscription requests and no need to deal with
  13 confused users who cannot unsubscribe.
  14
  15 Use existing infrastructure
  16 ---------------------------
  17
  18 * public-inbox can coexist with existing mailing lists, any subscriber
  19   to the existing mailing list can begin delivering messages to
  20   public-inbox-mda(1)
  21
  22 * public-inbox uses SMTP for posting.  Posting a message to a public-inbox
  23   instance is no different than sending a message to any _open_ mailing
  24   list.
  25
  26 * Existing spam filtering on an SMTP server is also effective on
  27   public-inbox.
  28
  29 * readers may continue using use their choice of mail clients and
  30   mailbox formats, only learning a few commands of the ssoma(1) tool
  31   is required.
  32
  33 * Atom is a reasonable feed format for casual readers and is supported
  34   by a variety of feed readers.
  35
  36 Why email?
  37 ----------
  38
  39 * Freedom from proprietary services, tools and APIs.  Communicating with
  40   developers and users of Free Software should not rely on proprietary
  41   tools or services.
  42
  43 * Existing infrastrucuture, tools, and user familarity.
  44   There is already a large variety of tools, clients, and email providers
  45   available.  There are also many resources for users to run their own
  46   SMTP server on a domain they control.
  47
  48 * All public discussion mediums are affected by spam and advertising.
  49   There exist several good Free Software anti-spam tools for email.
  50
  51 * Privacy is not an issue for public discussion.  Public mailing list
  52   archives are common and accepted by Free Software communities.
  53   There is no need to ask the NSA for backups of your mail archives :)
  54
  55 * git, one of the most widely-used version control systems, includes many
  56   tools for for email: git-format-patch(1), git-send-email(1), git-am(1).
  57   Furthermore, the development of git itself is based on the git mailing
  58   list.
  59
  60 * Email is already the de-facto form of communication in many Free Software
  61   communities..
  62
  63 * Fallback/transition to private email and other lists, in case the
  64   public-inbox host becomes unavailable, users may still directly email
  65   each other (or Cc: lists for related/dependent projects).
  66
  67 Why git?
  68 --------
  69
  70 * git is distributed and robust while being both fast and
  71   space-efficient with text data.  NNTP was considered, but does not
  72   support delta-compression and places no guarantees on data/transport
  73   integrity.  However, an NNTP gateway (read-only?) is possible.
  74
  75 * As of 2014, git is widely used and known to nearly all Free Software
  76   developers.  For non-developers it is packaged for all major GNU/Linux
  77   and *BSD distributions.  NNTP is not as widely-used nowadays.
  78
  79 Laziness
  80 --------
  81
  82 * A list server being turned into an SMTP spam relay and being
  83   blacklisted while an admin is asleep is scary.
  84   Sidestep that entirely by having clients pull.
  85
  86 * Eric has a great Maildir+inotify-based Bayes training setup
  87   going back many years.  Document, integrate and publicize it for
  88   public-inbox usage, encouraging other admins to use it (it works
  89   as long as admins read their public-inbox).
  90
  91 * Custom, difficult-for-Bayes requires custom anti-spam rules.
  92   We may steal rules from the Debian listmasters:
  93   svn://anonscm.debian.org/pkg-listmaster
  94
  95 * Full archives are easily distributable with git, so somebody else
  96   can take over the list if we give up.  Anybody may also run an SMTP
  97   notifier/delivery service based on the archives.
  98
  99 * Avoids bikeshedding about web UI decisions, GUI-lovers can write their
 100   own GUI-friendly interfaces (HTML or native) based on public archives.
 101   Maybe one day integrated MUAs will feature a built-in git protocol support!
 102
 103 Web notes
 104 ---------
 105
 106 * Getting users to install/run ssoma (or any new tool) is difficult.
 107   The web views must be easily read/cache/mirror-able.
 108
 109 * There may also be a significant number of webmail users without
 110   an MUA or feed reader; so a web view is necessary.
 111
 112 * Expose Message-ID in web views to encourage replies from drive-by
 113   contributors.
 114
 115 * Raw text endpoint allows users to write client-side JS endpoints
 116   without hosting the data themselves (or on a different server).
 117
 118 Copyright
 119 ---------
 120 Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.
 121 License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>