Mailing-List: contact dev-help@asterixdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@asterixdb.apache.org
Subject: Re: Commit messages
To: dev@asterixdb.apache.org
References: <6DB13094-338D-4C68-B4D8-D14E06E1BEED@apache.org>
 <96b581ce-8650-9ef3-a7d1-db78b9acf73d@gmail.com>
 <CALjEsF7HL_PJ2GMjF94HO1CZhSfxkfbYXdfpLmL6EbmGQLSChA@mail.gmail.com>
 <CALjEsF5sg_SuQBsCt6Lew7FLeApDPaEtX6W5_kUF8pNuAgnEQQ@mail.gmail.com>
 <ca0beaf8-2e0d-dc15-e90b-a90237e71786@gmail.com>
 <83B6B7CC-FB92-40CB-ADB8-97CA87F8F45E@apache.org>
 <CALjEsF5VGK2fSjYMxSfpdMVCJ-URh3kLcVm15BoAqnF1Jds9VA@mail.gmail.com>
 <914E8150-2905-4C6B-9D1C-430AEC1CBCDA@apache.org>
 <CALjEsF6wUHudyKe-BOmp1CL0Gv-wa=aBnMGqv5ueTvGbDZ2RJA@mail.gmail.com>
From: Mike Carey <dtabass@gmail.com>
Message-ID: <ee03d0b8-1c1a-7cee-ac4e-3e8e69380b02@gmail.com>
Date: Thu, 15 Jun 2017 17:07:25 -0700
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:52.0)
 Gecko/20100101 Thunderbird/52.1.1
MIME-Version: 1.0
In-Reply-To: <CALjEsF6wUHudyKe-BOmp1CL0Gv-wa=aBnMGqv5ueTvGbDZ2RJA@mail.gmail.com>
Content-Type: multipart/alternative;
 boundary="------------3992BF545CBF51487317F65F"
Content-Language: en-US
archived-at: Fri, 16 Jun 2017 00:07:41 -0000

--------------3992BF545CBF51487317F65F
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit

+1 :-)


On 6/15/17 3:46 PM, 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´
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>


--------------3992BF545CBF51487317F65F--