Working on schroot                           -*- text -*-
==================

This document is a short guide to the conventions used in the schroot
project.


Coding
------

The style should be apparent from the source.  It is the default Emacs
c++-mode style, with paired brackets aligned vertically.

* Use 0 rather than NULL.
* Use C++ casts rather than C-style casts.
* Don't use void * unless there is no alternative.
* Add doxygen comments for everything; use EXTRACT_ALL = NO in
  doc/schroot.dox to check for missing or incomplete documentation.


Format strings
--------------

The sources use boost::format for type-safe formatted output.  Make
sure that the maximum number of options passed is the same as the
highest %n% in the format string.

The following styles are used

  Style                  Formatting                Syntax
  --------------------------------------------------------------------
  Values                 Single quotes             '
  Example text           Double quotes             \"
  User input             Double quotes             \"

These are transformed into proper UTF-8 quotes with gettext.


Documentation
-------------

All the documentation is in UNIX manual page format.  GNU roff
extensions are permitted, as is use of tbl.  Make sure the printed
output is as good as terminal display.  Run "make ps" or "make pdf" to
build the printed documentation.


The following styles are used:

  Style                  Formatting                Syntax
  --------------------------------------------------------------------
  New term               Bold                      .B or \fB
  Option definition      Bold, args in italic      .BR and \fI
  Option reference       Italic                    .I or \fI
  File definition        Bold italic               \f[BI]
  File reference         Italic                    .I or \fI
  Config key definition  Courier bold italic       \f[CBI]
  Config key reference   Courier italic            \f[CI]
  Values                 Single quotes             \[oq] and \[cq]
  Example text           Double quotes             \[lq] and \[rq]
  Cross references       Italics in double quotes  \[lq]\fI...\fP\[rq]
  Verbatim examples      Courier                   \f[CR]
  Verbatim user input    Courier bold              \f[CB]


Releasing
---------

The code must pass the testsuite (make check).  It must also pass some
tests which must be run by hand:

Chdir fallback behaviour:

  schroot [login shell]
    CWD → CWD            Normal behaviour
    CWD → $HOME          If CWD nonexistent and -p used
    CWD → passwd pw_dir  If CWD nonexistent (or -p used and no $HOME exists)
    CWD → /              None of the above exist
    *FAIL*               If / nonexistent

  schroot [command]
    CWD → CWD            Normal behaviour
    *FAIL*               If CWD nonexistent

    No fallbacks should exist under any circumstances.

  schroot [--directory used]
    CWD → DIR            Normal behaviour
    *FAIL*               If DIR nonexistent

    No fallbacks should exist under any circumstances.

  dchroot [login shell or command]
    CWD → passwd pw_dir  Normal behaviour (not if -d used)
    CWD → CWD            If -d used
    CWD → /              If CWD nonexistent and -d used
    *FAIL*               If / nonexistent

  dchroot [--directory used]
    CWD → DIR            Normal behaviour
    *FAIL*               If DIR nonexistent

    No fallbacks should exist under any circumstances.

  dchroot-dsa [login shell or command]
    CWD → passwd pw_dir  Normal behaviour
    CWD → /              If no passwd_pw dir
    *FAIL*               If / nonexistent

  dchroot-dsa [--directory used]
    CWD → DIR            Normal behaviour
    *FAIL*               If DIR nonexistent

    No fallbacks should exist under any circumstances.

  Note that --debug=notice will show the internal fallback list
  computed for the session.


Setup script behaviour:

  To check if process termination works:
  schroot -v -c sid -- sh -c "trap '' INT; trap '' TERM; sleep 2 &"

  To check if process killing works:
  schroot -v -c sid -- sh -c "trap '' INT; trap '' TERM; sleep 20 &"