asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Carey <dtab...@gmail.com>
Subject Re: Commit messages
Date Fri, 16 Jun 2017 00:07:14 GMT
ING?


On 6/15/17 3:45 PM, Till Westmann wrote:
> Ok, we could also do "TXN" -> "TX" and "RTM" -> "RT" as I think that
> those 2-letter acronyms are quite common.
> The one that confuses me (but I don’t have a good alternative) is "IGS".
> Any other alternatives that come to mind?
>
> Cheers,
> Till
>
> On 15 Jun 2017, at 15:27, Yingyi Bu wrote:
>
>> +1 for short acronyms:
>>
>> Here is a list of acronyms:
>> - API
>> - AQL
>> - CLUS (cluster management)
>> - COMP (compiler)
>> - CONF (configuration parameters/mgmt)
>> - DOC
>> - FAIL (failure handling)
>> - EXT (external)
>> - IDX
>> - IGS (ingestion)
>> - FUN (function)
>> - LIC
>> - MVN
>> - MTD (metadata)
>> - PERF (performance monitoring etc.)
>> - REPL
>> - RPC (cc/nc message)
>> - RTM (runtime)
>> - STAT (statistics etc.)
>> - SITE
>> - STR
>> - SQL
>> - TEST
>> - TXN (transaction)
>> - TYPE (data model)
>> - UDF (user defined function)
>> - UI
>>
>>
>> On Thu, Jun 15, 2017 at 3:23 PM, Till Westmann <tillw@apache.org> wrote:
>>
>>> But the first line should also be below 50 characters [1]. That might
>>> become tricky with a single component and it becomes more difficult, if
>>> a change touches more than one component (the ellipsis in [2] show the
>>> reason).
>>>
>>> To include components into the commit message it might be better to do
>>> that in the body instead of the subject (and we might want to use the
>>> same name that we use in JIRA).
>>> Also, it does seem redundant to have the components that are available
>>> in the referenced JIRA issue again in the message, but then it’s not
>>> exactly trivial to join the log messages with the components in JIRA
>>> (unless both are available in AsterixDB ;) )
>>>
>>> Alternatively, we could think about really short acronyms for the
>>> components to make them fit.
>>>
>>> Thoughts?
>>> Till
>>>
>>> [1] https://cwiki.apache.org/confluence/display/ASTERIXDB/Formatting
>>> [2] https://github.com/apache/spark/commits/master
>>>
>>>
>>> On 15 Jun 2017, at 14:55, Mike Carey wrote:
>>>
>>> +1
>>>>
>>>>
>>>> On 6/15/17 1:19 PM, Yingyi Bu wrote:
>>>>
>>>>> Each commit message should
>>>>>>> 1) reference 1 or more JIRA issues (that hopefully provide a

>>>>>>> rationale
>>>>>>>
>>>>>> for
>>>>>
>>>>>>    the change).
>>>>>>> 2) contain a description of changes to the user model (language

>>>>>>> syntax,
>>>>>>>    configuration parameters, ..)
>>>>>>> 3) contain a description of storage format changes (that would

>>>>>>> require
>>>>>>>    reloading or upgrading)
>>>>>>> 4) contain a description of interface changes (for source code
>>>>>>> consumers)
>>>>>>>
>>>>>> I wonder if we could put component name(s) into the headline of 
>>>>>> commit
>>>>> message.
>>>>>
>>>>> So the headline will be sth. like:
>>>>> [ASTERIXDB-2000][TXN] Fix a deadlock in LogManager
>>>>> [ASTERIXDB-2001][STORAGE] Clean up file handling in BufferCache
>>>>> ....
>>>>>
>>>>> It makes change localization easier.
>>>>>
>>>>> Examples:
>>>>> Spark: https://github.com/apache/spark/commits/master
>>>>> Flink: https://github.com/apache/flink/commits/master
>>>>>
>>>>> Here is a list of component names:
>>>>> - API
>>>>> - AQL
>>>>> - CLUSTER (cluster management)
>>>>> - COMPILER
>>>>> - CONFIGURATION (configuration parameters/mgmt)
>>>>> - DOC
>>>>> - FAILURE (failure handling)
>>>>> - EXTERNAL
>>>>> - INDEX
>>>>> - INGESTION
>>>>> - FUNC (function)
>>>>> - LICENSE
>>>>> - MAVEN
>>>>> - METADATA
>>>>> - PERF (performance monitoring etc.)
>>>>> - REPLICATION
>>>>> - RPC (cc/nc message)
>>>>> - RUNTIME
>>>>> - STATS (statistics etc.)
>>>>> - SITE
>>>>> - STORAGE
>>>>> - SQL++
>>>>> - TEST
>>>>> - TXN (transaction)
>>>>> - TYPE (data model)
>>>>> - UDF (user defined function)
>>>>> - UI
>>>>>
>>>>> Best,
>>>>> Yingyi
>>>>>
>>>>>
>>>>> On Thu, Jun 15, 2017 at 1:09 AM, Yingyi Bu <buyingyi@gmail.com>

