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:23:13 GMT
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