To whom should error messages be written?

[Ryan Schmidt]

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.

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.



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.


[1] http://trac.macports.org/ticket/15514