hacking public-inbox
--------------------

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)

Contributions are email-driven, just like contributing to git
itself or the Linux kernel; nevertheless, 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 on public-inbox.

We will reject any feature which advocates or contributes to any
particular instance of 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
lacking 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; but continue to support
any LTS distros within their support window.

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
---------------------------------------------

- 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.