grml policy
===========

*******************************************************************************
Important! This file is not yet official - work in progress.
*******************************************************************************

Preface
-------

This is a short documentation describing different policies used at and for
link:http://grml.org/[grml].

Packaging Software
------------------

If you are not yet familiar with **creating** Debian packaging, useful
resources are the link:http://www.debian.org/doc/maint-guide/[Debian New
Maintainers' Guide] and
link:http://www.debian.org/doc/manuals/developers-reference/index.en.html[The
Debian Developer's Reference].

Software that should be **added** to the grml repository (and as a
consequence being available for inclusion in grml) must be packaged
according to the
link:http://www.debian.org/doc/debian-policy/index.html[Debian policy].
The Debian packages should be
link:http://lintian.debian.org/[lintian]-clean and have to provide manpages
for the shipped executables. The package should either be maintained inside
a git repository hosted at link:http://git.grml.org/[git.grml.org] or be
part of the official debian repository.
If a package is a grml specific package (so upstream is different from
the grml-team) the Debian package has to start with the suffix 'grml-' (so
the grml specific packages can be identified easily).

If you want to see software included in grml but won't be able to deal with
the Debian package please link:http://grml.org/report/[send your feature
request to the grml-team] or by sending a mail to
mailto:bts@bts.grml.org[bts@bts.grml.org], which will add an issue to
link:http://bts.grml.org[bts.grml.org].

Uploading Debian packages to link:http://deb.grml.org/[the grml pool] is
restricted to the ftp-masters (being Michael Prokop and Alexander Wirt at
the time of writing this document).

As a long term goal the Debian packages used at grml should be provided to
the official Debian distribution using the official
link:http://www.debian.org/devel/wnpp/[WNPP / ITP (Intend To Package)]
procedure.

Adding Software to grml
-----------------------

If you plan to write software for inclusion and distribution by grml you
should be aware of the following requirements:

* The software has to be licensed under an
link:http://www.opensource.org/licenses[OSI approved license] and should
follow the link:http://www.debian.org/social_contract#guidelines[The Debian
Free Software Guidelines (DFSG)]. The grml-team prefers the
link:http://www.gnu.org/copyleft/gpl.html[GNU General Public License
(GPL)]. If you want to see your patch/script/software included in a core
grml package it has to be licensed under the GPL as well.

* Your software has to provide documentation. The package must provide at
least an up2date manpage. The grml-team prefers documentation written in
link:http://www.methods.co.nz/asciidoc/[asciidoc], see
link:http://grml.org/docs/[grml.org/docs/] and
link:http://hg.grml.org/grml-debootstrap/file/tip/grml-debootstrap.8.txt[grml-debootstrap.8.txt]
for a real-life example.

* Your software should be as platform independent as possible and should
work at least on x86, x86_64 (amd64) and ppc.

Contributing patches to grml
----------------------------

Software written by and maintained by the grml-team is available at
link:http://git.grml.org/[git.grml.org]. If you plan to provide a patch to
the grml-team you can checkout the according repository and create a patch
using the 'git diff' or even better the 'git format-patch' command. Usage
example:

[shell]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
% git clone git://git.grml.org/grml-policy.git
% cd grml-policy
% git checkout -b mygreatfeature
% [hack hack hack]
% git commit -a
% git format-patch master
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

And mail the resulting patches to the grml-team with your favourite mail
client or using 'git send-email'. The maintainer of the according
repository is listed in the owner-column on
link:http://git.grml.org/[git.grml.org]. You are free to
link:http://grml.org/contact/[contact the grml-team directly via mail],
link:http://bts.grml.org/[the grml bug tracking system], or the
link:http://grml.org/mailinglist/[grml-mailinglist] as well.

More details regarding use of git within grml is available at
link:http://grml.org/git/[grml.org/git/].

Common practices for writing code
---------------------------------

Header information
~~~~~~~~~~~~~~~~~~

Every script should provide a header which should look like this:

  #!/bin/sh
  # Filename:      grml2hd
  # Purpose:       install grml to harddisk
  # Authors:       grml-team (grml.org), (c) Andreas Gredler <jimmy@grml.org>, Michael Prokop <mika@grml.org>
  # Bug-Reports:   see http://grml.org/bugs/
  # License:       This file is licensed under the GPL v2.
  # Latest change: Thu Sep 13 23:00:56 CEST 2007 [mika]
  ################################################################################

Footer information
~~~~~~~~~~~~~~~~~~

Most developers of the grml-team use Vim as their favourite editor.
Therefor providing a modeline at the end of the sourcefile is commonly used
to indicate the favourite editing mode/style. Usage example:

  # vim: autoindent filetype=sh expandtab shiftwidth=4

grml shellscript library
~~~~~~~~~~~~~~~~~~~~~~~~

