[dev] Seeking Documentation/Error Advice

[Rick Emery]

Quoting Eric Rostetter <eric.rostetter at physics.utexas.edu>:

> Quoting Rick Emery <rick at emery.homelinux.net>:
>
> > There has been some concern over the new horde metar block, namely that
> > there
> > isn't any documentation about the requirement of pear's Services_Weather
> > module or the need to run the buildMetarDB script. If either of these
> > requirements isn't  met, it doesn't fail gracefully.
>
> Can it be made to fail gracefully?

Perhaps not. I had thought of displaying a message about missing requirements
in the block, but the block has to be configured first, and that's where the
errors appear (on the layout screen).

And this brings up a larger issue. My thinking was that the Services_Weather
package is optional if the metar block isn't going to be used, but there isn't
any way for an admin to turn off the metar block in registry.php (other than
commenting it out). If the admin can't turn it off, there's nothing preventing
a user from trying to use it. If the Services_Weather package isn't installed,
errors will occur in the layout screen (and the portal). I'm trying to think
of a way to display a formatted message for the user indicating what the
problem is. Pear errors will be displayed at the top of the screen, but will
they mean anything to a "user" (as opposed to an admin)?

Further, if the metar applet can't be turned off, does that mean the
Services_Weather package is now required for a horde install?

> > I'm looking for advice on how to handle this.
>
> Document it, and if possible make it fail gracefully.  But don't feel
> too much presure since it is HEAD code.  It should at least be put on
> the TODO list though.

Agreed, but eventually it will be in release code, so I might as well handle it
now :-)

> > Where should the need for Services_Weather be documented?
>
> In horde/docs/INSTALL if it is part of the portal, in jonah/docs/INSTALL
> if it is part of Jonah.  IIRC, it is being removed from Jonah and put in
> the portal?  If so, then in horde/docs/INSTALL.

I'll add it to horde/docs/INSTALL (after I figure out if it's required or
optional; refer to the paragraph above)

> > I could add a check
> > to test.php, but it isn't really required for horde to function. If the
>
> Doesn't matter.  We put things in there that are not needed.  Just make sure
> any error message says "it is only needed if you use the metar block" or
> something like that.  There are other such things already in test.php.

OK, I'll add a check to test.php

> > system
> > isn't going to use the metar block, Services_Weather isn't needed.
>
> Yes, just state that in any messages.

OK.

> > I guess I could return an error if the buildMetarDB script hasn't been run
> > (and
> > hence, the location tables don't exist), or would it be better to display
> a
> > meaningful message (something like "the buildMetarDB script must be run to
> > place the location tables in the horde database").
>
> Anything that alerts the admin (not the user) to the problem is good.

OK. Maybe something logged to horde.log? I've never done that before, but I'll
look into it.

Thanks!

> --
> Eric Rostetter
> The Department of Physics
> The University of Texas at Austin
>
> Why get even? Get odd!

--
Rick Emery

"When once you have tasted flight, you will forever walk the Earth
 with your eyes turned skyward, for there you have been, and there
 you will always long to return"
                                              -- Leonardo Da Vinci