summaryrefslogtreecommitdiffstats
path: root/docs/HACKING.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--docs/HACKING.md181
1 files changed, 181 insertions, 0 deletions
diff --git a/docs/HACKING.md b/docs/HACKING.md
new file mode 100644
index 0000000..5b448c7
--- /dev/null
+++ b/docs/HACKING.md
@@ -0,0 +1,181 @@
+Hacking on man-db
+=================
+
+man-db is not a large or particularly complicated project, but there is
+still plenty for an interested developer to contribute. Here's a very brief
+guide on how to get started.
+
+
+Directory layout
+----------------
+
+The source tree looks something like this, ignoring some directories added
+by autoconf, automake, gettext, and gnulib:
+
+<dl>
+ <dt><code>docs/</code></dt>
+ <dd>Assorted documentation.</dd>
+
+ <dt><code>man/</code></dt>
+ <dd>Man pages for man-db's programs.</dd>
+
+ <dt><code>manual/</code></dt>
+ <dd>The man-db manual, written in <code>troff</code>.</dd>
+
+ <dt><code>include/</code></dt>
+ <dd>Header files used throughout the package.</dd>
+
+ <dt><code>lib/</code></dt>
+ <dd>
+ Basic library files, some of which supplement inadequate C libraries on
+ various systems and some of which implement utility functions used
+ throughout the package.
+ </dd>
+
+ <dt><code>libdb/</code></dt>
+ <dd>
+ The database access library. Code outside this directory should not know
+ about specific back-end database implementations.
+ </dd>
+
+ <dt><code>src/</code></dt>
+ <dd>Source code to the man-db programs themselves.</dd>
+
+ <dt><code>tools/</code></dt>
+ <dd>Miscellaneous add-on scripts.</dd>
+
+ <dt><code>po/</code></dt>
+ <dd>Translations.</dd>
+</dl>
+
+
+Coding style
+------------
+
+Each indent is a single tab. Brace style is K&R. Each function name is
+separated from the following opening parenthesis by a single space. (All
+this is almost certainly controversial somewhere, but it's as close as
+you'll get to a prevailing style here.)
+
+Keep all code within 80 columns (counting tabs as 8). This can sometimes be
+a little tight with the deep indent; think of it as a useful discipline to
+stop indentation levels getting out of hand. :-) (This rule is currently
+broken for argp option declarations, for the sake of other kinds of
+readability. This may change.)
+
+If you're editing existing code and it differs from any of the above, stick
+with whatever the existing code does. Likewise, if in doubt, find similar
+code and use its style. Maintaining a consistent style is important for
+general readability, and is more important than any individual point. It's
+also the easiest way to avoid long and tedious debates about "correct"
+style.
+
+
+Facilities and portability
+--------------------------
+
+man-db uses Gnulib to provide portability support and utility functions
+common to many GNU packages (although man-db is not itself a GNU package),
+while the `lib/` directory provides some other utility functions specific to
+man-db. Please make use of these facilities where available. In particular,
+there are various functions beginning with 'x' which check the return values
+from the system's memory allocation calls, which you should use instead of
+their non-'x' siblings.
+
+`appendstr()` provides manageable string concatenation. Use it where
+appropriate. Remember to terminate its argument list with a NULL. In many
+cases, `xasprintf()` from Gnulib may be more readable.
+
+If you're calling any of the `is*()` or `to*()` functions in `<ctype.h>`,
+please do so via the `CTYPE()` macro in `include/manconfig.h` to ensure that
+the argument type is correct.
+
+You may assume C99.
+
+
+Testing
+-------
+
+There is a small test suite in `src/tests/`, as well as basic tests in
+`man/` to ensure that man-db's own manual pages format without errors. Tests
+for new bug fixes are not *required*, but are generally a good idea.
+
+Various test library facilities are available in `src/tests/testlib.sh`.
+Feel free to extend this as necessary.
+
+
+Things to do
+------------
+
+`docs/TODO` has a number of outstanding projects. Things near the bottom are
+usually more detailed and accurate.
+
+The Debian bug tracking system has a number of [outstanding reports on
+man-db](https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=man-db;ordering=upstream).
+
+Much of the work needed on man-db is for maintainability. Patches that take
+difficult-to-understand code with hairy memory allocation and replace it
+with clean, obvious, and reliable code are most welcome, especially if they
+introduce new abstractions which are of more general use. The replacement of
+`splitline()` with the `page_description` interface is a good example of
+this.
+
+Work on porting to platforms other than GNU/Linux is welcome. It's been a
+while since serious effort in that direction has been invested in man-db.
+Most of the code should be quite portable, but the occasional teething
+problem would not be a surprise.
+
+
+Sending patches
+---------------
+
+GitLab merge requests are preferred. Create an account on gitlab.com,
+[fork](https://gitlab.com/man-db/man-db/-/forks/new) the repository to your
+own account, push your branch, and create a merge request.
+
+If you can't or don't want to use GitLab merge requests, then you can fall
+back to sending patches in unified diff format (use `git diff`, or GNU diff
+with the -u option) to man-db-devel@nongnu.org (see [subscription
+instructions](https://lists.nongnu.org/mailman/listinfo/man-db-devel)).
+
+
+Revision control
+----------------
+
+man-db is revision-controlled using [git](https://git-scm.com/). The archive
+may be fetched from here using `git clone`, and merge requests are accepted
+in the usual way:
+
+ https://gitlab.com/man-db/man-db
+
+Generated files should be added to `.gitignore` and should not be committed
+to revision control.
+
+
+Release process
+---------------
+
+1. Update the `AC_INIT` version number in `configure.ac` to "x.y.z-pre1".
+ Commit and tag.
+
+2. Pushing the tag should cause the GitLab CI machinery to upload a
+ preliminary tarball for translators to the [package
+ registry](https://gitlab.com/man-db/man-db/-/packages). Send this to the
+ Translation Project robot, to provide context for `po/man-db.pot`.
+
+3. Wait a couple of weeks for a reasonable number of translation updates to
+ arrive. During this time, test until your eyeballs fall out, but try to
+ avoid changing any translated messages.
+
+4. Once you're ready to release, update `NEWS.md`, and
+ the `AC_INIT` version number and `date` in `configure.ac`. Commit and
+ tag.
+
+5. Pushing the tag should cause the GitLab CI machinery to upload the
+ release tarball to the [package
+ registry](https://gitlab.com/man-db/man-db/-/packages). GPG-sign that
+ tarball, and upload the tarball and its signature to Savannah so that the
+ URLs in the newly-created [GitLab release
+ notes](https://gitlab.com/man-db/man-db/-/releases) are valid.
+
+6. Announce to wherever seems appropriate.