The grml system provides several shellscript resources. The package
grml-etc-core provides the files /etc/grml/lsb-functions and
/etc/grml/script-functions, the package grml-shlib ships /etc/grml/sh-lib.

/etc/grml/lsb-functions
^^^^^^^^^^^^^^^^^^^^^^^

The file /etc/grml/lsb-functions is used within init-scripts and init-style
scripts (like shellscripts handling with services) and is supposed to be
POSIX-compatible. Usage example:

[shell]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
% source /etc/grml/lsb-functions
% einfo "Starting foobar." ; /bin/true ; eend $?
 * Starting foobar.                                  [ ok ]
% einfo "Starting foobar." ; /bin/false ; eend $?
 * Starting foobar.                                  [ !! ]
%
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to provide output on the plain console (without using an
interface like link:http://invisible-island.net/dialog/[dialog] or
link:http://www.clifford.at/stfl/[stfl]) you should consider the use of
/etc/grml/lsb-functions so look and feel of grml-scripts is as consistent
as possible.

/etc/grml/script-functions
^^^^^^^^^^^^^^^^^^^^^^^^^^

The file /etc/grml/script-functions provides common functions used inside
several scripts, like check4root (check for root-permissions), iszsh (check
for running zsh). The file is supposed to work with every POSIX-compatible
shell (otherwise it's a bug).

/etc/grml/sh-lib
^^^^^^^^^^^^^^^^

The file /etc/grml/sh-lib provides a smiliar functionality like
/etc/grml/lsb-functions and /etc/grml/script-functions do. As a long term
goal the functionality of this file should be merged with the one of
lsb-functions and script-functions.

Good practices for shellscript
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* **shebang line:** if you use '#!/bin/sh' as the shebang line of your
shellscript you should make sure that the script runs under every
POSIX-compatible shell. A good test is the use of /bin/dash for /bin/sh. If
you use bash/zsh/ksh93/...  specific features please use the according
shell in the shebang line of your script.

* **check for appropriate permissions:** if you need root permissions you
should make sure that your script is running as user root (take a look at
check4root function provided by /etc/grml/script-functions).

* **clean up when being interrupted and on exit:** your script should not leave
any temporary files (unless intented for debugging purposes of course).
Usage example:
+
[shell]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TMPFILE=$(mktemp ${TMP}/grml2hd.XXXXXX)
bailout() {
  rm -f "$TMPFILE"
  [ -n "$1" ] && EXIT="$1" || EXIT="1"
  exit "$EXIT"
}
trap bailout 1 2 3 15
$CODE
bailout 0
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* **use of subshells:** please use _$(...)_ instead of _\`...\`_.
+
It allows nesting of commands in a more clearly and easier way.
Therefore any shell code might appear within the parentheses, since
the only time parentheses occur unquoted is in pairs. +
With backquotes however any unquoted _\`_ within the form _\`...\`_
would end the quotes immediately.
+
Consider the following as an example on readability:
+
[shell]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
% echo "Tomorrow's date: `expr \`date +%d\` + 1`.`date +%m`."
% echo "Tomorrow's date: $(expr $(date +%d) + 1).$(date +%m)."
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
Furthermore it can get quite tricky to get the right level of quotes
when using backquotes.
+
[shell]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
% print "`echo \"hello\"`"
hello
% print "$(echo \"hello\")"
"hello"
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
For further reading have a look at
link:http://zsh.dotsrc.org/Guide/zshguide05.html#l11[A User's Guide to the
Z Shell]
and link:http://zsh.sourceforge.net/Intro/intro_7.html#SEC7[Introduction to
the Z Shell]

* **if ... then ... else ... etc.**: Use the coding style used in other
shell scripts shipped by grml, like:
+
[shell]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## use the following forms:

if [ -n "$FOO" ] ; then
    bar
else
    baz
fi

while [ -n "$FOO" ] ; do
    bar
done

## instead of these:

if [ -n "$FOO" ]
then
    bar
else
    baz
fi

while [ -n "$FOO" ]
do
    bar
done
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* **whitespace:** make sure you indent your code and use blank lines where
according. Commonly accepted textwidth is 80 chars. (TODO: provide some
more information...)

* **indenting and use of tabs:** the grml-team prefers to **not** use any
tabs inside their code. Please use 4 spaces instead of a tab instead
('tabstop=4' and 'set expandtab' when using Vim editor). To replace tabs
with spaces you can use ':set expandtab' and ':retab' using Vim editor.

* **no trailing whitespaces:** make sure your code does not contain any
trailing whitespaces. Remove them inside Vim editor running ':%s/\s\+$//'
and make them visible using for example ':set
listchars=eol:$,precedes:«,extends:»,tab:»·,trail:·'.

About this document
-------------------

(C) Michael Prokop <mika@grml.org>; HTML version powered by link:http://www.methods.co.nz/asciidoc/[asciidoc].

// vim: ft=asciidoc autoindent textwidth=75 formatoptions=tcqn