Documentation/design_notes.txt | 14 ++++++++++++-- Documentation/design_www.txt | 3 ++- INSTALL | 3 +++ README | 20 +++++++++++++++++--- diff --git a/Documentation/design_notes.txt b/Documentation/design_notes.txt index d96c8d8247cbdf4654ebb8157d89492522ffbe65..ec1dc80084f65e1ea220e68bfaa0cf603d63fb8f 100644 --- a/Documentation/design_notes.txt +++ b/Documentation/design_notes.txt @@ -3,6 +3,7 @@ ------------------------- Challenges to running normal mailing lists ------------------------------------------ + 1) spam 2) bounce processing of invalid/bad email addresses 3) processing subscribe/unsubscribe requests @@ -14,6 +15,7 @@ confused users who cannot unsubscribe. Use existing infrastructure --------------------------- + * public-inbox can coexist with existing mailing lists, any subscriber to the existing mailing list can begin delivering messages to public-inbox-mda(1) @@ -34,6 +36,7 @@ by a variety of feed readers. Why email? ---------- + * Freedom from proprietary services, tools and APIs. Communicating with developers and users of Free Software should not rely on proprietary tools or services. @@ -64,17 +67,19 @@ each other (or Cc: lists for related/dependent projects). Why git? -------- + * git is distributed and robust while being both fast and space-efficient with text data. NNTP was considered, but does not support delta-compression and places no guarantees on data/transport - integrity. However, an NNTP gateway (read-only?) is possible. + integrity. However, a read-only NNTP gateway is implemented. -* As of 2014, git is widely used and known to nearly all Free Software +* As of 2016, 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. 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. @@ -83,6 +88,7 @@ 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. @@ -110,6 +116,7 @@ Maybe one day integrated MUAs will feature built-in git protocol support! Web notes --------- + * Getting users to install/run ssoma (or any new tool) is difficult. The web views must be easily read/cache/mirror-able. @@ -124,6 +131,7 @@ without hosting the data themselves (or on a different server). What sucks about public-inbox ----------------------------- + * Lack of push notification. On the other hand, feeds seem popular. * some (mostly GUI) mail clients cannot set In-Reply-To headers @@ -131,6 +139,7 @@ properly without the original message. 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 @@ -144,5 +153,6 @@ where `n' is the number of history splits. Copyright --------- + Copyright 2013-2015 all contributors License: AGPLv3 or later diff --git a/Documentation/design_www.txt b/Documentation/design_www.txt index 87631840e0806a9fc80c32de7fbae61a86c4ebae..760152333e651b916db7d62ae5d70c486da39cf8 100644 --- a/Documentation/design_www.txt +++ b/Documentation/design_www.txt @@ -16,7 +16,7 @@ /$LISTNAME/$MESSAGE_ID -> 301 to /$LISTNAME/$MESSAGE_ID /$LISTNAME/$MESSAGE_ID/raw -> raw mbox /$LISTNAME/$MESSAGE_ID/f/ -> HTML content (full quotes) -### Legacy endpoints (may be ambiguous given Message-IDs with similar suffies) +### Legacy endpoints (may be ambiguous given Message-IDs with similar suffixes) /$LISTNAME/m/$MESSAGE_ID/ -> 301 to /$LISTNAME/$MESSAGE_ID/ /$LISTNAME/m/$MESSAGE_ID.html -> 301 to /$LISTNAME/$MESSAGE_ID/ /$LISTNAME/m/$MESSAGE_ID.txt -> 301 to /$LISTNAME/$MESSAGE_ID/raw @@ -45,6 +45,7 @@ of the original email. Guidelines for using limited HTML --------------------------------- + We mainly use HTML for linking pages together with . We also set to make window management easier. diff --git a/INSTALL b/INSTALL index bb682942d7bdbd18f9840b7a735f3b601500e25a..538a95dbb8616154cadfe4aa544db6201a8bb0ee 100644 --- a/INSTALL +++ b/INSTALL @@ -1,5 +1,6 @@ public-inbox (server-side) installation --------------------------------------- + This is for folks who want to setup their own public-inbox instance. Clients should see http://ssoma.public-inbox.org/INSTALL.html instead if they want to import mail into their personal inboxes. @@ -20,6 +21,7 @@ make install # root permissions may be needed Requirements (server MDA) ------------------------- + * git * ssoma - http://ssoma.public-inbox.org/INSTALL.html * SpamAssassin (spamc/spamd) @@ -55,5 +57,6 @@ [4] - Optional for NNTP server Copyright --------- + Copyright 2013-2015 all contributors <meta@public-inbox.org> License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt> diff --git a/README b/README index 09b66a36bd2b9b74f59117cb307f4b943e4419c6..85b48be81f3faa04687d775ad0c559d355c2974c 100644 --- a/README +++ b/README @@ -1,5 +1,6 @@ public-inbox - an "archives first" approach to mailing lists ------------------------------------------------------------ + public-inbox implements the sharing of an email inbox via git to complement or replace traditional mailing lists. Readers may read via NNTP, Atom feeds or HTML archives. @@ -7,9 +8,11 @@ public-inbox spawned around three main ideas: * Publically accessible and archived communication is essential to - Free and Open Source development. -* Contributing to Free and Open Source projects should not require the - use of non-Free/non-Open Source services or software. + Free Software development. + +* Contributing to Free Software projects should not require the + use of non-Free services or software. + * Graphical user interfaces should not be required for text-based communication. @@ -18,6 +21,7 @@ to run their own instances with minimal overhead. Implementation -------------- + public-inbox uses ssoma[1], Some Sort Of Mail Archiver which implements no policy of its own. By storing (and optionally) exposing an inbox via git, it is fast and efficient to host and mirror public-inboxes. @@ -47,9 +51,13 @@ [1] http://ssoma.public-inbox.org/ Features -------- + * anybody may participate via plain-text email + * stores email in git, readers may have a complete archive of the inbox + * Atom feed and NNTP allows casual readers to follow via feed reader + * uses only well-documented and easy-to-implement data formats Try it out now, see http://try.public-inbox.org/ @@ -73,10 +81,12 @@ * participants do not need to install public-inbox, only server admins Requirements (server) --------------------- + See http://public-inbox.org/INSTALL Hacking ------- + Source code is available via git: git clone git://80x24.org/public-inbox @@ -85,6 +95,7 @@ See below for contact info. Contact ------- + We are happy to see feedback of all types via plain-text email. public-inbox discussion is self-hosting on public-inbox.org Please send comments, user/developer discussion, patches, bug reports, @@ -112,6 +123,7 @@ http://ssoma.public-inbox.org/README.html Anti-Spam --------- + The maintainer of public-inbox has found SpamAssassin a good tool for filtering his personal mail, and it will be the default spam filtering tool in public-inbox. @@ -120,6 +132,7 @@ See http://public-inbox/dc-dlvr-spam-flow.html for more info. Content Filtering ----------------- + To discourage phishing, web bugs (tracking), viruses and other nuisances, only plain-text content is allowed and non-text content is stripped. This saves I/O bandwidth and storage, which is important as @@ -131,6 +144,7 @@ aims to preserve the focus on content, and not presentation. Copyright --------- + Copyright 2013-2015 all contributors <meta@public-inbox.org> License: AGPLv3 or later <http://www.gnu.org/licenses/agpl-3.0.txt>