To whom should error messages be written?
ryandesign at macports.org
Tue Jul 22 00:35:59 PDT 2008
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
> stuff in a message, if any, could be included after a "DEBUG Info:"
> 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  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,
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
> 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.
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-
> 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
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.
More information about the macports-dev