Hi, Amit Kulkarni wrote on Wed, Nov 02, 2011 at 09:18:55AM -0500:
> Yeah, its a lot of work... found out the hard way. It was a huge time > sucker. Wow, that's something. The hard part about it is actually *understanding* what the commits do, to get the one-line summary right. A good commit message and a good plus.html entry have different goals. The commit message technically explains the reason for the change, and how the code works before and after the change, and the primary audience are programmers well acquainted with the internals of the program in question. It may also briefly mention consequences for users, but that is rarely the focus. A good plus.html entry briefly summarizes the relevance for the user. It may also mention technicalities when the change is very technical in nature - like, changing NULL to (void *) - but's that's more the exception than the rule. Not every commit warrants a plus.html entry, and most are shorter than the corresponding commit messages, but some need expansion on the relevance for the user. Shortening very technical, usually already rather terse texts is hard; understanding the consequences, and expanding on the relevance, where that is lacking from the commit message, is even harder. When Nicolas did it and i saw what he said regarding mandoc(1), i sometimes went "Huh? Which change is that referring to?" or a few times even "What? I never did that..." - even though Nicolas certainly used care and spent considerable effort, even though mandoc is certainly a relatively easy part of the system, and even though my commit messages tend to be more verbose than those of some other developers. That said, i don't think having individual developers provide plus.html entries in addition to commit messages would work - additional workload, lack of uniform style, and lack of a "big picture" pespective. So it has to be done by one person, or by a small team. The ideal person to do it would know all the technical internals of all parts of the system, have huge experience in using the system, but be completely unwilling or unable to write any code in there first place, to not be distracted from writing and committing code improvements. Oh well, what a contradictory job ad... :) Even if what you are doing is not perfect, having a least something, in a consistent style and with regular updates, is certainly a huge improvement, compared to letting plus.html die. Thanks, Ingo
