index e3fe4c8c192f6d9a1bb272de2910160a449a4cf3..3c37e5c104a858c9faeed19794f18fb776410813 100644 (file)
<bookinfo>
<authorgroup>
<author>
- <firstname>Karl</firstname>
- <surname>DeBisschop</surname>
- <affiliation>
- <address><email>karl@debisschop.net</email></address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Ethan</firstname>
- <surname>Galstad</surname>
- <authorblurb>
- <para>Author of Nagios</para>
- <para><ulink url="http://www.nagios.org"></ulink></para>
- </authorblurb>
- <affiliation>
- <address><email>netsaint@linuxbox.com</email></address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Hugo</firstname>
- <surname>Gayosso</surname>
- <affiliation>
- <address><email>hgayosso@gnu.org</email></address>
- </affiliation>
- </author>
-
-
- <author>
- <firstname>Subhendu</firstname>
- <surname>Ghosh</surname>
- <affiliation>
- <address><email>sghosh@sourceforge.net</email></address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Stanley</firstname>
- <surname>Hopcroft</surname>
- <affiliation>
- <address><email>stanleyhopcroft@sourceforge.net</email></address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Ton</firstname>
- <surname>Voon</surname>
- <affiliation>
- <address><email>tonvoon@users.sourceforge.net</email></address>
- </affiliation>
- </author>
-
- <author>
- <firstname>Jeremy T</firstname>
- <surname>Bouse</surname>
- <affiliation>
- <address><email>undrgrid@users.sourceforge.net</email></address>
- </affiliation>
+ <affiliation>
+ <orgname>Nagios Plugins Development Team</orgname>
+ </affiliation>
</author>
</authorgroup>
- <pubdate>2002</pubdate>
+ <pubdate>2005</pubdate>
<title>Nagios plug-in development guidelines</title>
<revhistory>
</revhistory>
<copyright>
- <year>2000 - 2004</year>
+ <year>2000 - 2005</year>
<holder>Nagios Plugins Development Team</holder>
</copyright>
the plug-in developers and encourage the standarization of the
different kind of plug-ins: C, shell, perl, python, etc.</para>
- <para>Nagios Plug-in Development Guidelines Copyright (C) 2000-2003
- (Karl DeBisschop, Ethan Galstad, Stanley Hopcroft, Subhendu Ghosh, Ton Voon, Jeremy T. Bouse)</para>
+ <para>Nagios Plug-in Development Guidelines Copyright (C) 2000-2005
+ (Nagios Plugins Team)</para>
<para>Permission is granted to make and distribute verbatim
copies of this manual provided the copyright notice and this
<literallayout>
gnu make 3.79
- automake 1.6
- autoconf 2.54
+ automake 1.8
+ autoconf 2.58
gettext 0.11.5
</literallayout>
<para>Output should be in the format:</para>
<literallayout>
- METRIC STATUS: Information text
+ SERVICE STATUS: Information text
</literallayout>
<para>However, note that this is not a requirement of the API, so you cannot depend on this
being an accurate reflection of the status of the service - the status should always
crt (remember when fixing stuff in the server room!)</para>
</section>
- <section><title>Return the proper status code</title>
- <para>See <xref linkend="ReturnCodes"> below
- for the numeric values of status codes and their
- description. Remember to return an UNKNOWN state if bogus or
- invalid command line arguments are supplied or it you are unable
- to check the service.</para>
- </section>
-
<section><title>Plugin Return Codes</title>
<para>The return codes below are based on the POSIX spec of returning
a positive value. Netsaint prior to v0.0.7 supported non-POSIX
<entry align="center"><para>3</para></entry>
<entry valign="middle"><para>Unknown</para></entry>
<entry><para>Invalid command line arguments were supplied to the
- plugin or the plugin was unable to check the status of the given
- hosts/service</para></entry>
+ plugin or low-level failures internal to the plugin (such as unable to fork,
+ or open a tcp socket) that prevent it from performing the specified
+ operation. Higher-level errors (such as name resolution errors,
+ socket timeouts, etc) are outside of the control of plugins and should
+ generally NOT be reported as UNKNOWN states.
+ </para></entry>
</row>
</tbody>
</tgroup>
</section>
<section><title>Translations</title>
- <para>If possible, use translation tools for all output. Currently, most of the core C plugins
- use gettext for translation. General guidelines are:</para>
-
- <orderedlist>
- <listitem><para>short help is not translated</para></listitem>
- <listitem><para>long help has options in English language, but text translated</para></listitem>
- <listitem><para>"Copyright" kept in English</para></listitem>
- <listitem><para>copyright holder names kept in original text</para></listitem>
- </orderedlist>
+ <para>If possible, use translation tools for all output to respect the user's language
+ settings. See <xref linkend="translations_developers"> for guidelines
+ for the core plugins.
+ </para>
</section>
</section>
</section>
</section>
+<section id="Testcases"><title>Test cases</title>
+<para>
+Tests are the best way of knowing if the plugins work as expected. Please
+create and update test cases where possible.
+</para>
+
+<para>
+To run a test, from the top level directory, run "make test". This will run
+all the current tests and report an overall success rate.
+</para>
+
+<para>
+See the <ulink url="http://tinderbox.altinity.org">Nagios Plugins Tinderbox server</ulink>
+for the daily test results.
+</para>
+
+<section><title>Test cases for plugins</title>
+<para>These use perl's Test::More. To do a one time test, run "cd plugins && perl t/check_disk.t".
+</para>
+
+<para>There will somtimes be failures seen in this output which are known failures that
+need to be fixed. As long as the return code is 0, it will be reported as "test pass".
+(If you have a fix so that the specific test passes, that will be gratefully received!)
+</para>
+
+<para>
+If you want a summary test, run: "cd plugins && perl -MTest::Harness -e 'runtests(@ARGV)' t/check_disk.t".
+This runs the test in a summary format.
+</para>
+
+<para>
+For a good and amusing tutorial on using Test::More, see this
+<ulink url="http://search.cpan.org/~mschwern/Test-Simple-0.62/lib/Test/Tutorial.pod">
+link</ulink>
+</para>
+
+</section>
+
+<section><title>Testing the C library functions</title>
+<para>
+Will be looking at using libtap, which is utilised by the FreeBSD team. The output is
+based on perl's TAP (Test Anything Protocol) format, so that Test::Harness will understand
+results. This is still in planning stages.
+</para>
+</section>
+
+</section>
<section id="CodingGuidelines"><title>Coding guidelines</title>
<para>See <ulink url="http://www.gnu.org/prep/standards_toc.html">GNU
Coding standards</ulink> for general guidelines.</para>
<section><title>Comments</title>
<para>You should use /* */ for comments and not // as some compilers
do not handle the latter form.</para>
- <para>There should not be any named credits in the source code - contributors
- should be added
- into the AUTHORS file instead. The only exception to this is if a routine
- has been copied from another source.</para>
+ <para>If you have copied a routine from another source, make sure the licence
+ from your source allows this. Add a comment referencing the ACKNOWLEDGEMENTS
+ file, where you can put more detail about the source.</para>
+ <para>For contributed code, do not add any named credits in the source code
+ - contributors should be added into the THANKS.in file instead.
+ </para>
</section>
<section><title>CVS comments</title>
</para>
<para>If the change is due to a contribution, please quote the contributor's name
and, if applicable, add the SourceForge Tracker number. Don't forget to
-update the AUTHORS file.</para>
+update the THANKS.in file.</para>
</section>
+
+ <section id="translations_developers"><title>Translations for developers</title>
+ <para>To make the job easier for translators, please follow these guidelines:</para>
+ <orderedlist>
+ <listitem><para>
+ Before creating new strings, check the po/nagios-plugins.pot file to
+ see if a similar string
+ already exists
+ </para></listitem>
+ <listitem><para>
+ For help texts, break into individual options so that these can be reused
+ between plugins
+ </para></listitem>
+ <listitem><para>Try to avoid linefeeds unless you are working on a block of text</para></listitem>
+ <listitem><para>Short help is not translated</para></listitem>
+ <listitem><para>Long help has options in English language, but text translated</para></listitem>
+ <listitem><para>"Copyright" kept in English</para></listitem>
+ <listitem><para>Copyright holder names kept in original text</para></listitem>
+ <listitem><para>Debugging output does not need to be translated</para></listitem>
+ </orderedlist>
+ </section>
+
+ <section><title>Translations for translators</title>
+ <para>To create an up to date list of translatable strings, run: tools/gen_locale.sh</para>
+ </section>
+
</section>
<section id="SubmittingChanges"><title>Submission of new plugins and patches</title>
</section>
<section id="Newplugins"><title>New plugins</title>
- <para>If you would like others to use your plugins and have it included in
- the standard distribution, please include patches for the relevant
- configuration files, in particular "configure.in". Otherwise submitted
- plugins will be included in the contrib directory.</para>
-
- <para>Plugins in the contrib directory are going to be migrated to the
- standard plugins/plugin-scripts directory as time permits and per user
- requests. The minimum requirements are:</para>
+
+ <para>If you would like others to use your plugins, please add it to
+ the official 3rd party plugin repository,
+ <ulink url="http://www.nagiosexchange.org">NagiosExchange</ulink>.
+ </para>
+
+ <para>We are not accepting requests for inclusion of plugins into
+ our distribution at the moment, but when we do, these are the minimum
+ requirements:
+ </para>
<orderedlist>
+ <listitem>
+ <para>Include copyright and license information in all files</para>
+ </listitem>
<listitem>
<para>The standard command options are supported (--help, --version,
--timeout, --warning, --critical)</para>
</listitem>
<listitem>
<para>It should also follow code format guidelines, and use functions from
-utils (perl or c or sh) rather than cooking it's own</para>
+utils (perl or c or sh) rather than using its own</para>
+ </listitem>
+ <listitem>
+ <para>Includes patches to configure.in if required (via the EXTRAS list if
+ it will only work on some platforms)</para>
+ </listitem>
+ <listitem>
+ <para>If possible, please submit a test harness. Documentation on sample
+ tests coming soon</para>
</listitem>
</orderedlist>
- <para>New plugins should be submitted via
- <ulink url="http://sourceforge.net/tracker/?group_id=29880&atid=541465">SourceForge's
- tracker system for Nagiosplug new plugins</ulink>
- and be announced to the nagiosplug-devel mailing list.</para>
-
- <para>For new plugins, provide a diff to add to the EXTRAS list (configure.in)
- unless you are fairly sure that the plugin will work for all platforms with
- no non-standard software added.</para>
-
- <para>If possible please submit a test harness. Documentation on sample
- tests coming soon.</para>
</section>
</section>
-
-<section id="UsingSourceforge"><title>Using Sourceforge</title>
-<table id="Projectmemberaccess"><title>Project Member Access</title>
- <tgroup cols="9">
- <thead>
- <row>
- <entry><para>Member type</para></entry>
- <entry><para>CVS Access</para></entry>
- <entry><para>Shell Access</para></entry>
- <entry><para>Release Tech</para></entry>
- <entry><para>Tracker Manager</para></entry>
- <entry><para>Task Manager</para></entry>
- <entry><para>Forums</para></entry>
- <entry><para>Doc Manager</para></entry>
- <entry><para>News</para></entry>
- <entry><para>Screenshots</para></entry>
- <entry><para>Notes</para></entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><para>Translator</para></entry>
- <entry><para>Yes</para></entry>
- <entry><para>Yes</para></entry>
- <entry><para>No</para></entry>
- <entry><para>-</para></entry>
- <entry><para>-</para></entry>
- <entry><para>-</para></entry>
- <entry><para>-</para></entry>
- <entry><para>-</para></entry>
- <entry><para>-</para></entry>
- <entry><para>Add developer to CVSROOT/avail for translation files</para></entry>
- </row>
- <row>
- <entry><para>Developer</para></entry>
- <entry><para>Yes</para></entry>
- <entry><para>Yes</para></entry>
- <entry><para>No</para></entry>
- <entry><para>-</para></entry>
- <entry><para>A&T</para></entry>
- <entry><para>Moderator</para></entry>
- <entry><para>Editor</para></entry>
- <entry><para>-</para></entry>
- <entry><para>-</para></entry>
- <entry><para>Need to set tracker access individually. Add developer to CVSROOT/avail for all files</para></entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-<para>Add all members to the nagiosplug-team mailing list</para>
-</section>
</article>
</book>