On Wed, Oct 19, 2011 at 4:42 PM, Jukka Zitting <jukka.zitt...@gmail.com> wrote:
>> Or... are you saying CHANGES should not include "minor" issues? Only >> "big" ones? And users need to go to Jira to get a complete list? > > Yes, basically. If you're doing something that you think the average > user of Tika should be aware of when upgrading, then that information > should be mentioned in CHANGES.txt. If it's a minor thing that only > affects a rare corner case, then it's IMHO better left in Jira. > > That's just me though. I'm fine also with other approaches to CHANGES.txt. I agree with that in principle... I guess I just draw the line "lower". EG, I don't think we should include a CHANGE entry for internal code refactoring (that has no immediate end user impact), small bug fixes that we found in our own testing and no user had encountered (that we know of), improvements to tests, etc. But I think API changes, issues a user has hit, new features, changes in behavior, we really should include. Generally, when I'm unsure, I try to err on the side of "being verbose". I expect very few users will go dig in Jira to find all the fixed issues for a given release, but many users will glance at the CHANGES file. (Separately I'd like to get changes-to-html from Lucene somehow pulled over, so you can quickly click on each issue to see all details behind it). In addition to conveying what's new about the release, this also gives potential upgraders a simple measure of how active/healthy Tika dev is, and so another good reason to include a change is to convey that we are in fact healthy. We shouldn't undersell ourselves, and, the perceived health of the dev community by our users is important, I think. Furthermore, it can push users to upgrade, eg maybe they look and see RTF parser is now more robust when input is malformed, and they remember hitting RTF problems themselves, and so they try to upgrade. The more users we have actively upgrading the better for Tika. >> Ie this has changed from a discussion on "when should we add the >> entries to CHANGES" (on committing the change vs at release time) to a >> question of "what should CHANGES contain". > > In a way yes, but those questions are linked: True. > If we choose to record information about all (or most) changes in > CHANGES.txt, then we should IMHO rather add a separate field to Jira > for such notes and have the CHANGES.txt generated automatically from > those records. Otherwise we essentially just maintain two different > issue trackers. I agree it's bad to have essentially 2 issue trackers. Your idea would be AWESOME! Has anyone added a custom field to Jira...? How hard is it...? In theory it doesn't look too bad: http://confluence.atlassian.com/display/JIRA/Adding+a+Custom+Field We could also just use the existing comments field (so we don't need to customize Jira), eg any comment prefixed with "CHANGES:" is added to CHANGES.txt on release. I'm happy to figure out how to make something like this work... I think custom field would be best. But, I don't have enough Jira karma now to edit Tika's Jira project... > If on the other hand, as I suggest, the CHANGES.txt is more of an > edited summary of the most notable developments since the previous > release, it's best maintained manually. And while updating the file > right after making a change is a good idea for some things, for others > it may actually be better to hold back for a while to get a better big > picture of all the related changes. > > For example, for 0.10 I added the following single entry shortly > before the release: > > * Handling of temporary files within Tika was much improved > (TIKA-701, TIKA-654, TIKA-645, TIKA-153) > > This IMHO gives an average user a much better overall idea of what > happened than a detailed listing of each individual change would have > done. I completely agree there should be a single entry for the temp file improvements. We can also do this with add-CHANGE-as-you-go, ie you just refactor the CHANGES as needed, or don't put a CHANGE entry in until you're done with all the related issues, etc. We do this in Lucene today, though generally it's the exception not the rule. Really, as Chris described, I don't think we have an either/or situation here. Ie, even if we commit-CHANGES-as-we-go, or pull-CHANGES-from-Jira-custom-field, the RM can and should still apply "editorial oversight" to make sure the final CHANGES is reasonably clean. I think CHANGES.txt is an important service we do for our users (and, indirectly, for us/our community). Yes, it's sort of hassle (two issue trackers) but I think it's worth investing in, so that our CHANGES is fairly complete summary of what non-trivial issues were included. Mike McCandless http://blog.mikemccandless.com
