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