I've noticed some trends in CLs from our newer guys that I want to warn against. People are putting in text that, viewed from a short time frame and a perspective of being unfamiliar with the code base and hardware, make sense. But from the longer time frame, they're not such a good idea.
A little background: the coreboot codebase started on sf.net, in 1999. SInce that time, we have - used 4 SCM systems (CVS, ARCH, subversion, GIT) - run on at least two different servers (sf.net, coreboot.org) - supported around 10 kernels (Linux, Plan 9, *BSD, windows variants, QNX, ...) - - and over 100 different linux versions - worked with at least 10 vendors who no longer exist
Writing CLs that stand the test of time in this context is a bit of challenge. But there are some things you can avoid:
1. Avoid URLs as much as possible. There are 600 URLs in the 21000 u-boot commit log. There are 224 in the 4000 or so coreboot commit log. Of those in coreboot, 40 or so are invalid. This problem only gets worse with time. Some of them are for dead companies, others because things have moved. 2. avoid kernel boot logs. Sure, it means something to you, right now. But it's useless after about a year, as kernels change. It can be quite misleading over time. And, besides, there are people out there who do not care about Linux and don't want to trawl through Linux boot logs to understand a CL. Avoid being linux-centric 3. avoid coreboot logs. Same reason. It's amazing how much coreboot logs change over time. 4. Avoid copy/paste of documents. Not the least because we don't want to deal with copyright issues 5. A CL is not a tutorial. It's not a chance to thank people for their work. It's an explanation of a change. Keep it short. In many cases, it should be possible to understand it from the summary. For most of them, I should not have to click through a URL to have some idea of what you've done! See gerrit.chromium.org for an example of a real, large project and what their CLs look like. 6. And, I hope for obvious reasons, never link to a patent, cite a patent, or mention patents as the basis of anything you do :-) 7. Avoid telling people to run this or that tool. Not everyone has your environment. 8. Finally, we almost never need to see gcc/iasl error messages. The words 'won't compile' are just fine in almost every case.
DO: 1. create a clean, concise summary 2. explain what you did 3. explain why you did it. (2 and 3 can be in the other order)
I hope Nico doesn't mind, but I've just been reviewing and his CLs are fresh in my mind. They're a great model of how CLs should be written. So check his CLs out. Hope you do not mind me mentioning you, Nico!
thanks
ron