[PATCH 3/6] doc: technical: document weird stuff in our codebase

[Eric Wong <e@80x24.org>]

Hopefully this makes things less surprising to new hackers.
---
 Documentation/technical/weird-stuff.txt | 22 ++++++++++++++++++++++
 MANIFEST                                |  1 +
 2 files changed, 23 insertions(+)
 create mode 100644 Documentation/technical/weird-stuff.txt

diff --git a/Documentation/technical/weird-stuff.txt b/Documentation/technical/weird-stuff.txt
new file mode 100644
index 00000000..0c8d6891
--- /dev/null
+++ b/Documentation/technical/weird-stuff.txt
@@ -0,0 +1,22 @@
+There's a lot of weird code in public-inbox which may be daunting
+to new hackers.
+
+* The event loop (PublicInbox::DS) is an evolution of a fairly standard
+  C10K event loop.  See ds.txt in this directory for more.
+
+Things got weirder in 2021:
+
+* The lei command-line tool is backed by a daemon.  This was done to
+  improve startup time for shell completion and manage git/SQLite/Xapian
+  single-writer during long, parallel imports.  It may eventually become
+  a read-write IMAP/JMAP server.
+
+* SOCK_SEQPACKET is used extensively in lei, and will likely make its
+  way into more places, still.
+
+And even more so in 2022:
+
+* public-inbox-clone / PublicInbox::LeiMirror relies on ->DESTROY
+  for make-like dependency management while providing parallelism.
+
+More to come, lei will expose Maildirs via FUSE 3...
diff --git a/MANIFEST b/MANIFEST
index 7437bb54..bc652e21 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -99,6 +99,7 @@ Documentation/standards.perl
 Documentation/technical/data_structures.txt
 Documentation/technical/ds.txt
 Documentation/technical/memory.txt
+Documentation/technical/weird-stuff.txt
 Documentation/technical/whyperl.txt
 Documentation/txt2pre
 HACKING