hacking public-inbox
--------------------
-Send all patches via to our self-hosting list at meta@public-inbox.org
+Send all patches and "git request-pull"-formatted emails to our
+self-hosting inbox at meta@public-inbox.org
+It is archived at: https://public-inbox.org/meta/
+and http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/ (using Tor)
-See design_www.txt and design_notes.txt in the Documentation/ directory
-for design decisions made during development.
+Contributions are email-driven, just like contributing to git
+itself or the Linux kernel; however anonymous and pseudonymous
+contributions will always be welcome.
+
+Please consider our goals in mind:
+
+ Decentralization, Accessibility, Compatibility, Performance
+
+These goals apply to everyone: users viewing over the web or NNTP,
+sysadmins running public-inbox, and other hackers working public-inbox.
+
+We will reject any feature which advocates or contributes to any
+particular instance of a public-inbox becoming a single point of failure.
+Things we've considered but rejected include:
+
+* exposing article serial numbers outside of NNTP
+* allowing readers to inject metadata (e.g. votes)
+
+We care about being accessible to folks with vision problems and/or
+lack the computing resources to view so-called "modern" websites.
+This includes folks on slow connections and ancient browsers which
+may be too difficult to upgrade due to resource demands.
+
+Only depend on Free Software packages which exist in the "main"
+section of Debian "stable" distribution. That is Debian 9.x
+("stretch") as of this writing, but "oldstable" (8.x, "jessie")
+remains supported for v1 inboxes.
+
+In general, we favor mature and well-tested old things rather than
+the shiny new.
+
+Avoid relying on compiled modules too much. Even if it is Free,
+compiled code makes packages more expensive to audit, build,
+distribute and verify. public-inbox itself will only be implemented
+in scripting languages (currently Perl 5) and optional
+Just-Ahead-of-Time-compiled C (via Inline::C)
+
+Do not recurse on user-supplied data. Neither Perl or C handle
+deep recursion gracefully. See lib/PublicInbox/SearchThread.pm
+and lib/PublicInbox/MsgIter.pm for examples of non-recursive
+alternatives to previously-recursive algorithms.
+
+Performance should be reasonably good for server administrators, too,
+and we will sacrifice features to achieve predictable performance.
+Encouraging folks to self-host will be easier with lower hardware
+requirements.
+
+See design_www.txt and design_notes.txt in the Documentation/
+directory for design decisions made during development.
+
+See Documentation/technical/ in the source tree for more details
+on specific topics, in particular data_structures.txt
+
+Optional packages for testing and development
+---------------------------------------------
+
+Optional packages testing and development:
+
+- Plack::Test deb: libplack-test-perl
+ pkg: p5-Plack
+ rpm: perl-Plack-Test
+
+- Plack::Test::ExternalServer deb: libplack-test-externalserver-perl
+ pkg: p5-Plack-Test-ExternalServer
+
+- Test::Simple deb: perl-modules-5.$MINOR
+ pkg: perl5
+ rpm: perl-Test-Simple
+
+- XML::TreePP deb: libxml-treepp-perl
+ pkg: p5-XML-TreePP
+ rpm: perl-XML-TreePP
+
+Email::MIME is optional as of public-inbox v1.5.0 but still
+used for maintainer comparison tests:
+
+* Email::MIME deb: libemail-mime-perl
+ pkg: p5-Email-MIME
+ rpm: perl-Email-MIME
+
+Faster tests
+------------
+
+The `make test' target provided by MakeMaker does not run in
+parallel. Our `make check' target supports parallel runs, and
+it also creates a `.prove' file to optimize `make check-run'.
+
+The prove(1) command (distributed with Perl) may also be used
+for finer-grained testing: prove -bvw t/foo.t
+
+If using a make(1) (e.g. GNU make) with `include' support, the
+`config.mak' Makefile snippet can be used to set environment
+variables such as PERL_INLINE_DIRECTORY and TMPDIR.
+
+With PERL_INLINE_DIRECTORY set to enable Inline::C support and
+TMPDIR pointed to a tmpfs(5) mount, `make check-run' takes 6-10s
+(load-dependent) on a busy workstation built in 2010.
+
+Perl notes
+----------
+
+* \w, \s, \d character classes all match Unicode characters;
+ so write out class ranges (e.g "[0-9]") if you only intend to
+ match ASCII. Do not use the "/a" (ASCII) modifier, that requires
+ Perl 5.14 and we're only depending on 5.10.1 at the moment.