Re: [Development] Change file process & improvement proposal

[Oswald Buddenhagen]

On Thu, Jan 26, 2017 at 09:51:24AM +0100, Edward Welbourne wrote:
> I don't know what you're saying, much less why it's supposed to be the
> obvious interpretation.  A "tagged commit" is presumably v5.7.0 or
> similar; why should a commit without an amends line be assumed to
> relate to one of these ?
> 
i used "tagged commit" as a shorthand for "a commit which is reachable
from a tag", which should be fairly clear from the context. i.e., "git
tag --contains " returns something.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Edward Welbourne]

On Wed, Jan 25, 2017 at 10:21:09AM +0100, Edward Welbourne wrote:
>> However, you seem to be talking about *release* 5.x.0 rather than the
>> *branch* of that name, so I'm not really clear on what you're talking
>> about.

25 January 2017 12:13, Oswald Buddenhagen:
> i don't know how you arrived at this conclusion, but it isn't relevant
> to my reasoning anyway.

On the other hand, it's a fairly good clue to the possibility that I've
misunderstood what you were talking about.

>>> we could suppress the changelog enforcement for example by standardizing
>>> my "amends ." lines in the commit messages. if the reference is to
>>> a commit which has not been tagged yet, we know that users won't find it
>>> interesting.
>
>> I have never heard of these amends  lines; where are they
>> explained ?
>>
> git log --author=oswald

So a sort of after-the-fact fixup! tag.

>> In any case, users may find a change interesting even if there is no
>> specific earlier commit that can be pinned down [...]
>
> unsurprisingly, i think that the correct fallback in case of a missing
> reference is assuming that the commit relates to a tagged commit (if
> it's even a fix at all) and therefore complaining about a missing
> changelog.

I don't know what you're saying, much less why it's supposed to be the
obvious interpretation.  A "tagged commit" is presumably v5.7.0 or
similar; why should a commit without an amends line be assumed to relate
to one of these ?  I *can* see how an amends line would be a basis for
not demanding a changelog entry, though.

Eddy.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Oswald Buddenhagen]

On Wed, Jan 25, 2017 at 10:21:09AM +0100, Edward Welbourne wrote:
> However, you seem to be talking about *release* 5.x.0 rather than the
> *branch* of that name, so I'm not really clear on what you're talking
> about.
> 
i don't know how you arrived at this conclusion, but it isn't relevant
to my reasoning anyway.

> > we could suppress the changelog enforcement for example by standardizing
> > my "amends ." lines in the commit messages. if the reference is to
> > a commit which has not been tagged yet, we know that users won't find it
> > interesting.
> 
> I have never heard of these amends  lines; where are they
> explained ?
>
git log --author=oswald

> In any case, users may find a change interesting even if there is no
> specific earlier commit that can be pinned down [...]
>
unsurprisingly, i think that the correct fallback in case of a missing
reference is assuming that the commit relates to a tagged commit (if
it's even a fix at all) and therefore complaining about a missing
changelog.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Shawn Rutledge]

> On 25 Jan 2017, at 10:21, Edward Welbourne  wrote:
> 
> I have never heard of these amends  lines; where are they
> explained ?  In any case, users may find a change interesting even if
> there is no specific earlier commit that can be pinned down as what this
> new change amends - sometimes, the origin of a status quo (being
> amended) is murky, its causes are contentious and most of the lines of
> prior code involved date from the 190MB commit 38be0d1383 that pulled
> most of our code into git in the first place.  Still, maybe your
> amends-spec addresses that …

You’ll find many of them in the logs, and every valid SHA1 (or even unique 
prefix of a SHA1) turns into a link automatically in some tools such as gitk, 
and the git log viewer in Creator, which helps a bit with following the chain 
of reasoning behind a block of code.  Forming a link which identifies a subset 
of the lines of the patch would be really very cool, but I don’t know of a way.

___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Edward Welbourne]

