Documentation/design_notes.txt

   1 public-inbox 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 * public-inbox can coexist with existing mailing lists, any subscriber
  18   to the existing mailing list can begin delivering messages to
  19   public-inbox-mda(1)
  20
  21 * public-inbox uses SMTP for posting.  Posting a message to a public-inbox
  22   instance is no different than sending a message to any _open_ mailing
  23   list.
  24
  25 * Existing spam filtering on an SMTP server is also effective on
  26   public-inbox.
  27
  28 * readers may continue using use their choice of mail clients and
  29   mailbox formats, only learning a few commands of the ssoma(1) tool
  30   is required.
  31
  32 * Atom is a reasonable feed format for casual readers and is supported
  33   by a variety of feed readers.
  34
  35 Why email?
  36 ----------
  37 * Freedom from proprietary services, tools and APIs.  Communicating with
  38   developers and users of Free Software should not rely on proprietary
  39   tools or services.
  40
  41 * Existing infrastrucuture, tools, and user familarity.
  42   There is already a large variety of tools, clients, and email providers
  43   available.  There are also many resources for users to run their own
  44   SMTP server on a domain they control.
  45
  46 * All public discussion mediums are affected by spam and advertising.
  47   There exist several good Free Software anti-spam tools for email.
  48
  49 * Privacy is not an issue for public discussion.  Public mailing list
  50   archives are common and accepted by Free Software communities.
  51   There is no need to ask the NSA for backups of your mail archives :)
  52
  53 * git, one of the most widely-used version control systems, includes many
  54   tools for for email, including: git-format-patch(1), git-send-email(1),
  55   git-am(1), git-imap-send(1).  Furthermore, the development of git itself
  56   is based on the git mailing list.
  57
  58 * Email is already the de-facto form of communication in many Free Software
  59   communities..
  60
  61 * Fallback/transition to private email and other lists, in case the
  62   public-inbox host becomes unavailable, users may still directly email
  63   each other (or Cc: lists for related/dependent projects).
  64
  65 Why git?
  66 --------
  67 * git is distributed and robust while being both fast and
  68   space-efficient with text data.  NNTP was considered, but does not
  69   support delta-compression and places no guarantees on data/transport
  70   integrity.  However, an NNTP gateway (read-only?) is possible.
  71
  72 * As of 2014, git is widely used and known to nearly all Free Software
  73   developers.  For non-developers it is packaged for all major GNU/Linux
  74   and *BSD distributions.  NNTP is not as widely-used nowadays.
  75
  76 Why perl 5?
  77 -----------
  78 * Perl 5 is widely available on modern *nix systems with good a history
  79   of backwards and forward compatibility.
  80
  81 * git and SpamAssassin both use it, so it should be one less thing for
  82   admins to install and waste disk space with.
  83
  84 Laziness
  85 --------
  86 * Stick to dependencies available in Debian main, this should make it
  87   easier for potential users to install, and easier for distro
  88   maintainers to pick up.
  89
  90 * A list server being turned into an SMTP spam relay and being
  91   blacklisted while an admin is asleep is scary.
  92   Sidestep that entirely by having clients pull.
  93
  94 * Eric has a great Maildir+inotify-based Bayes training setup
  95   going back many years.  Document, integrate and publicize it for
  96   public-inbox usage, encouraging other admins to use it (it works
  97   as long as admins read their public-inbox).
  98
  99 * Custom, difficult-for-Bayes requires custom anti-spam rules.
 100   We may steal rules from the Debian listmasters:
 101   svn://anonscm.debian.org/pkg-listmaster
 102
 103 * Full archives are easily distributable with git, so somebody else
 104   can take over the list if we give up.  Anybody may also run an SMTP
 105   notifier/delivery service based on the archives.
 106
 107 * Avoids bikeshedding about web UI decisions, GUI-lovers can write their
 108   own GUI-friendly interfaces (HTML or native) based on public archives.
 109   Maybe one day integrated MUAs will feature built-in git protocol support!
 110
 111 Web notes
 112 ---------
 113 * Getting users to install/run ssoma (or any new tool) is difficult.
 114   The web views must be easily read/cache/mirror-able.
 115
 116 * There may also be a significant number of webmail users without
 117   an MUA or feed reader; so a web view is necessary.
 118
 119 * Expose Message-ID in web views to encourage replies from drive-by
 120   contributors.
 121
 122 * Raw text endpoint allows users to write client-side JS endpoints
 123   without hosting the data themselves (or on a different server).
 124
 125 What sucks about public-inbox
 126 -----------------------------
 127 * Lack of push notification.  On the other hand, feeds seem popular.
 128
 129 * some (mostly GUI) mail clients cannot set In-Reply-To headers
 130   properly without the original message.
 131
 132 Scalability notes
 133 -----------------
 134 Even with shallow clone, storing the history of large/busy mailing lists
 135 may place much burden on subscribers and servers.  However, having a
 136 single (or few) refs representing the entire history of a list is good
 137 for small lists since it's easier to lookup a message by Message-ID, so
 138 we want to avoid splitting refs with independent histories.
 139
 140 ssoma will likely grow its own builtin ref rotation system based on
 141 message count (not rotating at fixed time intervals).  This would
 142 split the histories and require O(n) lookup time based on Message-ID,
 143 where `n' is the number of history splits.
 144
 145 Copyright
 146 ---------
 147 Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.
 148 License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>