[TYPO3-team-core-v5] Changelog considerations

[Robert Lemke]

Hi Bastian,

On 01.07.2009, at 17:38, Bastian Waidelich wrote:

> 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

Taking Masi's advice, let's change them to:

FEATURE
FIX
API
CONFIGURATION
TASK
!!!

They should be combinable like:

[!!!][-API] FLOW3 (Core): The Bootstrap's run() method has been  
removed. Please don't run FLOW3, write your own framework.

> 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

+ = something has been added
- = something has been removed
~ = something has been changed

The meaning depends on the tag of course:

[+CONFIGURATION] = a configuration option has been added
[~CONFIGURATION] = the meaning or syntax of configuration option has  
changed

etc.

> 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

Correct. If you parse the messages anyway, we can also omit the spaces
in the tags:

[~FIX] instead of [~FIX ]

> 1. These rules should be written down somewhere.

They'll end up in the manual - Karsten will take care of it.

> And we might even enforce them by a simple pre-commit hook.
> What do you think?

Well, why not - can you do that?

> 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.

My suggestion:

"Resolves" if it resolves a feature request or task.
"Fixes" if it fixes a bug.
"Relates to" if it doesn't close the given issue but relates to it.

We probably don't need "Closes" because if something is committed for
closing an issue it certainly resolves the task. Issues are usually
close (without solving them) without a related commit.

> 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 ;)

Yes, I'd be very happy if you or someone else could write a little php
script doing that conversion. Just a standalone script - I'll integrate
that later into a whole-in-one release app.

Cheers,
robert