On Tue, Jan 24, 2017 at 03:38:11PM +0100, Edward Welbourne wrote:
>>> Proposal: Check for [ChangeLog] entries in a 5.x branch _after 5.x.0
>>> branched_. Is that easy to enable/disable?
>>
>> It should be easy to detect that 5.x.0 "has branched" - check for
>> existence of either origin/5.x.0 branch or v5.x.0 tag. [...]

On 24 January 2017 16:20, Oswald Buddenhagen replied:
> that's answering the wrong question. changes for 5.x.0 may require a
> changelog just as well, as the branch may receive fixes against 5.(x-1).

What the proposal actually asked for was technically feasible; so I said
how to do it.  My impression was that the proposal was motivated by a
claim that stabilisation fixes typically won't want a change-log, as
they're fixes to recent changes.  The reasoning there may in fact be
flawed - a fix to a recent change *with a change-log entry* might well
need to amend/update the change-log entry.  Still, aside from that, I
suppose patch branches (M.m.p) are typically such stabilisation.

However, you seem to be talking about *release* 5.x.0 rather than the
*branch* of that name, so I'm not really clear on what you're talking
about.

> we could suppress the changelog enforcement for example by standardizing
> my "amends ." lines in the commit messages. if the reference is to
> a commit which has not been tagged yet, we know that users won't find it
> interesting.

I have never heard of these amends  lines; where are they
explained ?  In any case, users may find a change interesting even if
there is no specific earlier commit that can be pinned down as what this
new change amends - sometimes, the origin of a status quo (being
amended) is murky, its causes are contentious and most of the lines of
prior code involved date from the 190MB commit 38be0d1383 that pulled
most of our code into git in the first place.  Still, maybe your
amends-spec addresses that ...

Eddy.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Oswald Buddenhagen]

On Tue, Jan 24, 2017 at 03:38:11PM +0100, Edward Welbourne wrote:
> > Proposal: Check for [ChangeLog] entries in a 5.x branch _after 5.x.0
> > branched_. Is that easy to enable/disable?
> 
> It should be easy to detect that 5.x.0 "has branched" - check for
> existence of either origin/5.x.0 branch or v5.x.0 tag. [...]
>
that's answering the wrong question. changes for 5.x.0 may require a
changelog just as well, as the branch may receive fixes against 5.(x-1).

we could suppress the changelog enforcement for example by standardizing
my "amends ." lines in the commit messages. if the reference is to
a commit which has not been tagged yet, we know that users won't find it
interesting.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Edward Welbourne]

> Proposal: Check for [ChangeLog] entries in a 5.x branch _after 5.x.0 
> branched_. Is that easy to enable/disable?

It should be easy to detect that 5.x.0 "has branched" - check for
existence of either origin/5.x.0 branch or v5.x.0 tag.  That we're
committing to 5.x is fairly easy *in Gerrit* (with its relatively
conservative branch set), and checking for 5.x when folk are using that
locally for development is easy, but checking a topic-branch for whether
it's based on (so presumptively targetting) 5.x rather than 5.y or dev
may be trickier.  (Getting such checks through code review may also be
tricky; c.f. https://codereview.qt-project.org/177706 ...)

Eddy.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Kai Koehne]

Looks like this discussion got stuck before reaching a conclusion ...

> -Original Message-
> From: Development [mailto:development-bounces+kai.koehne=qt.io@qt-
> project.org] On Behalf Of Oswald Buddenhagen
> Sent: Thursday, November 10, 2016 3:23 PM
> To: development@qt-project.org; releas...@qt-project.org
> Subject: Re: [Development] Change file process & improvement proposal
> [...]
> > 1) Let's enable [ChangeLog] -tag by default in commit template. After
> > that you must remove/comment out it by purpose if you don't want add
> > it.
> >
> i really don't think this will make a positive difference. the problem is that
> many people just don't have the right audience-oriented mindset.
> we *already* have lots of garbage changelog entries, and this will just
> worsen the S/N ratio.

Actually looking through the commit logs e.g. in qtbase, I do think most 
[ChangeLog] entries are rather fine - surely some tweaking is sometimes 
necessary, but the quality of the ChangeLog entries we have is not all that bad.

