+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 <[email protected]> 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 <[email protected]> wrote: >>> >>> +1! >>>> >>>> Best, >>>> Yingyi >>>> >>>> On Wed, Jun 14, 2017 at 10:43 PM, Mike Carey <[email protected]> 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´ >>>>>> >>>>>> >>>>>
