To whom should error messages be written?

[Ryan Schmidt]

On Jul 20, 2008, at 09:47, markd at macports.org wrote:

>> 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.

Currently, debug output is prefixed with the DEBUG: label but only in  
debug mode. I think it would be confusing to now introduce new  
information which comes with a DEBUG: prefix which is not controlled  
by debug mode.


>> 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?

No, it occurs in normal output, just like the mtree warning.

The portfile developer can add a flag to the reinplace invocation to  
suppress the message, if indeed it is intentional that the reinplace  
not modify anything. This should be very rare.

I added a note to the ticket about possibly printing the warning in  
debug mode only in the case that the developer requested reinplace to  
be silent, just so there's some record of the situation.

> I wouldn't think a bug report is necessarily required for this  
> error.  I
> think of it more as informational.

It is my intention that any occurrence of this message in normal (non- 
debug) output is an error that needs to be fixed in the port in some  
way or another. Either the reinplace needs to be fixed so the file  
gets changed, or the reinplace needs to be removed if it is no longer  
needed, or a flag needs to be added to the reinplace invocation to  
indicate that it is ok that nothing got replaced.


> 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 agree "phase" is clearer than "target". Especially since portfile  
syntax also includes the notion of a "target" (in the likes of  
build.target) which is an unrelated concept.


>> 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.

Can you suggest an alternative?

There is a vast amount of information, for example, that we want to  
impart to people who encounter a checksum error. The port command  
does not provide any of it. Instead the user must read the FAQ to  
figure out which of several reasons for the checksum error exist and  
how to resolve it. And we have some information which is for MacPorts  
users and other information which is for port maintainers.

Not all errors need that much explanation, but I'm sure at least a  
paragraph could be written about each. Would you rather the port  
command print all of that out? And what if the instructions are  
inaccurate or unclear? Then we need to do a whole new MacPorts  
release just to fix it. And we know how infrequent MacPorts releases  
have been lately.

I would much prefer that MacPorts itself print very little  
information to the user: only a brief statement about what happened,  
and a link to the FAQ entry about that error. Since this link would  
point to a wiki page, inaccuracies could be very quickly corrected by  
anyone.


Just like we're talking about having a chunked guide now instead of  
the entire guide all on one page, maybe we should have one error  
message per page too instead of all on one. We could have a wiki  
template for error messages, like we have a wiki template for how-to's.