root/tags/1.4.2/HACKING.pod

Revision 2774, 2.5 kB (checked in by knan, 2 years ago)

Revert "Note to do 'make build' before trying the install script."

Root cause fixed by the "fix make clean twice" commit.

Line 
1 # this is in pod format (try `perldoc HACKING.pod`)
2
3 =pod
4
5 =head1 NAME
6
7 HACKING.pod - contributing to Munin
8
9 =head1 SYNOPSIS
10
11 This is the guide for Munin internals contributors (developers,
12 testers, documenters.)
13
14 If you are looking for more information on how to I<use> Munin you
15 probably want L<http://munin.projects.linpro.no/wiki/Documentation>
16 instead.
17
18 The munin code is marked by years on the battle front. You will
19 therefore find code that deviates from the guidelines defined
20 here. However, all new code should be made to comply.
21
22 These guidelines is an RFC for the time being and are of course
23 negotiable.
24
25
26 =head1 GETTING STARTED
27
28 In the dev_script directory you will find scripts that are meant to be
29 useful for developing. Most of them are tools for creating and using
30 munin in a sandbox.
31
32 =head2 THE SANDBOX
33
34 =over
35
36 =item B<install>
37
38 To make a clean rebuild of the sandbox
39
40  ./dev_scripts/install 1
41
42 To just install the latest changes
43
44  ./dev_scripts/install
45
46 =item B<enable/disable tls>
47
48 To test TLS, you can enable a paranoid TLS configuration by running:
49
50  ./dev_scripts/enable_tls
51
52 And disable it with:
53
54  ./dev_scripts/disable_tls
55
56 =item B<start/stop munin-node>
57
58  ./dev_scripts/start_munin-node [munin-node params ...]
59
60 And
61
62  ./dev_scripts/stop_munin-node
63
64 To do both:
65
66  ./dev_scripts/restart_munin-node [munin-node params ...]
67
68
69 =item B<query_munin_node>
70
71 Use this command to query the munin-node directly:
72
73  ./dev_scripts/query_munin_node list
74
75 =item B<run>
76
77 To run Munin master programs (munin-update, munin-html, munin-cron,
78 etc) use the run command.
79
80  ./dev_scripts/run CMD [CMD args ...]
81
82
83 =back
84
85
86 =head1 PUNCTUATION VARIABLES
87
88 Don't use punctuation variables (see PBP page 79.)
89
90  use English qw(-no_match_vars);
91
92 We'll add an exception for $_, and $! as they should be fairly widely
93 recognized.
94
95
96 =head1 FORMATTING
97
98 =head2 perltidy
99
100 FIX
101
102
103 =head1 TESTS AND COVERAGE
104
105 Use TDD.
106
107 In node, server, or common:
108
109  perl Build.PL
110  ./Build test
111
112
113 =head1 EXCEPTION HANDLING
114
115 Currently there is no unified approach to handling exceptions. Use
116 L<Carp>?
117
118  use Carp;
119  croak("Foo happened!");
120
121  confess("Foo happened!"); # With stack trace
122
123 Exceptions are caught with an eval
124
125  eval {
126      # Exceptionally scary code
127  };
128  if ($EVAL_ERROR) {
129      # Handle exception
130  }
131
132
133
134 =head1 DOCUMENTATION
135
136 The API documentation is embedded as POD in the code.  See L<perlpod>
137 for more on POD.
138
139 More is on L<http://munin.projects.linpro.no/wiki/Documentation>
140
141 =head2 WRITING
142
143 The POD should be defined all in one place. For plugins you place it at
144 the top, else at the bottom.
145
146 =cut
Note: See TracBrowser for help on using the browser.