summaryrefslogtreecommitdiffstats
path: root/doc/developer-guidelines.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/developer-guidelines.sgml')
-rw-r--r--doc/developer-guidelines.sgml92
1 files changed, 79 insertions, 13 deletions
diff --git a/doc/developer-guidelines.sgml b/doc/developer-guidelines.sgml
index 42ad896..3edca6b 100644
--- a/doc/developer-guidelines.sgml
+++ b/doc/developer-guidelines.sgml
@@ -109,7 +109,42 @@
109 when it notifies contacts about potential problems. If you print 109 when it notifies contacts about potential problems. If you print
110 multiple lines, you're out of luck. Remember, keep it short and 110 multiple lines, you're out of luck. Remember, keep it short and
111 to the point.</para> 111 to the point.</para>
112 </section> 112 </section>
113
114 <section><title>Verbose output</title>
115 <para>Use the -v flag for verbose output. You should allow multiple
116 -v options for additional verbosity, up to a maximum of 3. The standard
117 type of output should be:</para>
118
119 <table id="verbose_levels"><title>Verbose output levels</title>
120 <tgroup cols="2">
121 <thead>
122 <row>
123 <entry><para>Verbosity level</para></entry>
124 <entry><para>Type of output</para></entry>
125 </row>
126 </thead>
127 <tbody>
128 <row>
129 <entry align=center><para>0</para></entry>
130 <entry><para>Single line, minimal output. Summary</para></entry>
131 </row>
132 <row>
133 <entry align=center><para>1</para></entry>
134 <entry><para>Single line, additional information (eg list processes that fail)</para></entry>
135 </row>
136 <row>
137 <entry align=center><para>2</para></entry>
138 <entry><para>Multi line, configuration debug output (eg ps command used)</para></entry>
139 </row>
140 <row>
141 <entry align=center><para>3</para></entry>
142 <entry><para>Lots of detail for plugin problem diagnosis</para></entry>
143 </row>
144 </tbody>
145 </tgroup>
146 </table>
147 </section>
113 148
114 <section><title>Screen Output</title> 149 <section><title>Screen Output</title>
115 <para>The plug-in should print the diagnostic and just the 150 <para>The plug-in should print the diagnostic and just the
@@ -345,9 +380,8 @@
345 <section><title>Option Processing</title> 380 <section><title>Option Processing</title>
346 381
347 <para>For plugins written in C, we recommend the C standard 382 <para>For plugins written in C, we recommend the C standard
348 getopt library for short options. If using getopt_long, check to 383 getopt library for short options. Getopt_long is always available.
349 be sure that HAVE_GETOPT_H is defined (configure checks this and 384 </para>
350 sets the #define in common/config.h).</para>
351 385
352 <para>For plugins written in Perl, we recommend Getopt::Long module.</para> 386 <para>For plugins written in Perl, we recommend Getopt::Long module.</para>
353 387
@@ -363,6 +397,7 @@
363 -w warning threshold (--warning) 397 -w warning threshold (--warning)
364 -c critical threshold (--critical) 398 -c critical threshold (--critical)
365 -H hostname (--hostname) 399 -H hostname (--hostname)
400 -v verbose (--verbose)
366 </literallayout> 401 </literallayout>
367 402
368 <para>In addition to the reserved options above, some other standard options are:</para> 403 <para>In addition to the reserved options above, some other standard options are:</para>
@@ -397,6 +432,9 @@
397 help. Help text should fit on an 80-character width display, but 432 help. Help text should fit on an 80-character width display, but
398 may run as many lines as needed.</para> 433 may run as many lines as needed.</para>
399 434
435 <para>The option -v or --verbose should be present in all plugins.
436 The user should be allowed to specify -v multiple times to increase
437 the verbosity level, as described in <xref linkend="verbose_levels">.</para>
400 </section> 438 </section>
401 439
402 <section> 440 <section>
@@ -405,7 +443,7 @@
405 443
406 <para>Old style was to do things like -ct for critical time and 444 <para>Old style was to do things like -ct for critical time and
407 -cv for critical value. That goes out the window with POSIX 445 -cv for critical value. That goes out the window with POSIX
408 getopt. The allowable alternatves are:</para> 446 getopt. The allowable alternatives are:</para>
409 447
410 <orderedlist> 448 <orderedlist>
411 <listitem> 449 <listitem>
@@ -449,23 +487,51 @@
449 487
450 <para>As always, comments are welcome - making this consistent 488 <para>As always, comments are welcome - making this consistent
451 without a host of long options was quite a hassle, and I would 489 without a host of long options was quite a hassle, and I would
452 suspect that there are flaws in this strategy. Perhaps clear 490 suspect that there are flaws in this strategy.
453 long-options is the most important of the above choices, but not 491 </para>
454 all POSIX systems have C libraries for long options, so the
455 short forms must exist as well.</para>
456 </section> 492 </section>
457</section> 493</section>
458 494
495<section id="CodingGuidelines"><title>Coding guidelines</title>
496 <para>See <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU
497 Coding standards</ulink> for general guidelines.</para>
498 <section><title>Comments</title>
499 <para>You should use /* */ for comments and not // as some compilers
500 do not handle the latter form</para>
501 </section>
502</section>
503
459<section id="SubmittingChanges"><title>New submissions and patches</title> 504<section id="SubmittingChanges"><title>New submissions and patches</title>
460 505
461 <para>If you would like other to use your plugins and have it included in 506 <para>If you would like others to use your plugins and have it included in
462 the standard distribution, please include patches for the relavant 507 the standard distribution, please include patches for the relevant
463 configuration files, in particular "configure.in" Otherwise submitted 508 configuration files, in particular "configure.in". Otherwise submitted
464 plugins will be included in the contrib directory.</para> 509 plugins will be included in the contrib directory.</para>
465 510
466 <para>Plugins in the contrib directory are going to be migrated to the 511 <para>Plugins in the contrib directory are going to be migrated to the
467 standard plugins/plugin-scripts directory as time permits and per user 512 standard plugins/plugin-scripts directory as time permits and per user
468 requests</para> 513 requests. The minimum requirements are:</para>
514
515 <orderedlist>
516 <listitem>
517 <para>The standard command options are supported (--help, --version,
518 --timeout, --warning, --critical)</para>
519 </listitem>
520 <listitem>
521 <para>It is determined to be not redundant (for instance, we would not
522 add a new version of check_disk just because someone had provide
523 a plugin that had perf checking - we would incorporate the features
524 into an exisiting plugin)</para>
525 </listitem>
526 <listitem>
527 <para>One of the developers has had the time to audit the code and declare
528 it ready for core</para>
529 </listitem>
530 <listitem>
531 <para>It should also follow code format guidelines, and use functions from
532utils (perl or c or sh) rather than cooking it's own</para>
533 </listitem>
534 </orderedlist>
469 535
470 <para>Patches should be submitted via the SourceForge and be announced to 536 <para>Patches should be submitted via the SourceForge and be announced to
471 the mailing list.</para> 537 the mailing list.</para>