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:45:39 GMT
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