I'm not convinced there is a code change that needs to happen. I do think the docs could be clearer on results. I think the current behavior is what is most often desired, but that the docs could make that behavior clearer.

Conversely "at most one row" suggests that getting no rows is somehow acceptable, but an error is returned in that case. I think it should say "exactly one row".

No, it should not. If the query returns no rows, you get a ErrNoRows on Scan. That's useful and constitutes valid usage of QueryRow,

Also, I think you're reading this the wrong way: the "expected to return at most one row" part places an obligation on the user of QueryRow and not on its implementation. You're not supposed to use it in the first place if your query can return more than one row.

As the existing implementation allowed it, changing it to return an error now has the potential to break code that relied on it returning the first result (whatever that is).

I can see why changing the behavior is undesirable. but at least the documentation should be clarified. It needs to say that it scans the first row (ignoring others), and that ErrNoRows is returned if there are no rows.

CL https://golang.org/cl/44890 mentions this issue.