HACKING

   1 hacking public-inbox
   2 --------------------
   3
   4 Send all patches and "git request-pull"-formatted emails to our
   5 self-hosting inbox at meta@public-inbox.org
   6 It is archived at: https://public-inbox.org/meta/
   7 and http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/ (using Tor)
   8
   9 Contributions are email-driven, just like contributing to git
  10 itself or the Linux kernel; however anonymous and pseudonymous
  11 contributions will always be welcome.
  12
  13 Please consider our goals in mind:
  14
  15         Decentralization, Accessibility, Compatibility, Performance
  16
  17 These goals apply to everyone: users viewing over the web or NNTP,
  18 sysadmins running public-inbox, and other hackers working public-inbox.
  19
  20 We will reject any feature which advocates or contributes to any
  21 particular instance of a public-inbox becoming a single point of failure.
  22 Things we've considered but rejected include:
  23
  24 * exposing article serial numbers outside of NNTP
  25 * allowing readers to inject metadata (e.g. votes)
  26
  27 We care about being accessible to folks with vision problems and/or
  28 lack the computing resources to view so-called "modern" websites.
  29 This includes folks on slow connections and ancient browsers which
  30 may be too difficult to upgrade due to resource demands.
  31
  32 Only depend on Free Software packages which exist in the "main"
  33 section of Debian "stable" distribution.  That is Debian 9.x
  34 ("stretch") as of this writing, but "oldstable" (8.x, "jessie")
  35 remains supported for v1 inboxes.
  36
  37 In general, we favor mature and well-tested old things rather than
  38 the shiny new.
  39
  40 Avoid relying on compiled modules too much.  Even if it is Free,
  41 compiled code makes packages more expensive to audit, build,
  42 distribute and verify.  public-inbox itself will only be implemented
  43 in scripting languages (currently Perl 5) and optional
  44 Just-Ahead-of-Time-compiled C (via Inline::C)
  45
  46 Do not recurse on user-supplied data.  Neither Perl or C handle
  47 deep recursion gracefully.  See lib/PublicInbox/SearchThread.pm
  48 and lib/PublicInbox/MsgIter.pm for examples of non-recursive
  49 alternatives to previously-recursive algorithms.
  50
  51 Performance should be reasonably good for server administrators, too,
  52 and we will sacrifice features to achieve predictable performance.
  53 Encouraging folks to self-host will be easier with lower hardware
  54 requirements.
  55
  56 See design_www.txt and design_notes.txt in the Documentation/
  57 directory for design decisions made during development.
  58
  59 See Documentation/technical/ in the source tree for more details
  60 on specific topics, in particular data_structures.txt
  61
  62 Optional packages for testing and development
  63 ---------------------------------------------
  64
  65 Optional packages testing and development:
  66
  67 - Plack::Test                      deb: libplack-test-perl
  68                                    pkg: p5-Plack
  69                                    rpm: perl-Plack-Test
  70
  71 - Plack::Test::ExternalServer      deb: libplack-test-externalserver-perl
  72                                    pkg: p5-Plack-Test-ExternalServer
  73
  74 - Test::Simple                     deb: perl-modules-5.$MINOR
  75                                    pkg: perl5
  76                                    rpm: perl-Test-Simple
  77
  78 - XML::TreePP                      deb: libxml-treepp-perl
  79                                    pkg: p5-XML-TreePP
  80                                    rpm: perl-XML-TreePP
  81
  82 Email::MIME is optional as of public-inbox v1.5.0 but still
  83 used for maintainer comparison tests:
  84
  85 * Email::MIME                      deb: libemail-mime-perl
  86                                    pkg: p5-Email-MIME
  87                                    rpm: perl-Email-MIME
  88
  89 Faster tests
  90 ------------
  91
  92 The `make test' target provided by MakeMaker does not run in
  93 parallel.  Our `make check' target supports parallel runs, and
  94 it also creates a `.prove' file to optimize `make check-run'.
  95
  96 The prove(1) command (distributed with Perl) may also be used
  97 for finer-grained testing: prove -bvw t/foo.t
  98
  99 If using a make(1) (e.g. GNU make) with `include' support, the
 100 `config.mak' Makefile snippet can be used to set environment
 101 variables such as PERL_INLINE_DIRECTORY and TMPDIR.
 102
 103 With PERL_INLINE_DIRECTORY set to enable Inline::C support and
 104 TMPDIR pointed to a tmpfs(5) mount, `make check-run' takes 6-10s
 105 (load-dependent) on a busy workstation built in 2010.
 106
 107 Perl notes
 108 ----------
 109
 110 * \w, \s, \d character classes all match Unicode characters;
 111   so write out class ranges (e.g "[0-9]") if you only intend to
 112   match ASCII.  Do not use the "/a" (ASCII) modifier, that requires
 113   Perl 5.14 and we're only depending on 5.10.1 at the moment.