[Development] dist/changes-x.y.z (was: Re: Branches)

[Marc Mutz]

On Friday December 7 2012, Jedrzej Nowacki wrote:
> On Friday 7. December 2012 13.52.43 you wrote:
> > On Friday December 7 2012, Jedrzej Nowacki wrote:
> > > On Thursday 6. December 2012 19.08.41 Olivier Goffart wrote:
> > > > On Thursday 06 December 2012 17:58:57 shane.kearns at accenture.com 
wrote:
> > > > > > Hi Lars,
> > > > > >
> > > > > > On Monday December 3 2012, Knoll Lars wrote:
> > > > > > > Dev:
> > > > > > >
> > > > > > > Dev is the branch where you can land anything that's supposed
> > > > > > > to go into 5.1. The following policies apply:
> > > > > > >
> > > > > > > * Changes have to be source and binary compatible
> > > > > > > * You can add new method and classes given that they are fully
> > > > > > > documented and tested * Please do not add half finished
> > > > > > > features. Create your own branch for that, and only push your
> > > > > > > changes once the
> > > > > >
> > > > > > feature is fully done.
> > > > > >
> > > > > > Should we add:
> > > > > >
> > > > > > * carries a change to dist/changes-5.1.0 if it's
> > > > > > (Qt-)user-visible (bug fixes,
> > > > > >
> > > > > >   new features, performance fixes)?
> > > > > >
> > > > > > Same for stable once 5.0.0 branches off?
> > > > >
> > > > > This would cause many more staging conflicts, as most changes would
> > > > > touch the same file. I'd suggest that bug fixes should not touch
> > > > > the changes file, only new features.
> > > >
> > > > I suggest we add a new header in our commit messages such as
> > > > "Changelog:" Someting that can be parsed to generate the changelog
> > > > automatically.
> > >
> > > Hi,
> > >
> > >   Another alternative is to say that in dist/changes we should have
> > > only a
> > >
> > > major changes and bug fixes. It means that we need to filter every
> > > commit that has Qt bug number in it or it is a merge from a feature
> > > branch.
> >
> > That would require allocating a bug number for every bug, something we
> > don't currently do, but would indeed be nice to have.
>
> We do not put every bug fix into dist/changes either, only most wanted /
> important ones, which usually have a bug report. Definitely I would not go
> into direction of having one bug report per commit, It would create
> unnecessary paper work.
>
> > But how would you filter 'major changes'? Or are you saying that they
> > should be added to dist/changes in the commit that introduces them?
>
> It would be a valid solution too, but I was thinking about something
> different. In the current work flow a major change should be developed in a
> feature branch and merged to "dev" when ready. The merge would create a
> commit, which could be find in git history more or less easly. Then just
> before release we can generate the dist/changes file.
>
> > The latter would work for me, but you seem to be suggesting some other
> >
> > mechanism:
> > > The
> > > alternative is nice, because it would work with the current work flow,
> > > without changing anything, we only need to be strict about feature
> > > merge commit message, it should be verbose, describing the feature.
> > > That is all, everything else can be generated from git log and jira.
> >
> > The above sounds like sifting through a _lot_ of commits pre-5.1, which
> > isn't really an attractive activity. Or are you saying that every new
> > feature should have a JIRA issue, too?
>
> Sure, but it may be semi automatic.
> 1. save git history from the last update of dist/changes
> 2. search in the history for all "Task-number" and save them to the
> dist/changes as closed bugs
> 3. search in the history for all feature branch merges and save their
> commit massages to the dist/changes
> 4. commit dist/changes


That's assuming that new features necessarily come in the form of a topic 
branch. That's probably true for some of them, but most consists only of one 
commit (followed by any number of 'oops' commits, which a topic branch 
wouldn't help with, either).

Are you suggesting to enforce the use of a topic branch for new features, 
regardless of how small they are?

I'm sorry if I seem like the devil's advocate here, but I think that the 5.0 
anything-goes-forget-about-dist/changes policy has corrupted contributors in 
this regard (it certainly corrupted me: I'm extremely happy that I won't have 
to expect a mail re: Please add of all of your 5.0 changes to dist/changes, 
as we got pre-4.8).

The alternative would be to say: forget about dist/changes and generate it 
completely in the form of the git history (like other projects do), but the 
commit messages don't currently have the necessary quality, either; some are 
impossible to understand unless you look at the diff, too, which a changelog 
wouldn't contain, of course. dist/changes at least can be updated after a 
change has been merged, unlike commit messages.

Burdening the maintainer with generating the changes file after an onslaught 
of dozens of committers and 100s of changes without regards to the changes 
file is - I repeat - not an attractive prospect :(

Thanks,
Marc


-- 
Marc Mutz <marc.mutz at kdab.com> | Senior Software Engineer
KDAB (Deutschland) GmbH & Co.KG, a KDAB Group Company
www.kdab.com || Germany +49-30-521325470 || Sweden (HQ) +46-563-540090
KDAB - Qt Experts - Platform-Independent Software Solutions