[prev in list] [next in list] [prev in thread] [next in thread] 

List:       mesos-dev
Subject:    Re: Add JIRA ticket# to `TODO`s in comments
From:       Benjamin Mahler <benjamin.mahler () gmail ! com>
Date:       2015-11-15 16:20:44
Message-ID: CAFp_NitEK99NOWH_MwX=UwWX6AtKW4jXHGFWZa7byJN2Krrf2g () mail ! gmail ! com
[Download RAW message or body]


I'm a -1 on the syntax: I'm not sure why the syntax is being proposed when
folks are free to add one or more tickets in the content of the TODO, much
in the same way as comments are written in general. When optional, there is
also the inconsistency of TODO syntax across the code base which seems
unfortunate.

It does seem like a good idea to include some guidelines and examples
around when to use TODOs vs. tickets. Sometimes TODOs are written as food
for thought, or to suggest things to the next person that approaches the
code, as Alex Rukletsov described.

On Wed, Nov 11, 2015 at 10:02 AM, Kapil Arya <kapil@mesosphere.io> wrote:

> I like the idea of making it a soft requirement. That way for chain
> reviews, one can still have some TODOs which are going to be resolved by a
> later patch.
>
> On Wednesday, November 11, 2015, Jojy Varghese <jojy@mesosphere.io> wrote:
>
> > If we are going to track these TODOs on JIRA, I hope we add these as
> > sub-tasks to the stories/epics and are not floating free. Which brings
> the
> > question - how are epic completion timelines effected by these.
> >
> > -Jojy
> >
> >
> > > On Nov 11, 2015, at 9:39 AM, Greg Mann <greg@mesosphere.io
> > <javascript:;>> wrote:
> > >
> > > +1
> > > for adding TODO(MESOS-xxxx) to the style guide as a soft requirement. I
> > > don't think it should be strictly required, since sometimes creating a
> > JIRA
> > > ticket just doesn't make sense, but I do have the feeling that in
> *most*
> > > cases, our process would benefit from creating a JIRA at the moment a
> > TODO
> > > is created to help ensure that the work doesn't fall through the
> cracks.
> > >
> > > Cheers,
> > > Greg
> > >
> > > On Wed, Nov 11, 2015 at 9:32 AM, Marco Massenzio <marco@mesosphere.io
> > <javascript:;>>
> > > wrote:
> > >
> > >> -1
> > >> for mandatory adding MESOS-xxxx to TODO.
> > >>
> > >> it makes it more cumbersome to add TODOs and, I fear, would discourage
> > >> people from adding those.
> > >> For example in a "chain", TODOs may be short-lived enough that adding
> a
> > >> Jira would only add noise.
> > >>
> > >> I'm not even sure that (optionally) adding the Jira to the TODO will
> add
> > >> much value (in fact, it may make our backlog even more "noisy" than it
> > >> currently is) but I am willing to experiment with this and see how it
> > goes.
> > >>
> > >> --
> > >> *Marco Massenzio*
> > >> Distributed Systems Engineer
> > >> http://codetrips.com
> > >>
> > >> On Wed, Nov 11, 2015 at 8:40 AM, Alex Rukletsov <alex@mesosphere.com
> > <javascript:;>>
> > >> wrote:
> > >>
> > >>> I think we should encourage people to follow this pattern, but not
> > making
> > >>> this obligatory.
> > >>>
> > >>> I may be wrong, but I feel that sometimes we use `TODO`s as food for
> > >>> thought, not for something that should or will necessarily be
> > implemented
> > >>> soon. A `TODO` may provide additional context to the implementation
> > from
> > >>> the perspective, how the code or related feature may evolve in the
> > >> future.
> > >>> However, that original vision may change over time, so it's not
> always
> > >>> reasonable to create a ticket.
> > >>>
> > >>> On Wed, Nov 11, 2015 at 4:57 PM, Kapil Arya <kapil@mesosphere.io
> > <javascript:;>> wrote:
> > >>>
> > >>>> Hi Ben,
> > >>>>
> > >>>> On Wed, Nov 11, 2015 at 8:33 AM, Benjamin Mahler <
> > >>>> benjamin.mahler@gmail.com <javascript:;>>
> > >>>> wrote:
> > >>>>
> > >>>>> Kapil would you mind clarifying what is being proposed here? Folks
> > >> are
> > >>>>> already free to include a reference to a ticket when writing a
> > >> comment
> > >>>> or a
> > >>>>> TODO, so is the suggestion here to require it for TODOs? Or to add
> a
> > >>>> syntax
> > >>>>> for this? If it's the latter, what does the syntax achieve?
> > >>>>>
> > >>>>
> > >>>> The proposal is two fold:
> > >>>>
> > >>>> A. Make it mandatory to include a JIRA ticket number with the TODO.
> > >>>>
> > >>>> B. Add a syntax for this and for that we need some consensus. I
> > >> proposed
> > >>>> two options in the initial email:
> > >>>>    1. TODO(<REPORTER>:MESOS-XXX)
> > >>>>    2. TODO(MESOS-XXX)
> > >>>>
> > >>>> I personally prefer the second option, since the `REPORTER' is
> already
> > >>>> covered as part of the Jira ticket.
> > >>>>
> > >>>> Kapil
> > >>>>
> > >>>>
> > >>>>> On Wed, Nov 11, 2015 at 4:29 AM, Klaus Ma <klaus1982.cn@gmail.com
> > <javascript:;>>
> > >>>> wrote:
> > >>>>>
> > >>>>>> +1, JIRA will include more discussion and we can close it when it
> > >> has
> > >>>>> been
> > >>>>>> improved.
> > >>>>>>
> > >>>>>> ----
> > >>>>>> Da (Klaus), Ma (马达) | PMP ® | Advisory Software Engineer
> > >>>>>> Platform Symphony/DCOS Development & Support, STG, IBM GCG
> > >>>>>> +86-10-8245 4084 | klaus1982.cn@gmail.com <javascript:;> |
> > http://k82.me
> > >>>>>>
> > >>>>>> On Wed, Nov 11, 2015 at 5:11 PM, Alexander Rojas <
> > >>>>> alexander@mesosphere.io <javascript:;>>
> > >>>>>> wrote:
> > >>>>>>
> > >>>>>>> +1
> > >>>>>>>
> > >>>>>>> This also provides a way of removing TODO's since they are
> > >>> traceable.
> > >>>>> If
> > >>>>>>> you look in the code, there are TODO's which are no relevant
> > >>> anymore
> > >>>> or
> > >>>>>>> probably cannot be understood from their actual context.
> > >>>>>>>
> > >>>>>>>> On 08 Nov 2015, at 05:50, Kapil Arya <kapil@mesosphere.io
> > <javascript:;>>
> > >>> wrote:
> > >>>>>>>>
> > >>>>>>>> Folks,
> > >>>>>>>>
> > >>>>>>>> I wanted to bring up a style issue related to the TODO tag in
> > >>>>>> comments. I
> > >>>>>>>> have filed a Jira ticket (
> > >>>>>>> https://issues.apache.org/jira/browse/MESOS-3850)
> > >>>>>>>> with the following description:
> > >>>>>>>>
> > >>>>>>>> Currently, we have a TODO(<username-of-original-author>) tags
> > >> to
> > >>>> note
> > >>>>>>> stuff
> > >>>>>>>> has "should be"/"has to be" done in future. While this provides
> > >>> us
> > >>>>> with
> > >>>>>>>> some notion of accounting, it's not enough.
> > >>>>>>>>
> > >>>>>>>> The author listed in the TODO comment should be considered the
> > >>>>>>> "Reporter",
> > >>>>>>>> but not necessarily the "Assignee". Further, since the stuff
> > >>>> "should
> > >>>>>>>> be"/"has to be" done, why not have a Jira issue tracking it?
> > >>>>>>>>
> > >>>>>>>> We can use TODO(MESOS-XXX) or TODO(<Reporter>:MESOS-XXX) or
> > >>>> something
> > >>>>>>>> similar. Finally, we might wan to consider adding this to the
> > >>> style
> > >>>>>> guide
> > >>>>>>>> to make it a soft/hard requirement.
> > >>>>>>>>
> > >>>>>>>>
> > >>>>>>>> Are there any opinions/suggestions on this one?
> > >>>>>>>>
> > >>>>>>>> Best,
> > >>>>>>>> Kapil
> > >>>>>>>
> > >>>>>>>
> > >>>>>>
> > >>>>>
> > >>>>
> > >>>
> > >>
> >
> >
>


[prev in list] [next in list] [prev in thread] [next in thread]