docs/HACKING

   1 Hacking on man-db
   2 =================
   3
   4 man-db is not a large or particularly complicated project, but there is
   5 still plenty for an interested developer to contribute. Here's a very brief
   6 guide on how to get started.
   7
   8
   9 Directory layout
  10 ----------------
  11
  12 The source tree looks something like this, ignoring some directories added
  13 by autoconf, automake, gettext, and gnulib:
  14
  15   docs/
  16     Assorted documentation.
  17   man/
  18     Man pages for man-db's programs.
  19   manual/
  20     The man-db manual, written in troff.
  21   include/
  22     Header files used throughout the package.
  23   lib/
  24     Basic library files, some of which supplement inadequate C libraries on
  25     various systems and some of which implement utility functions used
  26     throughout the package.
  27   libdb/
  28     The database access library. Code outside this directory should not know
  29     about specific back-end database implementations.
  30   src/
  31     Source code to the man-db programs themselves.
  32   tools/
  33     Miscellaneous add-on scripts.
  34   po/
  35     Translations.
  36
  37
  38 Coding style
  39 ------------
  40
  41 Each indent is a single tab. Brace style is K&R. Each function name is
  42 separated from the following opening parenthesis by a single space. (All
  43 this is almost certainly controversial somewhere, but it's as close as
  44 you'll get to a prevailing style here.)
  45
  46 Keep all code within 80 columns (counting tabs as 8). This can sometimes be
  47 a little tight with the deep indent; think of it as a useful discipline to
  48 stop indentation levels getting out of hand. :-) (This rule is currently
  49 broken for argp option declarations, for the sake of other kinds of
  50 readability. This may change.)
  51
  52 If you're editing existing code and it differs from any of the above, stick
  53 with whatever the existing code does. Likewise, if in doubt, find similar
  54 code and use its style. Maintaining a consistent style is important for
  55 general readability, and is more important than any individual point. It's
  56 also the easiest way to avoid long and tedious debates about "correct"
  57 style.
  58
  59
  60 Facilities and portability
  61 --------------------------
  62
  63 man-db uses Gnulib to provide portability support and utility functions
  64 common to many GNU packages (although man-db is not itself a GNU package),
  65 while the lib/ directory provides some other utility functions specific to
  66 man-db. Please make use of these facilities where available. In particular,
  67 there are various functions beginning with 'x' which check the return values
  68 from the system's memory allocation calls, which you should use instead of
  69 their non-'x' siblings.
  70
  71 appendstr() provides manageable string concatenation. Use it where
  72 appropriate. Remember to terminate its argument list with a NULL. In many
  73 cases, xasprintf() from Gnulib may be more readable.
  74
  75 If you're calling any of the is*() or to*() functions in <ctype.h>, please
  76 do so via the CTYPE() macro in include/manconfig.h to ensure that the
  77 argument type is correct.
  78
  79 You may assume C89 (e.g. no need to support K&R-style function definitions),
  80 but please do not assume C99 (e.g. do not use nested functions or //
  81 comments).
  82
  83
  84 Testing
  85 -------
  86
  87 There is a small test suite in src/tests/, as well as basic tests in man/ to
  88 ensure that man-db's own manual pages format without errors. Tests for new
  89 bug fixes are not *required*, but are generally a good idea.
  90
  91 Various test library facilities are available in src/tests/testlib.sh. Feel
  92 free to extend this as necessary.
  93
  94
  95 Things to do
  96 ------------
  97
  98 docs/TODO has a number of outstanding projects. Things near the bottom are
  99 usually more detailed and accurate.
 100
 101 The Debian bug tracking system has a number of outstanding reports on man-db
 102 at <https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=man-db;ordering=upstream>.
 103
 104 Much of the work needed on man-db is for maintainability. Patches that take
 105 difficult-to-understand code with hairy memory allocation and replace it
 106 with clean, obvious, and reliable code are most welcome, especially if they
 107 introduce new abstractions which are of more general use. The replacement of
 108 splitline() with the page_description interface is a good example of this.
 109
 110 Work on porting to platforms other than GNU/Linux is welcome. It's been a
 111 while since serious effort in that direction has been invested in man-db.
 112 Most of the code should be quite portable, but the occasional teething
 113 problem would not be a surprise.
 114
 115
 116 Sending patches
 117 ---------------
 118
 119 Please send patches in unified diff format (use 'git diff', or GNU diff with
 120 the -u option) to man-db-devel@nongnu.org. See
 121 https://lists.nongnu.org/mailman/listinfo/man-db-devel for subscription
 122 instructions.
 123
 124
 125 Revision control
 126 ----------------
 127
 128 man-db is revision-controlled using git (https://git-scm.com/). The archive
 129 may be fetched from here using 'git clone':
 130
 131   https://git.savannah.gnu.org/git/man-db.git
 132
 133 To browse changes or source code in a web browser, use this URL instead:
 134
 135   https://git.savannah.gnu.org/cgit/man-db.git
 136
 137 Members of the man-db project on Savannah can commit directly by pushing to
 138 this URL:
 139
 140   ssh://git.sv.gnu.org/srv/git/man-db.git
 141
 142 Otherwise, since git is a distributed revision control system, you are of
 143 course free to make and publish branches which can then be merged into the
 144 main tree. See the git documentation for further details.
 145
 146 Generated files should be added to .gitignore and should not be committed to
 147 revision control.
 148
 149
 150 Release process
 151 ---------------
 152
 153 1. Update the AC_INIT version number in configure.ac to "x.y.z-pre1". Commit
 154    and tag.
 155
 156 2. Run ./release.sh to produce a preliminary tarball for translators. This
 157    doesn't have to be particularly well-tested or even compile; it's only
 158    there to provide context for po/man-db.pot. Send this to the Translation
 159    Project robot.
 160
 161 3. Wait a couple of weeks for a reasonable number of translation updates to
 162    arrive. During this time, test until your eyeballs fall out, but try to
 163    avoid changing any translated messages.
 164
 165 4. Ensure that NEWS and docs/man-db.lsm are up to date. Commit.
 166
 167 5. Update the AC_INIT version number and 'date' in configure.ac, but don't
 168    commit yet.
 169
 170 6. Run ./release.sh, which will spit out a tarball. Test it.
 171
 172 7. Commit the changes from step 5.
 173
 174 8. Tag everything.
 175
 176 9. Run ./release.sh. This is the distribution tarball; test it as thoroughly
 177    as you can.
 178
 179 10. Upload the tarball to Savannah.
 180
 181 11. Announce to wherever seems appropriate.