diff options
Diffstat (limited to 'docs/HACKING.md')
| -rw-r--r-- | docs/HACKING.md | 181 |
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. |