On Wed, Mar 4, 2026 at 10:45 AM David G. Johnston <[email protected]> wrote: > I do need to work in a way to better annotate/comment on the why of these. > Any suggestions for a better flow or feedback format? Inline comments > wrapped in sgml comments? Or just copy the diff into the email body and > inline comment there - leaving the original diff attachment as-is?
My suggestion is to break these fixes up into three categories: clear errors, stylistic suggestions, substantive concerns. Clear errors can be handled by just sending a patch that fixes all the clear errors without changing anything else. If I intended to write "applied" and I actually typed "aplied," it's fine to bundle that with 10 other mistakes and submit them without commentary. For substantive concerns, I think it's most helpful to just quote the patch hunk in the body of your email and say what your concern is. If you have suggested wording feel free to suggest that as well, but I'd focus more on saying what the problem is rather than jumping to the solution. At least some of these are cases where what I wrote wasn't sufficient for you to understand the patch, which a very fair issue to raise, but if you try to write your own wording, the fact that you don't understand the patch makes it hard for you to write quality documentation for it. If you say "I read where you said X and I tried Y and it seemed like the wrong thing happened, so either the documentation sucks or the code is buggy," now we're having a worthwhile conversation. If you just change the documentation based on your understanding of the results of an undisclosed experiment, I feel like the chances of the result being an improvement are not great. Stylistic concerns are the most complicated. If your concern is something like "this sentence is hard to understand," I'd class that as a substantive concern and treat it the same way. Beyond that, I'm not really sure. Honestly, I think we may just have different stylistic preferences, because my experience so far reading your proposed documentation patches is that I tend to agree with relatively little of what you want to do. I believe, though, that other committers feel differently about it and find your proposed changes quite helpful. So I'm not sure exactly what to recommend here, but perhaps take a lighter touch when it's my patch? I'm OK with some friendly suggestions that I can accept or reject, but going through a huge list of minor wording tweaks is as much work as going through a substantial review of the code itself, but for a lot less benefit, especially if they all look like random changes that I don't understand why you're proposing. Hope that makes sense and isn't too harsh. Thanks, -- Robert Haas EDB: http://www.enterprisedb.com
