From 5e8068b28aa01befa9c6fa7368db956148816189 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Wed, 13 Mar 2024 21:02:11 +0000 Subject: doc: update release notes, marketing, and install INSTALL now covers more of lei since I'm less uncomfortable about it for 2.0 and points users towards the install/ helpers if installing from source. --- Documentation/RelNotes/v2.0.0.wip | 46 +++++++++++++++++++++-- Documentation/marketing.txt | 13 ++++++- INSTALL | 77 ++++++++++++++++++++++++--------------- install/README | 6 ++- 4 files changed, 107 insertions(+), 35 deletions(-) diff --git a/Documentation/RelNotes/v2.0.0.wip b/Documentation/RelNotes/v2.0.0.wip index c473e8d7..53ef5fe5 100644 --- a/Documentation/RelNotes/v2.0.0.wip +++ b/Documentation/RelNotes/v2.0.0.wip @@ -6,7 +6,8 @@ Content-Disposition: inline This release includes several new features and fixes; mostly around improved integration between inboxes and coderepos for -solver. Portability and reliability is also improved. +solver. Portability and reliability is also improved, especially +in the internal process management of lei. public-inbox-cindex is a new command to index coderepos for WWW search and perform automatic associations between @@ -39,13 +40,22 @@ Compatibility: entries if `newsgroup' isn't specified) will also generate warnings since they break -extindex and the new -cindex (coderepo index). +New users + hackers: + + The install/ directory includes tools to automate installation and + removal of dependencies for stripped down or full setups. See + install/README for more details + treewide * support raw UTF-8 headers from SMTPUTF8 hosts * standardize on `#' prefix for stderr diagnostics (previously `I:') - * SHA-256 coderepos are fully-supported (inboxes not yet) + * SHA-256 coderepos are fully-supported (but not inboxes, yet) + + * jemalloc (tested as an LD_PRELOAD) is recommended to reduce fragmentation + in long-running daemon processes serving unpredictable traffic PublicInbox::WWW @@ -71,12 +81,18 @@ PublicInbox::WWW * add topics_(new|active).(html|atom) endpoints + * linkify peer public-inbox addresses in To/Cc headers + +public-inbox-watch: + + * watching MH folders is now supported + lei * use http.proxy / http..proxy from system-wide git-config if unconfigured for lei - * improve IMAP error reporting + * improve IMAP and NNTP error reporting * reduce default IMAP connections to avoid overloading servers @@ -94,10 +110,16 @@ lei * improved bash completion for labels (see contrib/completion) + * support for reading (but not writing) MH folders + + * `lei index' accepts `+L:$LABEL' like `lei import' does + solver (used by lei (rediff|blob), and PublicInbox::WWW) * handle copies in patches properly + * no longer redundantly parallelized within each WWW process + portability * SIGWINCH is handled properly on less common architectures and OSes @@ -112,6 +134,12 @@ portability * support Alpine Linux, Dragonfly, NetBSD and OpenBSD. This resulted not only in bugfixes to our code, but also to Dragonfly and OpenBSD. + * Inline::C||Socket::MsgHdr no longer required for SCM_RIGHTS + with sendmsg/recvmsg on supported *BSDs. + + * inotify support no longer requires Linux::Inotify2 XS package + for most architectures + public-inbox-pop3d * support `limit=NUM' and `initial_limit=NUM' query parameters @@ -144,9 +172,19 @@ Search improvements (lei and PublicInbox::WWW) * quoted text inside base-85 binary patches is no longer indexed + * `public-inbox-cindex --join' prefers using Xapian's C++ API + directly to avoid Perl method dispatch overhead to get usable + performance assocating ~300 inboxes with over 1K coderepos + (and vice-versa). Users needing this performance will need + a C++ compiler, pkg-config, and the Xapian development files + (see INSTALL). + + This C++ helper will be used more heavily in the future + to enable query parser customizations and other functionality + unavailable from the Xapian SWIG or XS bindings. Thanks to all the bug reporters and users who made this release -possible. +possible, and thanks for bearing with my anxiety over making releases. Please report bugs via plain-text mail to: meta@public-inbox.org diff --git a/Documentation/marketing.txt b/Documentation/marketing.txt index 385e5172..8e4aa3b5 100644 --- a/Documentation/marketing.txt +++ b/Documentation/marketing.txt @@ -3,7 +3,9 @@ marketing guide for public-inbox TL; DR: Don't market this. If you must: don't be pushy and annoying about it. Slow down. -Please no superlatives, hype or BS. +Please no superlatives, hype or BS. Please keep all marketing +materials text-only to be accessible to those on slow networks +and ancient hardware. It's online and public, so it already markets itself. Being informative is not a bad thing, being insistent is. @@ -25,3 +27,12 @@ than the adoption of any software. Every time somebody recognizes and rejects various forms of lock-in and centralization is already a victory for us. + +Please keep in mind: + +* Perl 5 is not a well-liked language +* AGPL is not a well-liked license +* maintainer is a shy introvert + +Be sure to mention these things in any marketing materials +to avoid wasting time of people who hate Perl and/or AGPL. diff --git a/INSTALL b/INSTALL index c5d69d1b..b1d7fd1b 100644 --- a/INSTALL +++ b/INSTALL @@ -1,11 +1,15 @@ -public-inbox (server-side) installation ---------------------------------------- +public-inbox / lei installation +------------------------------- -This is for folks who want to set up their own public-inbox instance. -Clients should use normal git-clone/git-fetch, IMAP or NNTP clients -if they want to import mail into their personal inboxes. +This is for people who want to run public-inbox on their server or +lei as a command-line tool. Any HTTP, IMAP, NNTP, or POP3 client can +access public-inbox servers, as can git-{clone,fetch} on the HTTP(S) +endpoint. -As of 2023, public-inbox is packaged by several OS distributions, +Since our marketing sucks, ease-of-installation is an important goal +for this project and we only depend on distro-provided packages. + +As of 2024, public-inbox is packaged by several OS distributions, listed in alphabetical order: Debian, GNU Guix, NixOS, and Void Linux. public-inbox is developed on Debian GNU/Linux systems and will @@ -14,12 +18,18 @@ the "oldstable" distribution, currently Debian 11.x ("bullseye"), but older versions of Debian remain supported (as are newer ones). Most packages are available in other GNU/Linux distributions, -FreeBSD, NetBSD, and OpenBSD. CentOS 7.x users will likely want -newer git and Xapian for better performance and v2 inbox support: +Alpine Linux, FreeBSD, NetBSD, OpenBSD, and DragonflyBSD. +CentOS 7.x users will likely want newer git and Xapian for +better performance and v2 inbox support: https://public-inbox.org/meta/20210421151308.yz5hzkgm75klunpe@nitro.local/ -TODO: this still needs to be documented better, -also see the scripts/ and sa_config/ directories in the source tree +As of 2.0, install/deps.perl makes it easier to install target +dependencies needed for certain features. See install/README in +the source tree for more info. + +Also see sa_config/ directories in the source tree for recommended +SpamAssassin configuration examples if using public-inbox-mda or +public-inbox-watch. Requirements ------------ @@ -43,22 +53,10 @@ Beyond that, there is one non-standard Perl package required: rpm: perl-URI (for HTML/Atom generation) -Plack and Date::Parse are optional as of public-inbox v1.3.0, -but required for older releases: - -* Plack deb: libplack-perl - pkg: p5-Plack - rpm: perl-Plack, perl-Plack-Test, - (for HTML/Atom generation) - -- Date::Parse deb: libtimedate-perl - pkg: p5-TimeDate - rpm: perl-TimeDate - (for broken, mostly historical emails) - Where "deb" indicates package names for Debian-derived distributions, -"pkg" is for the FreeBSD package (and some other common BSDs, too), and -"rpm" is for RPM-based distributions (only known to work on Fedora). +"pkg" is for the FreeBSD package (and some other common BSDs, too), +"pkgin" for NetBSD, "apk" for Alpine Linux and "rpm" is for RPM-based +distributions (only known to work on Fedora). Numerous optional modules are likely to be useful as well: @@ -71,7 +69,14 @@ Numerous optional modules are likely to be useful as well: pkg: p5-Xapian (FreeBSD, NetBSD) xapian-bindings-perl (OpenBSD) rpm: perl-Search-Xapian - (lei; HTTP and IMAP search) + (required for lei; HTTP and IMAP search) + +Every effort has been to make everything else optional: + +- Plack deb: libplack-perl + pkg: p5-Plack + rpm: perl-Plack, perl-Plack-Test, + (for WWW interface, public-inbox-httpd(1)) - Inline::C deb: libinline-c-perl pkg: p5-Inline-C @@ -88,7 +93,7 @@ Numerous optional modules are likely to be useful as well: - Parse::RecDescent deb: libparse-recdescent-perl pkg: p5-Parse-RecDescent rpm: perl-ParseRecDescent - (only for public-inbox-imapd(1)) + (for public-inbox-imapd(1)) - Mail::IMAPClient deb: libmail-imapclient-perl pkg: p5-Mail-IMAPClient @@ -113,10 +118,19 @@ Numerous optional modules are likely to be useful as well: * xapian-tools deb: xapian-tools pkg: xapian-core + pkgin: xapian rpm: xapian-core (for public-inbox-compact(1) and public-inbox-cindex(1)) +* Xapian development files deb: libxapian-dev + pkg: xapian-core + pkgin: xapian + apk: xapian-core-dev + rpm: xapian-core-devel / xapian14-core-libs + (for public-inbox-cindex(1) and future + performance enhancements) + * curl (tool) deb, pkg, rpm: curl (for lei HTTP(S) externals with curl and public-inbox-clone(1)) @@ -124,11 +138,11 @@ Numerous optional modules are likely to be useful as well: - Linux::Inotify2 deb: liblinux-inotify2-perl rpm: perl-Linux-Inotify2 (for lei, public-inbox-watch and -imapd - on Linux) + on Linux; not required as of 2.0)) - IO::KQueue pkg: p5-IO-KQueue (for lei, public-inbox-watch and -imapd - on *BSDs) + on *BSDs only) - Net::Server deb: libnet-server-perl pkg: p5-Net-Server @@ -159,6 +173,11 @@ Uncommonly needed modules (see HACKING for development-only modules): pkg: p5-Crypt-CBC (for PublicInbox::Unsubscribe (rarely used)) +- Date::Parse deb: libtimedate-perl + pkg: p5-TimeDate + rpm: perl-TimeDate + (for broken, mostly historical emails) + standard MakeMaker installation (Perl) -------------------------------------- diff --git a/install/README b/install/README index dd652552..2cdac4d2 100644 --- a/install/README +++ b/install/README @@ -1,7 +1,11 @@ tooling for mass package installation ------------------------------------- -TL;DR: sudo ./install/deps.perl all +TL;DR (as root or with sudo): + + ./install/deps.perl all # install everything + ./install/deps.perl lei # only what's needed for lei + ./install/deps.perl www-search # for hosting WWW search Files in this directory are designed for: -- cgit v1.2.3-24-ge0c7