What is obvious though is that a lot of commits where I would have expected a 
[ChangeLog] do not have one. What's more, a well written [ChangeLog] entry will 
help also during the review, and can serve as a sanity check when it comes to 
the right branch being targeted etc.

I therefore agree with Janne that we should encourage people to write them, and 
changing the default template is a very easy thing to do.

> > And in addition to this update sanity bot so that it will give '-1' if
> > change log entry isn't given in release branch.
> >
> this is probably not sensible. most last-minute fixes relate to recently
> introduced problems, which means that they specifically *don't* need
> changelog entries.

That might be the case until the first .0 release from the branch is done, but 
surely not afterwards.

Proposal: Check for [ChangeLog] entries in a 5.x branch _after 5.x.0 branched_. 
Is that easy to enable/disable?

> here's what i think would actually make a difference (based on historical
> evidence within trolltech):
> https://bugreports.qt.io/browse/QTQAINFRA-933

Such a tool/infrastructure would be cool to have, indeed. It requires a lot 
more investment though than the incremental changes Jani proposed. 

I therefore suggest to implement Jani's suggestions for the time being. If we 
find out they're not effective, we can always come back and look into 
alternative processes.

1. Enable [ChangeLog] tag in commit template

https://codereview.qt-project.org/183244

2. Add check in sanity bot to check for missing ChangeLog entries (potentially 
only in 5.x branches after 5.x.0 is out)

(who could do this?)

Regards

Kai

___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Edward Welbourne]

On Thu, Nov 10, 2016 at 12:38:41PM +, Jani Heikkinen wrote:
>> Lately it has been quite hard to get change files done for the releases.
and Ossi replied:
> oh, it's that time of the year again. :D

Speaking of which, it's also hard to get API reviews done, even though
they are now much easier (because they get represented properly as
gerrit reviews that show the change properly).  See recent mail: of 17
modules with API reviews, one has a +2 and one a +1 on the latest PS;
one has +1 on the previous; two are new reviews (I may have lost an
earlier review) with no comments; three have comments on earlier PSs;
qtwebengine's team concocted a better review (that's rather out of date)
and have reviewed it; qtserialbus's maintainers note the need for a full
API review; but seven add-on modules have had no comments.  (Three of
these were new in 5.7; the rest have been add-ons since at least 5.6.)

Gerrit's diffs between patch sets work for you here: if you've reviewed
an earlier patch set, you can review the change since in the usual
useful way.  No rebasing has happened.

Please review (changelogs and) changes to your module APIs,

Eddy.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Change file process & improvement proposal

[Oswald Buddenhagen]

On Thu, Nov 10, 2016 at 12:38:41PM +, Jani Heikkinen wrote:
> Lately it has been quite hard to get change files done for the releases.
>
oh, it's that time of the year again. :D

> 1) Let's enable [ChangeLog] -tag by default in commit template. After
> that you must remove/comment out it by purpose if you don't want add
> it.
>
i really don't think this will make a positive difference. the problem
is that many people just don't have the right audience-oriented mindset.
we *already* have lots of garbage changelog entries, and this will just
worsen the S/N ratio.

> And in addition to this update sanity bot so that it will give '-1' if
> change log entry isn't given in release branch.
>
this is probably not sensible. most last-minute fixes relate to recently
introduced problems, which means that they specifically *don't* need
changelog entries.

here's what i think would actually make a difference (based on
historical evidence within trolltech):
https://bugreports.qt.io/browse/QTQAINFRA-933

> 2) Let's agree every submodule in the release needs to have a change
> file (to make things clear)
> 
yes

> 3) Let's agree the change log is the diff between new & previous
> release in same series (in case of patch level release, meaning delta
> from x.y.z -> x.y.z+1). And for new major release the diff is from
> last patch release from previous series
> 
that seems a no-brainer to me. the tricky question is what to do with
LTS vs. stable, but we already resolved this: we duplicate the relevant
log entries.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development