[Insight-developers] Commit message prefixes

Stephen Aylward stephen.aylward at kitware.com
Fri Oct 29 15:20:17 EDT 2010 

Unless someone wants to petition for a community vote to change the
original ITK policy, then perhaps we can continue to honor the old
ways and require the use of standard prefixes?

I'd be happy to organize a vote if someone wants one on this (or any
other) topic.   It really is one of the few clear roles/uses of the
ISC.

Stephen

On Fri, Oct 29, 2010 at 3:12 PM, Bill Lorensen <bill.lorensen at gmail.com> wrote:
> I just edited the vtk commit messages for the last week. Notice that
> the automated messages al have a common prefix. Actually, more than 5
> characters. The old required prefixes appear quite often, even though
> there is not a commit hook. The messages that do not have an approved
> commit message, usually start with a verb, which is selected by the
> commiter and is not consistent: (adding, fixed, moving, added,
> changing).
>
> I think, as computer scientists, we have learned that having an agreed
> upon lexicon is good.
>
> Bill
>
> Merge topic 'add-vtkvector-to-srcs'  master nightly-master
> COMP: Add vtkVector to Kit_SRCS so vtkChartsHie...
> Merge topic 'add-vtkvector-to-srcs'
> COMP: Add vtkVector to Kit_SRCS so vtkChartsHierarchy...
> Merge topic 'comp-cygwin-visibility'
> COMP: The "visibility" fix for mingw also applies to...
> Merge topic 'includes-system-remove'
> BUG: Fixed the source and system include separation.
> Merge topic 'comp-cygwin-gdi'
> COMP: Fix link errors related to not explicitly linking...
> Merge topic 'mni-file-readers'
> BUG: Fix crash when no filename set.
> COMP: Fix dashboard warnings.
> Merge topic 'mni-file-readers'
> ENH: Add test for vtkMNIObjectReader/Writer.
> STYLE: Documentation and formatting.
> ENH: Recognized the reserved data type 'V'.
> BUG: Remove the polygon reversal check, it doesn't...
> BUG: Removed the system include directories.
> COMP: On some platforms "index" is a system function.
> ENH: Add file IO classes for BIC-MNI file formats.
> Merge topic 'scalar-color-mapping'
> Merge topic 'ImplicitModellerSmallZFix'
> Fixed case where small Z dimension (less than # of...
> Adding in a safety check to avoid a divide by zero...
> Merge topic 'ParallelCoordinatesLeak'
> ENH: Fixed memory leak
> Fixed the issue with polygon offsets and near / far...
> Merge topic 'sortfilenames-opt'
> ENH: Pass strings to comparison function by reference.
> Merge topic 'asciiReader-eof-fix'
> Another boundary condition I missed...
> Moving an openGL call to the derived classes.
> Merge topic 'text-codecs-const-fix'
> COMP: Cannot return const bool - client server wrapping.
> Merge topic 'minc-attribute-validation'
> ENH: Fewer warnings for non-standard minc files.
> Merge topic 'Latin1-unicode-in-DelimitedTextReader'
> changed order of const and virtual in declarations...
> Merge topic 'Latin1-unicode-in-DelimitedTextReader'
> Added a call to delete the codec after we are done.
> Forgot PrintSelf methods which made one of the python...
> Merge topic 'comp-vtktextcodecfactory'
> Added an include for algorithm, some platforms do not...
> COMP: find is an algorithm. Need to #include <algorithm...
> Changing the amount of colors shown for lookup tables.
> Merge topic 'msvc_mp_flag_option'
> ENH: Added a configure option to enable /MP flag on...
> Merge topic 'Latin1-unicode-in-DelimitedTextReader'
> Merge topic 'legend_improvements'
> Fixed PrintSelf.
>
>
> On Fri, Oct 29, 2010 at 2:52 PM, David Cole <david.cole at kitware.com> wrote:
>> So, personally, I don't think the prefixes are that useful, but I will defer
>> to the wisdom of the crowd. I'll use prefixes if it's generally agreed
>> they're worthwhile.
>>
>>
>> On Fri, Oct 29, 2010 at 2:45 PM, Stephen Aylward
>> <stephen.aylward at kitware.com> wrote:
>>>
>>> Going over a day's work as a a project manager, it is good to know if
>>> bug fixes are being done or new features being added or style  fixes.
>>>
>>> Looking back as a developer, I'd like to know if someone was
>>> committing a bug fixed to my code or simply style changes.   Or when
>>> looking at other people's code, where there 100s of bug fixes applied
>>> to it, or just one or two.
>>>
>>> Looking back as a user, I'd like to know if a filter has been improved
>>> since I last downloaded it, or bugs fixed or whatever.
>>>
>>> Yes, Developer IQ errors that result in mislabelings are a problem -
>>> no need to throw out the baby with the bathwater...as my grandma
>>> actually never said, but I'm sure someone's grandmother once said.
>>>
>>> s
>>>
>>> On Fri, Oct 29, 2010 at 2:39 PM, David Cole <david.cole at kitware.com>
>>> wrote:
>>> > Out of curiosity: what are you scanning for?
>>> >
>>> > You want to know only about ENH or only about BUG fixes?
>>> >
>>> > What if one's mis-categorized and you miss it, just because one man's
>>> > bug is
>>> > another man's enh?
>>> >
>>> >
>>> > On Fri, Oct 29, 2010 at 2:37 PM, David Cole <david.cole at kitware.com>
>>> > wrote:
>>> >>
>>> >> It's documented on this page:
>>> >> http://www.itk.org/Wiki/Git/Hooks
>>> >>
>>> >> (Search on that page for "ENH:")
>>> >>
>>> >> Found by googling "commit message prefix ITK" oddly enough...
>>> >>
>>> >>
>>> >> :-)
>>> >> David C.
>>> >>
>>> >>
>>> >> On Fri, Oct 29, 2010 at 2:33 PM, Bill Lorensen
>>> >> <bill.lorensen at gmail.com>
>>> >> wrote:
>>> >>>
>>> >>> Yes, now I remumber. It wasn;'t just Brad, it was Dave also.
>>> >>>
>>> >>> Now that we have a wider ITK audience, the ITK developers decided many
>>> >>> years ago that the commit prefix was important. If the ITK developers
>>> >>> think that is no longer the case, then let it be.
>>> >>>
>>> >>> We are not trying to push our process on Cmake, VTK or Paraview.
>>> >>>
>>> >>> I think a consistent prefix helps the transition to git.
>>> >>>
>>> >>> Bill
>>> >>>
>>> >>>
>>> >>>
>>> >>> On Fri, Oct 29, 2010 at 2:27 PM, David Cole <david.cole at kitware.com>
>>> >>> wrote:
>>> >>> > On Fri, Oct 29, 2010 at 2:21 PM, David Doria <daviddoria at gmail.com>
>>> >>> > wrote:
>>> >>> >>
>>> >>> >> On Fri, Oct 29, 2010 at 2:14 PM, Stephen Aylward
>>> >>> >> <stephen.aylward at kitware.com> wrote:
>>> >>> >>>
>>> >>> >>> Ok,
>>> >>> >>>
>>> >>> >>> I thought we had decided on ITK to use them many many years ago,
>>> >>> >>> and
>>> >>> >>> I
>>> >>> >>> hadn't heard of a discussion to change.   Perhaps it was the VTK
>>> >>> >>> folks.
>>> >>> >>>
>>> >>> >>> We did previously have hooks for these, right?
>>> >>> >>>
>>> >>> >>> Those 4-5 characters provide critical info.   If anything, we
>>> >>> >>> should
>>> >>> >>> welcome them for the space and time they do save for those
>>> >>> >>> creating
>>> >>> >>> the messages as well as those reading them.   They embody all
>>> >>> >>> things
>>> >>> >>> good about shorthand, codes, keys, names, IDs, stereotypes,
>>> >>> >>> labels,
>>> >>> >>> acronyms, and abbrevs. in a simple, universally accepted package
>>> >>> >>> that
>>> >>> >>> only requires 4-5 characters per usage :)
>>> >>> >>>
>>> >>> >>> s
>>> >>> >>
>>> >>> >> I'm not sure how many prefixes there are, but the ones I know are
>>> >>> >> BUG,
>>> >>> >> STYLE, and ENH. If character count is the only concern, could they
>>> >>> >> be
>>> >>> >> shortened to B:, S:, and E: ? I vote +1 for mandatory prefixes.
>>> >>> >> David
>>> >>> >> _______________________________________________
>>> >>> >> Powered by www.kitware.com
>>> >>> >>
>>> >>> >> Visit other Kitware open-source projects at
>>> >>> >> http://www.kitware.com/opensource/opensource.html
>>> >>> >>
>>> >>> >> Kitware offers ITK Training Courses, for more information visit:
>>> >>> >> http://kitware.com/products/protraining.html
>>> >>> >>
>>> >>> >> Please keep messages on-topic and check the ITK FAQ at:
>>> >>> >> http://www.itk.org/Wiki/ITK_FAQ
>>> >>> >>
>>> >>> >> Follow this link to subscribe/unsubscribe:
>>> >>> >> http://www.itk.org/mailman/listinfo/insight-developers
>>> >>> >>
>>> >>> >
>>> >>> > The argument was brought up due to the switch to git. Since there
>>> >>> > are
>>> >>> > many
>>> >>> > tools/places where git is used ( 'git log --oneline' or 'git
>>> >>> > shortlog'
>>> >>> > ) to
>>> >>> > produce summary output, it is best to describe the change in 78
>>> >>> > characters
>>> >>> > or less for the first line, and then elaborate on that in subsequent
>>> >>> > lines
>>> >>> > if necessary.
>>> >>> >
>>> >>> > Some commits are easy to describe in one line, others not so much.
>>> >>> >
>>> >>> > For bug fix commits, Brad and I have taken to using "(#12345)" as
>>> >>> > the
>>> >>> > suffix
>>> >>> > on the first line.
>>> >>> >
>>> >>> > All other commits should be sufficiently described in English such
>>> >>> > that
>>> >>> > reading the one line indicates it's type.
>>> >>> >
>>> >>> > The prefixes make it harder to come up with the one-liner....
>>> >>> >
>>> >>> > At least those are the arguments.
>>> >>> >
>>> >>> > I prefer not having the prefixes enforced. That way, I can just
>>> >>> > describe
>>> >>> > what I did, and not worry about categorizing it and whether or not
>>> >>> > the
>>> >>> > community will agree with my own categorization.
>>> >>> >
>>> >>> >
>>> >>> > Another 2 cents,
>>> >>> > David C.
>>> >>> >
>>> >>> >
>>> >>> > _______________________________________________
>>> >>> > Powered by www.kitware.com
>>> >>> >
>>> >>> > Visit other Kitware open-source projects at
>>> >>> > http://www.kitware.com/opensource/opensource.html
>>> >>> >
>>> >>> > Kitware offers ITK Training Courses, for more information visit:
>>> >>> > http://kitware.com/products/protraining.html
>>> >>> >
>>> >>> > Please keep messages on-topic and check the ITK FAQ at:
>>> >>> > http://www.itk.org/Wiki/ITK_FAQ
>>> >>> >
>>> >>> > Follow this link to subscribe/unsubscribe:
>>> >>> > http://www.itk.org/mailman/listinfo/insight-developers
>>> >>> >
>>> >>> >
>>> >>
>>> >
>>> >
>>>
>>>
>>>
>>> --
>>>
>>> ==============================
>>> Stephen R. Aylward, Ph.D.
>>> Director of Medical Imaging Research
>>> Kitware, Inc. - North Carolina Office
>>> http://www.kitware.com
>>> stephen.aylward (Skype)
>>> (919) 969-6990 x300
>>
>>
>



-- 

==============================
Stephen R. Aylward, Ph.D.
Director of Medical Imaging Research
Kitware, Inc. - North Carolina Office
http://www.kitware.com
stephen.aylward (Skype)
(919) 969-6990 x300

More information about the Insight-developers mailing list