Emily Shaffer <emilyshaffer@xxxxxxxxxx> writes: >> + - Log messages to explain your changes are as important as the >> + changes themselves. Clearly written code and in-code comments >> + explain how the code works and what is assumed from the surrounding >> + context. The log messages explain what the changes wanted to >> + achieve and why the changes were necessary (more on this in the >> + accompanying SubmittingPatches document). >> + > > One thing not listed here, that I often hope to find from the commit > message (and don't), is "why we did it this way instead of <other way>". > I am not sure how to phrase it in this document, though. Maybe: > > The log messages explain what the changes wanted to achieve, any > decisions that were made between alternative approaches, and why the > changes were necessary (more on this in blah blah) > > Or maybe "...whether any alternative approaches were considered..." fits > the form of the surrounding sentence better. Quite valid observation. Documentation/SubmittingPatches::meaningful-message makes a note on these points, and the above may want to be more aligned to them. Patches welcome, as these have long been merged to 'master/main'. Thanks.
