asterixdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Yingyi Bu <buyin...@gmail.com>
Subject Re: Commit messages
Date Thu, 15 Jun 2017 22:27:24 GMT
+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