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; nevertheless, 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 on public-inbox.
  19
  20 We will reject any feature which advocates or contributes to any
  21 particular instance of 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 lacking 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; but continue to support
  34 any LTS distros within their support window.
  35
  36 In general, we favor mature and well-tested old things rather than
  37 the shiny new.
  38
  39 Avoid relying on compiled modules too much.  Even if it is Free,
  40 compiled code makes packages more expensive to audit, build,
  41 distribute and verify.  public-inbox itself will only be implemented
  42 in scripting languages (currently Perl 5) and optional
  43 Just-Ahead-of-Time-compiled C (via Inline::C)
  44
  45 Do not recurse on user-supplied data.  Neither Perl or C handle
  46 deep recursion gracefully.  See lib/PublicInbox/SearchThread.pm
  47 and lib/PublicInbox/MsgIter.pm for examples of non-recursive
  48 alternatives to previously recursive algorithms.
  49
  50 Performance should be reasonably good for server administrators, too,
  51 and we will sacrifice features to achieve predictable performance.
  52 Encouraging folks to self-host will be easier with lower hardware
  53 requirements.
  54
  55 See design_www.txt and design_notes.txt in the Documentation/
  56 directory for design decisions made during development.
  57
  58 See Documentation/technical/ in the source tree for more details
  59 on specific topics, in particular data_structures.txt
  60
  61 Optional packages for testing and development
  62 ---------------------------------------------
  63
  64 - Plack::Test                      deb: libplack-test-perl
  65                                    pkg: p5-Plack
  66                                    rpm: perl-Plack-Test
  67
  68 - Plack::Test::ExternalServer      deb: libplack-test-externalserver-perl
  69                                    pkg: p5-Plack-Test-ExternalServer
  70
  71 - Test::Simple                     deb: perl-modules-5.$MINOR
  72                                    pkg: perl5
  73                                    rpm: perl-Test-Simple
  74
  75 - XML::TreePP                      deb: libxml-treepp-perl
  76                                    pkg: p5-XML-TreePP
  77                                    rpm: perl-XML-TreePP
  78
  79 Email::MIME is optional as of public-inbox v1.5.0 but still
  80 used for maintainer comparison tests:
  81
  82 * Email::MIME                      deb: libemail-mime-perl
  83                                    pkg: p5-Email-MIME
  84                                    rpm: perl-Email-MIME
  85
  86 Faster tests
  87 ------------
  88
  89 The `make test' target provided by MakeMaker does not run in
  90 parallel.  Our `make check' target supports parallel runs, and
  91 it also creates a `.prove' file to optimize `make check-run'.
  92
  93 The prove(1) command (distributed with Perl) may also be used
  94 for finer-grained testing: prove -bvw t/foo.t
  95
  96 If using a make(1) (e.g. GNU make) with `include' support, the
  97 `config.mak' Makefile snippet can be used to set environment
  98 variables such as PERL_INLINE_DIRECTORY and TMPDIR.
  99
 100 With PERL_INLINE_DIRECTORY set to enable Inline::C support and
 101 TMPDIR pointed to a tmpfs(5) mount, `make check-run' takes 6-10s
 102 (load-dependent) on a busy workstation built in 2010.
 103
 104 Perl notes
 105 ----------
 106
 107 * \w, \s, \d character classes all match Unicode characters;
 108   so write out class ranges (e.g., "[0-9]") if you only intend to
 109   match ASCII.  Do not use the "/a" (ASCII) modifier, that requires
 110   Perl 5.14 and we're only depending on 5.10.1 at the moment.