On Thu, Jan 09, 2025 at 02:57:50AM -0500, Jeff King wrote: > On Tue, Jan 07, 2025 at 08:37:33AM +0100, Patrick Steinhardt wrote: > > > On Tue, Jan 07, 2025 at 02:07:52AM -0500, Jeff King wrote: > > > We want to know if there are any leaks logged by LSan in the results > > > directory, so we run "find" on the containing directory and pipe it to > > > xargs. We can accomplish the same thing by just globbing in the shell > > > and passing the result to grep, which has a few advantages: > > > > > > - it's one fewer process to run > > > > > > - we can glob on the TEST_RESULTS_SAN_FILE pattern, which is what we > > > checked at the beginning of the function, and is the same glob use > > > > s/use/used > > > > I'm always a bit thrown off by your style of bulleted lists, where they > > feel like sentences but start with a lower-case letter, and sometimes > > they do and sometimes they don't end with punctuation. Maybe it's just > > me not being a native speaker and it's a natural thing to do in English. > > In any case, it's nothing that really matters in the end, but would be > > happy to learn if this is indeed something you tend to do in English. > > Heh. Yeah, I've seen you mention them before and I've been tempted to > start a big discussion. But I never felt like it was worth it. But > tonight's your lucky night. ;) > > In short: I think it's a style question. I perceive them as > continuations of the sentence that has the ":". Though admittedly I do > not always grammatically continue that sentence. So for example I could: > > - have one bullet item that completes the sentence. > > - and then another that likewise completes it. > > ;) I think many style guides would frown on that. Especially with the > periods at the end (you might argue that they should be semicolons). > > In the example you quoted above they don't grammatically continue the > sentence, so arguably what I'm saying doesn't even apply. But I also > kind of think of the list items as sentence fragments. That sometimes > happen to make a full sentence. Or need punctuation because that > fragments gets so long it contains multiple sentences. > > I dunno. You asked if it is something you tend to do in English. It is > something _I_ tend to do in English, but I think most style guides would > suggest against it (but then, most also suggest against bulleted lists > in the first place). (They probably also suggest against lots of > parentheses). So I wouldn't necessarily copy me. > > My general feeling is that unless a commit message is inaccurate or hard > to understand, we should mostly let it pass (even typos). Yes, they are > an artifact that is enshrined in the history. But at some point they are > also just a written communication between developers, and we all have > our own voices and styles. And make mistakes. Polishing them is > something we _can_ do collaboratively, but there are diminishing > returns. Yup, agreed. It's a minor detail and I'm happy to gloss over it in the future. > In case it is not clear, I would not say the same for documentation, > error messages, etc. Those are artifacts that hits a wider audience, and > we have a tool for polishing them together: git. > > And people should still proofread and correct their own messages before > sending. Believe it or not, I do always take a final pass when sending > out my commits and still manage to have errors. ;) A lot of times I end > up improving clarity and wording on the final pass, but end up > introducing a typo (I'm pretty sure that the use/used above was me > switching last-minute between "the same glob we use" and "the same glob > used"). > > Bringing it back to the example at hand, my assumption is that the > bullet list capitalization and punctuation is mostly a question of > style, and isn't making the result hard to understand. But if it is, I > can try to adjust. I actually wrote a bulleted list in a commit message > earlier today and capitalized it just for you. :) Thanks for explaining! Patrick
