To whom should error messages be written?

[markd at macports.org]

>There are a number of error messages that MacPorts might print during
>the normal course of events. Checksum errors, fetch failures, port
>misbehaviors. Who should be the audience for these error messages --
>the end user or the portfile developer? I would argue the former but
>we currently have some messages that target the latter.

I agree they should be written to the end user.  Perhaps if more technical
stuff in a message, if any, could be included after a "DEBUG Info:" label?
 Not sure if this is a good idea; I'm just thinking out loud.
>
>Take, for example, destroot violations. If a port violates the mtree
>and does not indicate that it wants to do this via
>"destroot.violate_mtree yes", MacPorts prints:
>
>        Warning: violation by <path>
>        Warning: <port> violates the layout of the ports-filesystems!
>        Warning: Please fix or indicate this misbehavior (if it is
>intended), it will be an error in future releases!
>
>This message is clearly written to the portfile developer.
>
>If the port does indicate that it will install files outside of the
>mtree, MacPorts says:
>
>        Warning: <port> requests to install files outside the common
>directory structure!
>
>This message is presumably written to the end user so that they know
>files have been installed in a nonstandard location, though MacPorts
>does not tell the user where. I recall at least one bug report from a
>user who did not realize that this message did not constitute a bug
>but correct normal behavior. I guess the word "Warning" and the
>exclamation point make it sound like a bug that needs to be reported.
>
>The patch in #15514 [1] adds a new message the end user could see:
>
>        Warning: reinplace <regexp> didn't change anything in <file>
>
>This information is meant for the portfile developer. The developer
>should either fix the regexp (so that it replaces what it was
>designed to replace), or remove it (because the file no longer needs
>that replacement), or indicate via a new flag to the reinplace
>command that it's ok that no replacement occurred (for example see
>the mysql5 port which does a reinplace across a glob of files, not
>all of which contain the string to be replaced). The end user doesn't
>need to know all this, of course; the end user just needs to be told
>to file a ticket.

That new reinplace error message only shows up in debug output, correct? 
I wouldn't think a bug report is necessarily required for this error.  I
think of it more as informational.
>

Also, I favor changing the "target" terminology in error messages for the
same reason; I think that is ambiguos and a type of "developer-speak".  I
dropped that in favor of "phase" or "installation phase" in the new guide.
 I haven't submitted a patch to change the error message(s) yet so the
user doesn't need to figure out what a target is, but I will.

http://lists.macosforge.org/pipermail/macports-dev/2007-September/002872.html

>
>I think we should write error messages to the end user, not the
>portfile developer. I think we should also have a new page in the
>wiki called ErrorMessages, where we can list the error messages that
>MacPorts might print along with explanations of what the portfile
>author should do about them. We would describe mtree violations and
>ineffectual reinplaces and checksum failures (the checksum failure
>discussion would move to this new page from the FAQ).
>
>Or we could put all these in the FAQ page, maybe in a new section for
>error messages.

I think this might not be sustainable and might lead to always out-of-date
docs.  I wouldn't be in favor of this unless the error messages were
sourced out of the code itself, rather than written independently.

Mark