lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Hostetter <>
Subject Re: Changes Mess
Date Wed, 08 Dec 2010 18:42:14 GMT

I'm going to side step the "use jira to generate changes.txt debate, and 
focus on what i think is the broader problem with a simpler fix.

FWIW, i like CHANGES.txt myself, i think the jira generate pages 
compliment it, and give you a differnet view of the same info, but i 
prefer CHANGES.txt because it hsa a human element to it... if we do decide 
to go the jira automated route, the problems (and ultimate decision making 
needed) that i point out below still needs to be dealt with


: when merging changes done in 2.9.4/3.0.3 with current 3.x and trunk I found
: out that 3.x changes differ immense between the trunk changes.txt and the
: 3.x changes.txt. Some entries are missing in the 3.x branch, but are
: available in trunk's 3.x part or other entries using new trunk class names
: are between 3.x changes in trunk.

I tried to point this out a whle back when i discovered there even *was* a 
3x section in trunk's CHANGES.txt

The problem seems entirely of our own making by assuming that the 3x 
section of trunk/CHANGES.txt should be updated when things were commited 
to the 3x branch.

as i said before...

If we commit to the 3x branch, add to the 3x CHANGES.txt
If we commit to the trunk, add to the trunk CHANGES.txt

the 3x "section" of trunks CHANGES.txt should never have existed.

There are two very simple solutions to cleaning up the current mess, 
depending on wether we really want to have CHANGES.txt list the full 
history of all changes to the product in all versions, ad infinitum; or if 
(as has been suggested before but i don't think ever decided on) we want 
to start pruning CHANGES.txt to focus only on hte most recent relase (or 
current "branch" of development)

*** If we do want CHANGES.txt to be a historical record ***

the 3x "section" of trunks CHANGES.txt should just be riped out now and 
replaced with the final "3.0.3" section of the CHANGES.txt that was 
included in the 3.0.3.

the "2.9.4" section of the CHANGES.txt that was included in the 2.9.4 
release should also be included in trunk's CHANGES.txt

the process going forward on each release should be that after a release 
is done, cut/past the section of changes from that release to the "HEAD" 
of any branches that have higher release numbers.

Arguably we could dedup identical entries so that each entry appears only 
once (i suggested this before and now think i was wrong), but that loses 
information: people who see that LUCENE-9876 was fixed in 2.9.4 have no 
context of wether that fix was in 3.0.2 or 3.0.3 -- to have that full 
context it makes sense for each "fix" commited in a branch to actually be 
listed in the first release on that branch that the fix was in.

*** If we want CHANGES.txt to focus on the current version/branch ***

We do nothing special at all.  

We rip out the 3x section of trunk's CHANGES.txt and forget about it.

we rip out everything pre 4.x from trunk's CHANGES.txt and let people who 
are interested in the CHANGES.txt from those versions go look them up 
there.  (we could/should start publishing them on the website in a more 
conspicous place to make them more accessible)

we move forward only ever adding things to CHANGES.txt on a branch if that 
change is actually commited to the branch, and we do nothing special when 
releases happen.

	*** vote is to start having CHANGES.txt focus solely on the changes 
commited to the branches that lead to that release (so 4.1.1's CHANGES.txt 
will list 4.0, 4.1, 4.2, and 4.2.1 - but not 3.1, or 4.1.1) but i could 
also be pursuaded that it should only be that exact release (4.1.1 only 
contains commits specific to 4.1.1)

I think that general approach is the only sane thing to do (both from a 
developer sanity stand point, and from a clarity to users standpoint 
about what versions on what branches contain what bug fixes/features) now 
that we are knowingly and deliberately maintaining multiple branches under 
active development.

if we publish releases containing CHANGES.txt file that contains a 
sequential list of versions like "2.9.4, 3.0.2, 3.1, 3.2, 4.0, 4.1" then 
people are going to (understandable) assume that if the "3.2" section says 
it fixes a bug, that means the bug fix was included in 4.0 -- and that 
won't always be true, it might have been fixed in 3.2 and 4.1, but 4.0 
might still have it. (that scenerio has always been possible with our 
point releases, but with the multiple active branches the frequency of 
that scenerio is going to skyrocket)


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message