man-db/docs/HACKING.md

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:

docs/

Assorted documentation.

man/

Man pages for man-db's programs.

manual/

The man-db manual, written in troff.

include/

Header files used throughout the package.

lib/

Basic library files, some of which supplement inadequate C libraries on various systems and some of which implement utility functions used throughout the package.

libdb/

The database access library. Code outside this directory should not know about specific back-end database implementations.

src/

Source code to the man-db programs themselves.

tools/

Miscellaneous add-on scripts.

po/

Translations.

Coding style

clang-format enforces a consistent style, configured in .clang-format. You can ensure that this and other checks are applied to your git commits locally by installing the pre-commit package and running pre-commit install. Whether you do this or not, if you push your changes to a fork on GitLab, then GitLab CI will run them for you.

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

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

Revision control

man-db is revision-controlled using git. 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. 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. GPG-sign that tarball, and upload the tarball and its signature to Savannah so that the URLs in the newly-created GitLab release notes are valid.

6. Announce to wherever seems appropriate.