File: HACKING.pod

package info (click to toggle)
munin 2.999.14-1
  • links: PTS, VCS
  • area: main
  • in suites: experimental
  • size: 10,036 kB
  • sloc: perl: 31,052; sh: 12,473; java: 1,924; python: 852; makefile: 336; ruby: 232; awk: 169; xml: 45; sql: 11
file content (270 lines) | stat: -rw-r--r-- 6,471 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
# this is in pod format (try `perldoc HACKING.pod`)

=pod

=head1 NAME

HACKING.pod - contributing to Munin

=head1 SYNOPSIS

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

If you are looking for more information on how to I<use> Munin you
probably want L<http://guide.munin-monitoring.org/> instead.

You can find some additional contributing information at
L<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.


=head1 GETTING STARTED


=head2 GITHUB

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

There are two interesting branches:

=over

=item I<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.

=item I<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.

=back


=head2 THE SANDBOX

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

=over

=item B<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

=item B<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

=item B<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 ...]

=item B<query_munin_node>

Use this command to query the munin-node directly:

  ./dev_scripts/query_munin_node list

=item B<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 ...]

=item B<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 B<munin-update> at least once before visiting the site.

=back


=head1 CODING STYLE

=head2 GENERAL

=over 12

=item C<Strictness and Warnings>

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

There should be no perl warnings when running Munin.

=item C<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.

=item C<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 ;-)

=item C<1 stmt/line>

Only put 1 statement per line. If the expression is complex, break it in
elementary sub-expressions, with meaningful temporary variables.

=item C<exception handling>

Currently there is no unified approach to handling exceptions. Use L<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
  }

=item C<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.

=back


=head2 PERLTIDY [inactive]

We use B<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 I<.perltidyrc>. Please try to use it before any contribution by running
C<make apply-formatting>.

B<TODO>: discuss perltidy style, see #1014


=head2 PERLCRITIC

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

B<TODO>: discuss perlcritc style, see #1051


=head2 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).


=head1 TESTS AND COVERAGE

Use test-driven development.

In node, server, or common:

  perl Build.PL
  ./Build test

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


=head1 DOCUMENTATION

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

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


=head2 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


=head1 END

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

=cut