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 -- Ihor Radchenko // yantar92, Org mode maintainer, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>
