You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by Daniel John Debrunner <dj...@debrunners.com> on 2005/05/12 04:50:31 UTC
Please add descriptive Jira comments when fixing bugs
Jean, thanks for marking all the doc bugs as fixed but I would strongly
encourage you and anyone else to provide a descriptive comment when
marking a bug as fixed. I believe a well maintained bug tracking system
with complete data is essential for a quality project.
For several of the bugs that you closed today I can't tell from the Jira
entry if the issue was fixed by changing the functionality or just the
documentation to match the existing functionality.
A comment such as 'Patch committed revision 169667.' (Derby-164) doesn't
tell me immediately what was done. I try to include the svn commit
comment in any bug I mark as fixed.
I know I could find the details of revision 169667 (but I can never
remember how) but it takes time, spending the time up front in providing
the descriptive comment in Jira saves time for everyone else later.
Thanks,
Dan.
Re: Please add descriptive Jira comments when fixing bugs
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Andrew McIntyre wrote:
> For reference, you can look up a revision that has been applied to your
> svn view with: svn log -r 169667. Or, if it was not in your view, with
> propget like so: svn pg --revprop -r 169667 svn:log
>
> But if you run that last command, you get:
>
> Applied Jeff's patches for DERBY-87, DERBY-116 and DERBY-164
>
> More detailed explanations than this are essential, if not in both
> places (Jira and svn), then please at least in one! When determining
> what changes have been made, it is one thing to have to go from one
> place to the other, but if they each point at each other and neither
> have much (or any) information, it makes something like updating the
> CHANGES file very difficult. While what happened to fix 116 is clear, 87
> is less so, and 164 even less.
also, one patch per commit would be best, right? I realized that after
committing three patches in one lump.
Given the fixed issue, ie. DERBY-199, one can easily pull up the Jira
issue for details. And given DERBY-199 in particular, you can even see
that Mamta reviewed the doc fix. --That's ideal.
But we have some cart-before-the-horse where review is concerned.
If just the dita file is posted, the patch needs to be applied, then the
nightly build run to spit out the new doc for review.
If the corresponding html file is also posted, along with the dita file,
the change can be reviewed before the patch gets applied.
Now's a good time for establishing preferences for handling doc issues
and we can easily update the web site with more amplified steps to follow.
-jean
Re: Please add descriptive Jira comments when fixing bugs
Posted by Andrew McIntyre <mc...@gmail.com>.
On May 11, 2005, at 7:50 PM, Daniel John Debrunner wrote:
> I know I could find the details of revision 169667 (but I can never
> remember how) but it takes time, spending the time up front in
> providing
> the descriptive comment in Jira saves time for everyone else later.
For reference, you can look up a revision that has been applied to your
svn view with: svn log -r 169667. Or, if it was not in your view, with
propget like so: svn pg --revprop -r 169667 svn:log
But if you run that last command, you get:
Applied Jeff's patches for DERBY-87, DERBY-116 and DERBY-164
More detailed explanations than this are essential, if not in both
places (Jira and svn), then please at least in one! When determining
what changes have been made, it is one thing to have to go from one
place to the other, but if they each point at each other and neither
have much (or any) information, it makes something like updating the
CHANGES file very difficult. While what happened to fix 116 is clear,
87 is less so, and 164 even less.
andrew
Re: Please add descriptive Jira comments when fixing bugs
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jean T. Anderson wrote:
> Actually, I think my "resolving" these doc issues when all I have done
> is apply the posted patch is completely incorrect.
>
> Probably the correct action is to add a comment that the patch was
> applied. Then whomever reported the problem needs to verify that the
> patch fixed the issue, then resolve the issue as 'fixed'.
then, of course, if it is verified as fixed, it can actually be closed
..... so it isn't clear that a "resolved" step is useful.
-jean
Re: Please add descriptive Jira comments when fixing bugs
Posted by Jeremy Boynes <jb...@apache.org>.
Myrna van Lunteren wrote:
> I could be missing something here...
>
> Explicit details about a fix should go into the bug tracking system.
> Users should be able to search for a problem & find out what was done
> without having to download svn & the source tree.
>
Agreed.
Use Jira for recording information about the issue raised - for example,
a single entry may result in several commits over time, may result in
clearer doco, or other changes that are not reflected in the code tree
(e.g. wiki updates).
Use SVN for recording information about the specific change being made
so that developers reviewing the change can see what was intended or
someone looking back at the code (including you 3 years from now) can
understand what happened.
Jira and SVN are two of the most critical communication tools for the
community - if in doubt, over-communicate.
--
Jeremy
Re: Please add descriptive Jira comments when fixing bugs
Posted by Myrna van Lunteren <m....@gmail.com>.
I could be missing something here...
Explicit details about a fix should go into the bug tracking system.
Users should be able to search for a problem & find out what was done
without having to download svn & the source tree.
Myrna
On 5/12/05, Andrew McIntyre <mc...@gmail.com> wrote:
>
> On May 11, 2005, at 9:08 PM, Jean T. Anderson wrote:
>
> > I added svn comments for 169667, 169669, 169671, 169674, and 169675,
> > mostly cutting and pasting Jeff's Jira descriptions. Please critique
> > and provide suggestions for how they can be improved to be more
> > useful.
>
> These look great. My only comment is that the description for 169671
> reads like it could have been a code change. But, it's obvious from the
> Jira entry and the svn log that it was merely a doc change.
>
> Elsewhere, on May 11, 2005, at 10:02 PM, Jeff Levitt wrote:
>
> > I actually have wanted to attach html output to each
> > of my patch attachments. But how can that be done?
> > Maybe I'm missing something here. It seems to me that
> > you have the option in JIRA to attach one file at a
> > time. So does that mean I should attach the patch,
> > then each html file separately? Wouldn't that
> > generate quite a bit of unnecessary traffic to all of
> > us? Or should we attach the patch and then send the
> > output to the derby dev list separetly? Or something
> > I'm completely missing altogether?
>
> You could either 1) post the patch and sample output together as a zip
> or jar file to jira, or 2) post the patch and sample output together to
> derby-dev instead of Jira. Or, 3) post both as separate attachments to
> jira as you describe. I don't think anyone will mind one extra mail, as
> long as its the changes are easy to review. But, if you post the patch
> and sample output together in a single mail to derby-dev, then there's
> only one mail to review. :-)
>
> andrew
>
>
Re: Please add descriptive Jira comments when fixing bugs
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Jean T. Anderson wrote:
> Andrew McIntyre wrote:
>
>> You could either 1) post the patch and sample output together as a zip
>> or jar file to jira, or 2) post the patch and sample output together
>> to derby-dev instead of Jira. Or, 3) post both as separate attachments
>> to jira as you describe. I don't think anyone will mind one extra
>> mail, as long as its the changes are easy to review. But, if you post
>> the patch and sample output together in a single mail to derby-dev,
>> then there's only one mail to review. :-)
>>
>
> I prefer 1 or 3 for the following reasons:
>
> - It keeps the patch tightly coupled to the Jira issue
> - If the patch isn't quite right, a new one can be uploaded and the old
> one removed. One problem with posting patches to derby-dev is it can be
> difficult to know if you've seen all the patches for a thread and have
> the "right" one.
One more reason for 1 or 3:
- Uploads the file(s) to just one place and avoids emailing the patch to
everyone on the derby-dev list, which is currently at 220 subscribers
according to http://people.apache.org/~coar/mlists.html . Anyone
interested in the patch can readily download it from Jira.
I don't mind an additional Jira notification for option 3. Email filters
can easily organize list traffic.
Keeping it in Jira provides a single review spot. And if the reviewer
also posts the verdict to Jira, then it really does keep it to one spot.
-jean
Re: Please add descriptive Jira comments when fixing bugs
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Andrew McIntyre wrote:
> You could either 1) post the patch and sample output together as a zip
> or jar file to jira, or 2) post the patch and sample output together to
> derby-dev instead of Jira. Or, 3) post both as separate attachments to
> jira as you describe. I don't think anyone will mind one extra mail, as
> long as its the changes are easy to review. But, if you post the patch
> and sample output together in a single mail to derby-dev, then there's
> only one mail to review. :-)
>
I prefer 1 or 3 for the following reasons:
- It keeps the patch tightly coupled to the Jira issue
- If the patch isn't quite right, a new one can be uploaded and the old
one removed. One problem with posting patches to derby-dev is it can be
difficult to know if you've seen all the patches for a thread and have
the "right" one.
-jean
Re: Please add descriptive Jira comments when fixing bugs
Posted by Andrew McIntyre <mc...@gmail.com>.
On May 11, 2005, at 9:08 PM, Jean T. Anderson wrote:
> I added svn comments for 169667, 169669, 169671, 169674, and 169675,
> mostly cutting and pasting Jeff's Jira descriptions. Please critique
> and provide suggestions for how they can be improved to be more
> useful.
These look great. My only comment is that the description for 169671
reads like it could have been a code change. But, it's obvious from the
Jira entry and the svn log that it was merely a doc change.
Elsewhere, on May 11, 2005, at 10:02 PM, Jeff Levitt wrote:
> I actually have wanted to attach html output to each
> of my patch attachments. But how can that be done?
> Maybe I'm missing something here. It seems to me that
> you have the option in JIRA to attach one file at a
> time. So does that mean I should attach the patch,
> then each html file separately? Wouldn't that
> generate quite a bit of unnecessary traffic to all of
> us? Or should we attach the patch and then send the
> output to the derby dev list separetly? Or something
> I'm completely missing altogether?
You could either 1) post the patch and sample output together as a zip
or jar file to jira, or 2) post the patch and sample output together to
derby-dev instead of Jira. Or, 3) post both as separate attachments to
jira as you describe. I don't think anyone will mind one extra mail, as
long as its the changes are easy to review. But, if you post the patch
and sample output together in a single mail to derby-dev, then there's
only one mail to review. :-)
andrew
Re: Please add descriptive Jira comments when fixing bugs
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Andrew McIntyre wrote:
> ... it would be nice to have descriptive comments in svn as
> well, provided by whomever made the fix. I usually copy/paste a summary
> from the mail with the patch. If you don't get the comments for patches
> that were attached to jira entries until after the patch has been
> submitted, then adding those comments to svn requires an extra step,
> editing the svn log entry. For reference, that can be done with:
>
> svn propedit --revprop -r 169667 svn:log
I added svn comments for 169667, 169669, 169671, 169674, and 169675,
mostly cutting and pasting Jeff's Jira descriptions. Please critique and
provide suggestions for how they can be improved to be more useful.
thanks,
-jean
Re: Please add descriptive Jira comments when fixing bugs
Posted by Andrew McIntyre <mc...@gmail.com>.
On May 11, 2005, at 8:15 PM, Jean T. Anderson wrote:
> Actually, I think my "resolving" these doc issues when all I have done
> is apply the posted patch is completely incorrect.
>
> Probably the correct action is to add a comment that the patch was
> applied. Then whomever reported the problem needs to verify that the
> patch fixed the issue, then resolve the issue as 'fixed'.
>
> right?
I'm not sure what exactly the best way to go would be. That doesn't
sound bad, but it would be nice to have descriptive comments in svn as
well, provided by whomever made the fix. I usually copy/paste a summary
from the mail with the patch. If you don't get the comments for patches
that were attached to jira entries until after the patch has been
submitted, then adding those comments to svn requires an extra step,
editing the svn log entry. For reference, that can be done with:
svn propedit --revprop -r 169667 svn:log
> also, one patch per commit would be best, right? I realized that after
> committing three patches in one lump.
Yes, the most important reason being that it can be impossible to
determine what changes correspond to which issues if the files are all
lumped together in one commit.
> If the corresponding html file is also posted, along with the dita
> file, the
> change can be reviewed before the patch gets applied. Now's a good time
> for establishing preferences for handling doc issues and we can easily
> update
> the web site with more amplified steps to follow.
+1. It's not terribly difficult to generate the docs from the DITA
source, so providing sample output with doc changes would be nice.
andrew
Re: Please add descriptive Jira comments when fixing bugs
Posted by "Jean T. Anderson" <jt...@bristowhill.com>.
Actually, I think my "resolving" these doc issues when all I have done
is apply the posted patch is completely incorrect.
Probably the correct action is to add a comment that the patch was
applied. Then whomever reported the problem needs to verify that the
patch fixed the issue, then resolve the issue as 'fixed'.
right?
-jean
Daniel John Debrunner wrote:
> Jean, thanks for marking all the doc bugs as fixed but I would strongly
> encourage you and anyone else to provide a descriptive comment when
> marking a bug as fixed. I believe a well maintained bug tracking system
> with complete data is essential for a quality project.
>
> For several of the bugs that you closed today I can't tell from the Jira
> entry if the issue was fixed by changing the functionality or just the
> documentation to match the existing functionality.
>
> A comment such as 'Patch committed revision 169667.' (Derby-164) doesn't
> tell me immediately what was done. I try to include the svn commit
> comment in any bug I mark as fixed.
>
> I know I could find the details of revision 169667 (but I can never
> remember how) but it takes time, spending the time up front in providing
> the descriptive comment in Jira saves time for everyone else later.
>
> Thanks,
> Dan.
>