Skip to content

Latest commit

 

History

History
270 lines (154 loc) · 6.32 KB

HACKING.pod

File metadata and controls

270 lines (154 loc) · 6.32 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://guide.munin-monitoring.org/ instead.

You can find some additional contributing information at http://guide.munin-monitoring.org/en/latest/others/index.html#contributing.

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

GITHUB

The main development of Munin is happening on https://github.com. After registering an account you can report feature requests and issues (https://github.com/munin-monitoring/munin/issues/new/choose) and create pull requests (https://github.com/munin-monitoring/munin/pulls).

There are two interesting branches:

stable-2.0

As the name suggests this is the stable branch for versions (currently 2.0.x). Please base your bug-fix patches (for core and plugins) on this branch. They will get merged by time into master.

master

This is the development branch of munin. Please base your non bug-fix patches, like new features/plugins, rewrites, cleanup etc., on this branch.

THE SANDBOX

In the dev_scripts 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.

install

To make a clean rebuild of the sandbox:

./dev_scripts/install clean
./dev_scripts/install node

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 programs (munin-update, munin-cron, munin-node-configure, munin-run etc.), use this command. It ensures a correct invocation in relation to perl's taint mode.

./dev_scripts/run CMD [CMD args ...]
start munin-httpd

To start the Munin http web front-end, run the following:

./dev_scripts/start_munin-httpd

This will start the web server on port 4946.

Make sure to run munin-update at least once before visiting the site.

CODING STYLE

GENERAL

Strictness and Warnings

Perl code should be written in tainted-mode with the settings use strict; and use warnings;.

There should be no perl warnings when running Munin.

Spaces vs Tabs

In general we prefer indentation via tabs.

But due to many space based indentations in the current codebase is it sufficient to follow the overall style of the file in question.

When a sub-block is started, always use one level.

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 sub-expressions, with meaningful temporary variables.

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 ($@) {
  # Handle exception
}
punctuation variables

Don't use punctuation variables (see Perl Best Practices page 79.). Use the English clear names:

use English qw(-no_match_vars);

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

PERLTIDY [inactive]

We use perltidy to automatically format perl code. This ensures a consistent style and a tool-based enforcement. The exact configuration can be seen in the file .perltidyrc. Please try to use it before any contribution by running make apply-formatting.

TODO: discuss perltidy style, see #1014

PERLCRITIC

perlcritic is used to comply to some wide-spread recommendations. The exact configuration can be seen in the file .perlcriticrc. Please try to comply with those rules by running c<make lint>.

TODO: discuss perlcritc style, see #1051

Commit messages

Please use the present tense ("Add feature" not "Added feature"), the imperative mood ("Move cursor to..." not "Moves cursor to...") and some standard commit formatting (look at the one already made).

TESTS AND COVERAGE

Use test-driven development.

In node, server, or common:

perl Build.PL
./Build test

Munin uses https://travis-ci.org/ to automatically build after each commit. Make sure your pull-requests succeeds.

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.

For scripts the recommend headers are (in this order):

NAME, SYNOPSIS, DESCRIPTION, REQUIRED ARGUMENTS, OPTIONS, EXIT STATUS,
CONFIGURATION, FILES, VERSION, BUGS AND LIMITATIONS, AUTHOR,
LICENSE AND COPYRIGHT

B<TODO>: discuss

For modules the recommend headers are (in this order):

NAME, SYNOPSIS, DESCRIPTION, SUBROUTINES/METHODS,
CONFIGURATION AND ENVIRONMENT, DEPENDENCIES, BUGS AND LIMITATIONS, AUTHOR,
LICENSE AND COPYRIGHT

B<TODO>: discuss

For plugins the recommend headers are (in this order):

NAME, APPLICABLE SYSTEMS, CONFIGURATION, USAGE, MAGIC MARKERS, BUGS, AUTHOR,
LICENSE AND COPYRIGHT

B<TODO>: discuss

END

If you find any code not matching these recommendations, feel free to contribute a patch.