]> Sergey Matveev's repositories - public-inbox.git/blobdiff - Documentation/design_notes.txt
mda: rename PI_FAILBOX to PI_EMERGENCY
[public-inbox.git] / Documentation / design_notes.txt
index e7e6fff7121659f313fb3ada0de80ce6d2e65f3b..286f35c0cd0ce37a030755a093e234cfb38c14da 100644 (file)
@@ -1,17 +1,5 @@
-Design notes and philosophy
----------------------------
-
-public-inbox spawned around some basic ideas
---------------------------------------------
-
-* Public, non-real-time, archivable communication is essential to
-  Free and Open Source software development.
-
-* Contributing to Free and Open Source projects should not require the
-  use of non-Free/non-Open Source services or software.
-
-* Graphical user interfaces should not be required for text-based
-  communication.
+Design notes
+------------
 
 Challenges to running normal mailing lists
 ------------------------------------------
@@ -33,8 +21,10 @@ Use existing infrastructure
 
 * public-inbox uses SMTP for posting.  Posting a message to a public-inbox
   instance is no different than sending a message to any _open_ mailing
-  list.  Any existing spam filtering on an SMTP server is also effective
-  on public-inbox.
+  list.
+
+* Existing spam filtering on an SMTP server is also effective on
+  public-inbox.
 
 * readers may continue using use their choice of mail clients and
   mailbox formats, only learning a few commands of the ssoma(1) tool
@@ -68,7 +58,7 @@ Why email?
   list.
 
 * Email is already the de-facto form of communication in many Free Software
-  communities.
+  communities..
 
 * Fallback/transition to private email and other lists, in case the
   public-inbox host becomes unavailable, users may still directly email
@@ -79,12 +69,49 @@ Why git?
 
 * git is distributed and robust while being both fast and
   space-efficient with text data.  NNTP was considered, but does not
-  support compression and places no guarantees on data/transport
+  support delta-compression and places no guarantees on data/transport
   integrity.  However, an NNTP gateway (read-only?) is possible.
 
 * As of 2014, git is widely used and known to nearly all Free Software
   developers.  For non-developers it is packaged for all major GNU/Linux
-  and *BSD distributions.
+  and *BSD distributions.  NNTP is not as widely-used nowadays.
+
+Why perl 5?
+-----------
+
+* Perl 5 is widely available on modern *nix systems with good a history
+  of backwards and forward compatibility.
+
+* git and SpamAssassin both use it, so it should be one less thing for
+  admins to install and waste disk space with.
+
+Laziness
+--------
+
+* Stick to dependencies available in Debian main, this should make it
+  easier for potential users to install, and easier for distro
+  maintainers to pick up.
+
+* A list server being turned into an SMTP spam relay and being
+  blacklisted while an admin is asleep is scary.
+  Sidestep that entirely by having clients pull.
+
+* Eric has a great Maildir+inotify-based Bayes training setup
+  going back many years.  Document, integrate and publicize it for
+  public-inbox usage, encouraging other admins to use it (it works
+  as long as admins read their public-inbox).
+
+* Custom, difficult-for-Bayes requires custom anti-spam rules.
+  We may steal rules from the Debian listmasters:
+  svn://anonscm.debian.org/pkg-listmaster
+
+* Full archives are easily distributable with git, so somebody else
+  can take over the list if we give up.  Anybody may also run an SMTP
+  notifier/delivery service based on the archives.
+
+* Avoids bikeshedding about web UI decisions, GUI-lovers can write their
+  own GUI-friendly interfaces (HTML or native) based on public archives.
+  Maybe one day integrated MUAs will feature built-in git protocol support!
 
 Web notes
 ---------
@@ -101,6 +128,20 @@ Web notes
 * Raw text endpoint allows users to write client-side JS endpoints
   without hosting the data themselves (or on a different server).
 
+Scalability notes
+-----------------
+
+Even with shallow clone, storing the history of large/busy mailing lists
+may place much burden on subscribers and servers.  However, having a
+single (or few) refs representing the entire history of a list is good
+for small lists since it's easier to lookup a message by Message-ID, so
+we want to avoid splitting refs with independent histories.
+
+ssoma will likely grow its own builtin ref rotation system based on
+message count (not rotating at fixed time intervals).  This would
+split the histories and require O(n) lookup time based on Message-ID,
+where `n' is the number of history splits.
+
 Copyright
 ---------
 Copyright 2013, Eric Wong <normalperson@yhbt.net> and all contributors.