Date: Mon, 20 Dec 1999 10:09:22 +1100 From: Peter Jeremy <peter.jeremy@alcatel.com.au> To: freebsd-hackers@FreeBSD.ORG Subject: CVS Log comments for large changes Message-ID: <99Dec20.100056est.40341@border.alcanet.com.au>
next in thread | raw e-mail | index | archive | help
[This might not belong on -hackers, but I'm not sure where this sort of discussion _does_ belong}. Occasionally, single CVS changes affect large numbers of files. The comments associated with those commits generally fall into 3 categories: 1) Import version x.y into vendor branch z 2) [Detailed discussion of change] 3) Implement xxx as discussed on freebsd-yyy I'm not concerned about the first change. Information regarding the specifics will normally be in a CHANGELOG or similar file associated with the change. The second commit style correctly documents what has been done, but leads to repository bloat by repeating the message in multiple locations. The third commit style solves the repo-bloat problem, but loses the reasoning behind the change. (It might be in one of the mailing list archives, but locating it in future may be difficult). I'd like to suggest that where a major change (one that needs more than a line or two of explanation) affects a significant number of files, the commit be performed in two pieces: Firstly a null commit to a convenient file associated with the change (eg a README or Makefile) including the full explanation behind the proposed commit in the log message. Secondly the actual change of all files, with the log message just referencing the file/version containing the detailled log message. In this way, the reasons for the change get stored within the repository, without bloating it. I believe the 'description first, then changes' order is better than the opposite order for two reasons: 1) This allows comments to be added to files that are going to be deleted. 2) The change commit can specify the already known version of the file containing the log message. Peter To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?99Dec20.100056est.40341>