Documentation/design_notes.txt

   1 public-inbox design notes
   2 -------------------------
   3
   4 Challenges to running normal mailing lists
   5 ------------------------------------------
   6
   7 1) spam
   8 2) bounce processing of invalid/bad email addresses
   9 3) processing subscribe/unsubscribe requests
  10
  11 Issues 2) and 3) are side-stepped entirely by moving reader
  12 subscriptions to git repository synchronization and Atom feeds.  There's
  13 no chance of faked subscription requests and no need to deal with
  14 confused users who cannot unsubscribe.
  15
  16 Use existing infrastructure
  17 ---------------------------
  18
  19 * public-inbox can coexist with existing mailing lists, any subscriber
  20   to the existing mailing list can begin delivering messages to
  21   public-inbox-mda(1) or public-inbox-watch(1)
  22
  23 * public-inbox uses SMTP for posting.  Posting a message to a public-inbox
  24   instance is no different than sending a message to any _open_ mailing
  25   list.
  26
  27 * Existing spam filtering on an SMTP server is also effective on
  28   public-inbox.
  29
  30 * Readers may continue using use their choice of NNTP and mail clients.
  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
  38 * Freedom from proprietary services, tools and APIs.  Communicating with
  39   developers and users of Free Software should not rely on proprietary
  40   tools or services.
  41
  42 * Existing infrastructure, tools, and user familiarity.
  43   There is already a large variety of tools, clients, and email providers
  44   available.  There are also many resources for users to run their own
  45   SMTP server on a domain they control.
  46
  47 * All public discussion mediums are affected by spam and advertising.
  48   There exist several good Free Software anti-spam tools for email.
  49
  50 * Privacy is not an issue for public discussion.  Public mailing list
  51   archives are common and accepted by Free Software communities.
  52   There is no need to ask the NSA for backups of your mail archives :)
  53
  54 * git, one of the most widely-used version control systems, includes many
  55   tools for for email, including: git-format-patch(1), git-send-email(1),
  56   git-am(1), git-imap-send(1).  Furthermore, the development of git itself
  57   is based on the git mailing list: https://public-inbox.org/git/
  58   (or
  59   http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/git/
  60   for Tor users)
  61
  62 * Email is already the de-facto form of communication in many Free Software
  63   communities..
  64
  65 * Fallback/transition to private email and other lists, in case the
  66   public-inbox host becomes unavailable, users may still directly email
  67   each other (or Cc: lists for related/dependent projects).
  68
  69 Why git?
  70 --------
  71
  72 * git is distributed and robust while being both fast and
  73   space-efficient with text data.  NNTP was considered, but does not
  74   support delta-compression and places no guarantees on data/transport
  75   integrity.  However, read-only IMAP and NNTP gateways are implemented.
  76
  77 * As of 2016, git is widely used and known to nearly all Free Software
  78   developers.  For non-developers it is packaged for all major GNU/Linux
  79   and *BSD distributions.  NNTP is not as widely-used nowadays, and
  80   most IMAP clients do not have good support for read-only mailboxes.
  81
  82 Why perl 5?
  83 -----------
  84
  85 * Perl 5 is widely available on modern *nix systems with good a history
  86   of backwards and forward compatibility.
  87
  88 * git and SpamAssassin both use it, so it should be one less thing for
  89   admins to install and waste disk space with.
  90
  91 * Distributing compiled binaries has higher costs for storage/cache
  92   space is required for each architecture.  Having a runnable,
  93   source-only distribution means any user already has access to all
  94   of our source.
  95
  96 Laziness
  97 --------
  98
  99 * Stick to dependencies available in Debian main, this should make it
 100   easier for potential users to install, and easier for distro
 101   maintainers to pick up.
 102
 103 * A list server being turned into an SMTP spam relay and being
 104   blacklisted while an admin is asleep is scary.
 105   Sidestep that entirely by having clients pull.
 106
 107 * Eric has a great Maildir+inotify-based Bayes training setup
 108   going back many years.  Document, integrate and publicize it for
 109   public-inbox usage, encouraging other admins to use it (it works
 110   as long as admins read their public-inbox).
 111
 112 * Custom, difficult-for-Bayes requires custom anti-spam rules.
 113   We may steal rules from the Debian listmasters:
 114   svn://anonscm.debian.org/pkg-listmaster
 115
 116 * Full archives are easily distributable with git, so somebody else
 117   can take over the list if we give up.  Anybody may also run an SMTP
 118   notifier/delivery service based on the archives.
 119
 120 * Avoids bikeshedding about web UI decisions, GUI-lovers can write their
 121   own GUI-friendly interfaces (HTML or native) based on public archives.
 122
 123 Web notes
 124 ---------
 125
 126 * Getting users to install/run any new tool is difficult.
 127   The web views must be easily read/cache/mirror-able.
 128
 129 * There may also be a significant number of webmail users without
 130   an MUA or feed reader; so a web view is necessary.
 131
 132 * Expose Message-ID in web views to encourage replies from drive-by
 133   contributors.
 134
 135 * Raw text endpoint allows users to write client-side endpoints
 136   without hosting the data themselves (or on a different server).
 137
 138 What sucks about public-inbox
 139 -----------------------------
 140
 141 * Lack of push notification.  On the other hand, feeds seem popular.
 142
 143 * some (mostly GUI) mail clients cannot set In-Reply-To headers
 144   properly without the original message.
 145
 146 * marketing - as it should: <https://public-inbox.org/marketing.txt>
 147
 148 Scalability notes
 149 -----------------
 150
 151 See the public-inbox-v2-format(5) manpage for all the scalability
 152 problems solved.
 153
 154 Copyright
 155 ---------
 156
 157 Copyright all contributors <meta@public-inbox.org>
 158 License: AGPL-3.0+ <http://www.gnu.org/licenses/agpl-3.0.txt>