[TYPO3-team-core-v5] Changelog considerations

[Bastian Waidelich]

Hi there,

since the first release of FLOW3 a "special" format for svn commit 
messages has been introduced by Robert and Karsten.
IIRC the rules are the following (please correct me, if I'm wrong):

One line per "issue", prefixed with one of the following codes: FEAT, 
FIX, API, CONF, TASK, !!!
where:
FEAT = Feature
FIX = Bugfix
API = Change in the public API
CONF = Configuration
TASK = Anything else
!!! = Breaking change

each code is enclosed in squere brackets and FEAT, FIX, API & CONF are 
prefixed by one of: +, -, ~
where:
+ = API has been extended
- = API has been reduced
~ = No API change

The prefix is followed by package name and (in round brackets) 
subpackage name followed by a custom message without trailing period.

Example:
[+FEAT] FLOW3 (AOP): Some greate AOP feature. Resolves #1234
[~FIX ] SomePackage (SomeSubpackage): Some bugfix without API changes
[ TASK] SomePackage (SomeSubpackage): Foo bar

These rules are not final yet, but I think it's a great start to add 
more semantic to the svn log and to be able to generate the changelog 
from it: http://wiki.typo3.org/FLOW3_1.0.0_alpha2#Changelog

Now my concerns:

1. These rules should be written down somewhere. And we might even 
enforce them by a simple pre-commit hook. what do you think?

2. AFAIK we don't have rules yet for ISSUE-keywords (fixes vs resolves 
and refs vs relates to). Personally, I'm favour of "Resolves #123" and 
"Relates to #123" because "fixes" is not always true and "refs" is not 
very clear IMO.

3. The changelog is really technical right now with all those codes and 
prefixes.. I'm thinking of a script that generates a more 
non-geek-readable version from the svn history.
I'm not really sure yet, how that could look like.. maybe something like:

=[ FLOW3 ]==============================================================

- Core -----------------------------------------------------------------

     FEATURES:
      - some feature
      - another feature
     CHANGES:
      - some task (extends the API)
     BUGFIXES:
      - some fix

- AOP ------------------------------------------------------------------

     FEATURES:
      - ...


alrighty, shoot now ;)

Bastian