* [PATCH] doc: update release notes, marketing, and install
@ 2024-03-13 21:02 Eric Wong
0 siblings, 0 replies; only message in thread
From: Eric Wong @ 2024-03-13 21:02 UTC (permalink / raw)
To: meta
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.<remote>.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:
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2024-03-13 21:02 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-03-13 21:02 [PATCH] doc: update release notes, marketing, and install Eric Wong
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).