Style Guide

This document provides rules on how new features should be provided within Opsview.

• All files must have a copyright statement on it, of the form: Copyright (C) year-now Opsera Limited. All rights reserved
• All files must have a licence statement

• All new form fields must link to the online help documentation
• All list pages should display a suitable message if no items in there are no items in the list
• If a field requires numeric input, you must specify units (if applicable)
• Add validation for any free text fields - better to be too strict than not strict enough
• Validation should be set at model layer as much as possible
• Ensure UI validation matches model validation
• If validation errors re: invalid characters, make sure error message either says which characters, or explain what valid characters are
• All images should have a title attribute so a suitable tooltip is displayed
• Documentation on http://docs.opsview.org should be updated to reflect any changes
• Add an audit log entry if applicable
• When adding new questions, make sure it makes sense within a context. A random question about router, switch or server may be “why?”, but if as part of setting up NMIS, is more understandable

• Field labels and titles should be in a capitalisation in titles format. See title_capitalisation for more details
• List pages should have a title of a plural based on the type. Use singular for edit, new, or clone pages
• Messages and help sentences should follow normal English grammar. Ignore the trailing full stop

• If script is to be written, should be in perl, then bash. Only sh if absolutely necessary.

• If configuration change and is not applicable until a reload, ensure configuration status is reflected and row is highlighted
• If nagconfgen updated, only raise a fatal warning when absolutely necessary - should try and continue when possible.

These aspects need to be considered:

• Distributed environments
• Clustered node environments
• Security
• ODW

The general principle is:

• User input assumes local timezone
• Display output applies local timezone
• Everything else should be in UTC

The ideal is each contact has a timezone set for the user. The current design is that everything is based on the application server and database server's timezone.

Warning: if using DateTime module to calculate times, make sure everything is in timezone = “local”. The default is timezone=“floating”, which means “no timezone”.

Make sure tests in opsview-core and opsview-web are updated to cover new functionality.

Fact tables with additive data, such as service_availability_hourly_summary, should not have any columns with NULL. If creating new columns for the table and data is not available historically, populate the column with “next best” values, with an assumption of “worst case”.

For instance, if adding a column called seconds_not_ok_hard, populate this column with seconds_not_ok. This will effectively mean that all services went immediately into a hard state, which is a reasonable assumption to make from a historical perspective.

Similarly, adding in seconds_unacknowledged, populate with seconds_not_ok. This means that all failures were not acknowledged - again a worst case scenario, but acceptable given the circumstances.

All perl code should be fed through 'perltidy -pbp <filename>' before committing to the repository to ensure all code is consistently laid out. If the formatting changes large amount of code, the style change should be done in two steps:

1. commit all code changes
2. reform code and commit changes

This is to separate the changes into logic changes and style changes, which eases tracking bug etymology.

See the development server setup instructions on using the central vimrc and perltidyrc configuration files.

If there are any special cases where you want to exclude perltidy from formatting (for instance, Runtime::Searches has a special list style for the select statement in list_services), then use perltidy's ignore characters:

#<<< ignore perltidy - retain simpler list format
....
#>>>

When updating this repository, if you upgrade perl modules from CPAN, add a comment to the CHANGES file with a date when the upgrade occurred.

All HTML templates should maintain the style within the file itself. Prioritise on readability of the template, not the resultant HTML.

Some templates have slightly different styling, but this is being resolved over time.

When committing into SVN, follow these guidelines:

• ensure perl files have had perltidy run against it. SVN has a pre commit hook to validate that perltidy has been run and matches
• try to commit a single change at a time
• if the commit is related to a jira, add the jira reference, eg OPS-666
• if this was a submitted patch, add author's name to commit message and update http://opsview.org/contributors
• update CHANGES file with the categories
  • FEATURES - major new features
  • ENHANCEMENTS - minor changes
  • FIXES - bugs that have been fixed or package dependencies which have been fixed (one liners like “rrdtool minimum version is now 1.2” or “libcairo is required” - leave details to package info files)
  • WARNINGS - any incompatibilities or breakages that may occur
  • TRANSLATIONS - flag for any translations that maybe required
• If merging, CHANGES file should have the changes merged into the appropriate category
• if it is a sponsored feature and sponsor would like to be recognised:
  • add the sponsor name to the commit message
  • add sponsor to CHANGES file
  • add sponsor to page http://opsview.org/sponsorship, with a one-liner of the change

If sponsor is not an individual the official name of company or organisation should be used.

These are expected tools on a developer system.

If you want to setup for Opsview Core, see the developmentserver document.

A great perl tool for grepping source files. Requires bootstrapping an environment with local::lib perl module and then installing via CPAN. See http://search.cpan.org/dist/local-lib/lib/local/lib.pm for the bootstrap technique, summarised here:

su - opsview
cd /tmp
wget .... # From http://search.cpan.org/dist/local-lib
tar --gzip -xf .... # Extract file
cd ... # Directory created
perl Makefile.PL --bootstrap
make test && make install
echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
exit
su - opsview
echo $PERL5LIB  # Should contain entries for ~/perl5/lib/perl5
cpan install App::Ack