>>>>> wrote:
>>>>>
>>>>> +1!
>>>>>>
>>>>>> Best,
>>>>>> Yingyi
>>>>>>
>>>>>> On Wed, Jun 14, 2017 at 10:43 PM, Mike Carey <dtabass@gmail.com>

>>>>>> wrote:
>>>>>>
>>>>>> +1 !!!
>>>>>>>
>>>>>>> I think this is a GREAT proposal, and we can also then hopefully

>>>>>>> do the
>>>>>>> equivalent of grep'ing the commits to identify things that we
might
>>>>>>> want to
>>>>>>> incorporate in a high-level set of release notes.  I also really

>>>>>>> like
>>>>>>> the
>>>>>>> "no" requirement. Also, storage changes should really NOT be
taken
>>>>>>> lightly
>>>>>>> - they seriously inconvenience our customers and will hopefully

>>>>>>> cause
>>>>>>> the
>>>>>>> tests to fail (the ones that check for backward-compat) - I 
>>>>>>> would like
>>>>>>> to
>>>>>>> set storage changes actually be voted on, ideally, if we could
make
>>>>>>> that
>>>>>>> part of our operating procedure somehow?
>>>>>>>
>>>>>>> Cheers,
>>>>>>>
>>>>>>> Mike
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On 6/14/17 9:15 AM, Till Westmann wrote:
>>>>>>>
>>>>>>> Hi,
>>>>>>>>
>>>>>>>> some of us had a discussion with an SDSC team last week that
is
>>>>>>>> running
>>>>>>>> an
>>>>>>>> AsterixDB instance. Their customer perspective on AsterixDB
>>>>>>>> highlighted a
>>>>>>>> few areas of improvement to ease the consumption of AsterixDB.
>>>>>>>>
>>>>>>>> One thing that I’d like to follow up on are release notes.
So 
>>>>>>>> far we
>>>>>>>> didn’t
>>>>>>>> provide them and so changes to the system came as a surprise
to
>>>>>>>> everybody
>>>>>>>> who is not monitoring commits closely.
>>>>>>>>
>>>>>>>> As I think that it’s not easy to provide good release notes
I’d 
>>>>>>>> like
>>>>>>>> to
>>>>>>>> propose some additions to our commit messages to ease the

>>>>>>>> creation of
>>>>>>>> release messages:
>>>>>>>>
>>>>>>>> Each commit message should
>>>>>>>> 1) reference 1 or more JIRA issues (that hopefully provide
a 
>>>>>>>> rationale
>>>>>>>> for
>>>>>>>>     the change).
>>>>>>>> 2) contain a description of changes to the user model (language
>>>>>>>> syntax,
>>>>>>>>     configuration parameters, ..)
>>>>>>>> 3) contain a description of storage format changes (that
would 
>>>>>>>> require
>>>>>>>>     reloading or upgrading)
>>>>>>>> 4) contain a description of interface changes (for source
code
>>>>>>>> consumers)
>>>>>>>>
>>>>>>>> and all reviewers should check that these are mentioned in
the 
>>>>>>>> commit
>>>>>>>> message. To increase the probability to we won’t forget
to 
>>>>>>>> mention the
>>>>>>>> changes in 2-4, I think that we should should explicitly

>>>>>>>> mention the
>>>>>>>> absence
>>>>>>>> of such changes, i.e.:
>>>>>>>>
>>>>>>>> user model changes: no
>>>>>>>> storage format changes: no
>>>>>>>> interface changes: no
>>>>>>>>
>>>>>>>> Thoughts/concerns about this?
>>>>>>>> Is this manageable?
>>>>>>>> Are there other kinds of changes that have a high impact
on 
>>>>>>>> consumers
>>>>>>>> that
>>>>>>>> we should call out?
>>>>>>>>
>>>>>>>> Cheers,
>>>>>>>> Till´
>>>>>>>>
>>>>>>>>
>>>>>>>


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message