Skip to content

Latest commit

 

History

History
166 lines (92 loc) · 3.24 KB

HACKING.pod

File metadata and controls

166 lines (92 loc) · 3.24 KB
Raw

NAME

HACKING.pod - contributing to Munin

SYNOPSIS

This is the guide for Munin internals contributors (developers, testers, documenters.)

If you are looking for more information on how to use Munin you probably want http://munin-monitoring.org/wiki/Documentation instead.

The munin code is marked by years on the battle front. You will therefore find code that deviates from the guidelines defined here. However, all new code should be made to comply.

GETTING STARTED

In the dev_script directory you will find scripts that are meant to be useful for developing. Most of them are tools for creating and using munin in a sandbox.

THE SANDBOX

install

To make a clean rebuild of the sandbox

./dev_scripts/install 1

To just install the latest changes

./dev_scripts/install
enable/disable tls

To test TLS, you can enable a paranoid TLS configuration by running:

./dev_scripts/enable_tls

And disable it with:

./dev_scripts/disable_tls
start/stop munin-node
./dev_scripts/start_munin-node [munin-node params ...]

And

./dev_scripts/stop_munin-node

To do both:

./dev_scripts/restart_munin-node [munin-node params ...]
query_munin_node

Use this command to query the munin-node directly:

./dev_scripts/query_munin_node list
run

To run Munin master programs (munin-update, munin-cron, etc) use the run command.

./dev_scripts/run CMD [CMD args ...]

PUNCTUATION VARIABLES

Don't use punctuation variables (see Perl Best Practices page 79.)

use English qw(-no_match_vars);

We'll add an exception for $_, and $! as they should be fairly widely recognized.

FORMATTING

Tabs

We prefer indentation via tabs. Space-based indentation is usually relying on editor magic to ease the pain. That said, nothing should be vertical-aligned. Only indentated correctly.

When a subblock is started, always use one level.

Braces

Braces should go on the same line.

Wrapping

Wrapping in code is discouraged. It does not make any sense to force wrap at a fixed amount of columns. A much better rule is the following (1 stmt/line).

Comments on the other side, are to be wrapped at 78 chars, since they are a block of text anyway. Any space formatting is encouraged, since it usually helps. ASCII art is a must ;-)

1 stmt/line

Only put 1 statement per line. If the expression is complex, break it in elementary subexpressions, with meaniful temp vars.

TESTS AND COVERAGE

Use test-driven devolopment.

In node, server, or common:

perl Build.PL
./Build test

EXCEPTION HANDLING

Currently there is no unified approach to handling exceptions. Use Carp?

use Carp;
croak("Foo happened!");

confess("Foo happened!"); # With stack trace

Exceptions are caught with an eval:

eval {
    # Exceptionally scary code
};
if ($EVAL_ERROR) {
    # Handle exception
}

DOCUMENTATION

The API documentation is embedded as POD in the code. See perlpod for more on POD.

More is on http://munin-monitoring.org/wiki/Documentation

WRITING

The POD should be defined all in one place. For plugins you place it at the top, else at the bottom.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 123:

You forgot a '=back' before '=head1'