asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Till Westmann" <ti...@apache.org>
Subject Re: Commit messages
Date Thu, 15 Jun 2017 22:50:41 GMT
Yes, works better for me.

Are there other opinions/concerns on the subject?

Thanks,
Till

On 15 Jun 2017, at 15:46, Yingyi Bu wrote:

> How about ING?
>
> Best,
> Yingyi
>
> On Thu, Jun 15, 2017 at 3:45 PM, Till Westmann <tillw@apache.org> 
> 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
View raw message