A few notes on CLs

[ron minnich]

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