On Sat, May 3, 2025 at 9:01 AM Ihor Radchenko <yanta...@posteo.net> wrote:
> Gnarled Grip <gnarledg...@gmail.com> writes: > > > Thank you Ihor. As I understand you, you are requesting the following > > approach: > > > > - That one not change existing STARTUP options in org files as a rule, > and > > discuss any first > > Yup. It should be separate because it is very different from grammar > fixes. And it should be discussed because it may affect more than a > single file. > > > - Avoid the passive form, that is, use "change" instead of "changed" > > Yup. This is a common commit message practice. > > > - Each commit should focus on one type of change only > > Yes, although similar changes may be grouped. For example, it is ok to > group all grammar fixes into one patch. Detailing each _kind_ of grammar > fix is usually too granular. > > The general logic behind creating commits is the following: > > 1. When you look at the git log, you will see only the first line of the > commit message. So, git log should be written in such a way that a > person just skimming through the first lines could get an idea about > what kind of changes have been done. For example, take a look at > https://git.savannah.gnu.org/cgit/emacs/org-mode.git/log/ > You should be able to tell, without looking into actual changes, what > happened to Org mode repository recently. > > If you split very similar changes into multiple commits, they will > not provide useful information - you will just introduce consequent > (alost) identical lines into the log. > > For the same reason, putting very different changes into a single > commit message is not very useful. There is only that much you can > fit into the first line. If you do not describe all the changes in > the first line, they may be missed while reading the log. > > An analogy of the first line of a commit message is Title of a > video/article/blog post. It is the first thing the reader encounters, > and it should indicate whether more detailed reading is needed. > > 2. At the second level we have the rest of the commit message. > This is a kind of abstract summarizing changes. One should be able to > understand what kind of changes were done and why they were done, in > plain English. That's why (and for historical reasons) it follows > changelog format were each changed function/section should be > annotated. > > Hope I made things more clear. > > > - All changes should be rigorously documented in commit messages, which > > includes detailed ChangeLog entries for every change > > How detailed is a judgment call, actually. The commit message should > give enough idea to understand *why* the changes were done and, > sometimes, why they were done in some specific way. It may be achieved > with a few words sometimes. > > P.S. Please avoid top-posting. See > https://orgmode.org/worg/org-mailing-list.html#org4778c4c Thank you for the detailed explanation. Understood. With small changes it seems impractical to provide headings/sections in the changelog. Am I correct?
