Proposal: Start requiring "code release notes" on a bug-level basis

[Jouni Heikniemi]

Hey ya,

in the flurry of patches we've been receiving in the last few days, I've 
started to think about the problematic nature of heavy code 
reorganizations happening over a short span of time. Since the whole 
development team (not even the whole reviewer team) never takes part in 
developing a single patch, every now and then we check in a huge lump of 
code most people have never seen or even heard about. Yet, that code may 
change pretty familiar interfaces and ways to do everyday coding.

For most of the time, hanging on the IRC and/or reading the bug will 
provide sufficient information, but nobody has the time to do that for 
all the bugs. This is why I think we should have "release notes" for 
significant changes to the codebase. These notes would be posted to 
developers@ at the time of checkin, and they should describe the new 
feature and the implications in the code. Notes shouldn't be required 
for things that are particularly internal to a method, module or another 
independent unit. In the end, I think only about 10-20% of the patches 
really need this...

Here's a fictional example of what such a posting could look like 
(remember, this is just an example, the change described below hasn't 
occurred):

--
Bug 123456 was just checked in. The modern SQL Statement execution using 
->prepare and ->execute doesn't care about taints anymore, so you no 
longer have to trick_taint your variables prior to passing them to 
$sth->execute(). This is the correct way to do it: DB parameters are 
automatically quoted anyway.

To summarize, you can now run SQL queries using the following syntax:

my $dbh = Bugzilla->dbh;
my $sth = $dbh->prepare("SELECT x, y FROM foo WHERE z = ?");
$sth->execute($cgi->param("z")); # taintedness no longer an issue here

Remember that SendSQL et al. are deprecated. They will (naturally) still 
need the appropriate validation and detainting.
--


Processwise, I think approval should be withheld until there is an 
acceptable proposal for notes available in the bug. It's then finally up 
to the approver to decide whether information about a certain change 
should be posted to developers at . It should be the responsibility of the 
person doing the checkin to make sure the notes actually get posted.


Thoughts on this?


Jouni