Re: [Development] Changelogs for 5.3.0

[Thiago Macieira]

Em qui 24 abr 2014, às 16:25:41, Bache-Wiig Jens escreveu:
> On a somewhat related note, I would suggest that for future updates we
> standardize on putting the bug-id after each item entry rather than in front
> as that would make the document a bit more readable in my opinion. I don’t
> really see any valid reason why people would remember a specific task
> number and scan that list manually.
> 
> Jens

Sounds good. You can submit an update to the create_changelog.pl script 
(qtsdk/packaging-tools), it should be fairly simple. I'll do it later if you 
don't though.

PS: it would be nice if the changes to the changelog script got approved by 
someone...
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

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

Re: [Development] Changelogs for 5.3.0

[Bache-Wiig Jens]

I edited and updated the controls related change log here:

https://codereview.qt-project.org/#change,84066

On a somewhat related note, I would suggest that for future updates we
standardize on putting the bug-id after each item entry rather than in front
as that would make the document a bit more readable in my opinion.
I don’t really see any valid reason why people would remember a specific
task number and scan that list manually.

Jens

On 24 Apr 2014, at 06:57, Thiago Macieira 
mailto:thiago.macie...@intel.com>> wrote:

Em qua 23 abr 2014, às 21:22:40, Alan Alpert escreveu:
On Tue, Apr 22, 2014 at 3:13 PM, Thiago Macieira

mailto:thiago.macie...@intel.com>> wrote:
Please find attached the raw logs for each of the modules that had any
[ChangeLog] in the v5.2.1..origin/release range.

I'm taking responsibility of editing the one for qtbase.

For all other modules, I'd like someone to reply to this email saying
they'll be the editor. Otherwise, there will be no changelog for the
module at all, because I won't do it.

I'll edit qtquick1. First draft at
https://codereview.qt-project.org/#change,83982 (and it's just one
item... probably ready to go).

Also qtdeclarative, which I didn't see in the attachments, but running
the script and adding the output to the existing changelog gives
another 'first' draft: https://codereview.qt-project.org/#change,83983

Comments there.
--
Thiago Macieira - thiago.macieira (AT) intel.com
 Software Architect - Intel Open Source Technology Center

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

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

Re: [Development] Changelogs for 5.3.0

[Thiago Macieira]

Em qua 23 abr 2014, às 21:22:40, Alan Alpert escreveu:
> On Tue, Apr 22, 2014 at 3:13 PM, Thiago Macieira
> 
>  wrote:
> > Please find attached the raw logs for each of the modules that had any
> > [ChangeLog] in the v5.2.1..origin/release range.
> > 
> > I'm taking responsibility of editing the one for qtbase.
> > 
> > For all other modules, I'd like someone to reply to this email saying
> > they'll be the editor. Otherwise, there will be no changelog for the
> > module at all, because I won't do it.
> 
> I'll edit qtquick1. First draft at
> https://codereview.qt-project.org/#change,83982 (and it's just one
> item... probably ready to go).
> 
> Also qtdeclarative, which I didn't see in the attachments, but running
> the script and adding the output to the existing changelog gives
> another 'first' draft: https://codereview.qt-project.org/#change,83983

Comments there.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

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

Re: [Development] Changelogs for 5.3.0

[Alan Alpert]

On Tue, Apr 22, 2014 at 3:13 PM, Thiago Macieira
 wrote:
> Please find attached the raw logs for each of the modules that had any
> [ChangeLog] in the v5.2.1..origin/release range.
>
> I'm taking responsibility of editing the one for qtbase.
>
> For all other modules, I'd like someone to reply to this email saying they'll
> be the editor. Otherwise, there will be no changelog for the module at all,
> because I won't do it.

I'll edit qtquick1. First draft at
https://codereview.qt-project.org/#change,83982 (and it's just one
item... probably ready to go).

Also qtdeclarative, which I didn't see in the attachments, but running
the script and adding the output to the existing changelog gives
another 'first' draft: https://codereview.qt-project.org/#change,83983

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

Re: [Development] Changelogs for 5.3.0

[Samuel Gaist]

On 23 avr. 2014, at 09:16, Thiago Macieira  wrote:

> Em qua 23 abr 2014, às 08:49:47, Samuel Gaist escreveu:
 - QTBUG-4714:
  * [QTBUG-4714] Use the grid size for wordwrapping when available in
 icon
mode Task-number: QTBUG-4714 Change-Id:
I2cb63809d3ee8bd262f38bc11de91df9ff5cf237 Reviewed-by: Stephen Kelly

>>> 
>>> 
>> 
>> QtWidgets/QListView:
>> 
>> Until now, when QListView was in icon mode, the word wrapping was always
>> done using the icon size which would be ugly if you had small icons on a
>> "big" grid. From now on, if the grid size is set, it will be used for word
>> wrapping.
> 
> Can you make it a little shorter? Please use the rest of the changelog as a 
> template.
> 


Sure, I can try. This one sounds more concise and clear:

 * [QTBUG-4714] Fixed QListView ignoring the grid size for word wrapping in 
icon mode

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

Re: [Development] Changelogs for 5.3.0

[Oswald Buddenhagen]

On Wed, Apr 23, 2014 at 12:26:41AM -0700, Thiago Macieira wrote:
> Em qua 23 abr 2014, às 09:16:05, Joerg Bornemann escreveu:
> > On 23-Apr-14 09:04, Giuseppe D'Angelo wrote:
> > > And no, commit message and changelog can't use the same rules.
> > 
> > Well you can have simple rules or people making mistakes. It's as simple
> > as that.
> > 
luckily, we have attentive reviewers, right?

> > At the very least it should be more visible which linguistic mode we
> > have to use in what context and where a haiku would be appropriate.
> 
> We can standardise on the simple past for everything. Just note that it costs 
> you 2 extra characters on the 72-character subject line (and the sanity bot 
> starts complaining at 67).
> 
it's actually gerrit, following the git recommendations (which are
optimized for shortlog, log --oneline, merge --log, etc. in an 80 col
terminal). the bot is more liberal.

> Still, that doesn't change the fact that the two things have two
> different audiences and convey two different messages.
>
that's precisely the crux. many of the entries you pointed out make it
blatantly obvious that a lot of people don't think at all about whom
they are writing for. it would appear that it's just another box to be
checked in a form (the commit message template, that is) ... with that
mindset, the different tense requirements are the least of the problems.

on the upside, it seems that the commit messages (at least in qtbase,
from a quick glance) have a reasonable quality, and noobs are usually
quickly clued in by the reviewers.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Changelogs for 5.3.0

[Thiago Macieira]

Em qua 23 abr 2014, às 09:16:05, Joerg Bornemann escreveu:
> On 23-Apr-14 09:04, Giuseppe D'Angelo wrote:
> > And no, commit message and changelog can't use the same rules. A
> > commit message is usually in the imperative mode, present tense ("Fix
> > foo"), and uses pluralis maiestatis + indicative in the body ("We do
> > this, but we should do that, so this commit fixes it"). A changelog
> > uses indicative past simple ("Fixed foo"), or passive present perfect
> > ("Foo has been fixed"), and in general privileges an impersonal form
> > ("It is now possible to use foo"), all of which indicate that the
> > change has already happened in the past.
> 
> Well you can have simple rules or people making mistakes. It's as simple
> as that.
> 
> At the very least it should be more visible which linguistic mode we
> have to use in what context and where a haiku would be appropriate.

We can standardise on the simple past for everything. Just note that it costs 
you 2 extra characters on the 72-character subject line (and the sanity bot 
starts complaining at 67).

Still, that doesn't change the fact that the two things have two different 
audiences and convey two different messages.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

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

Re: [Development] Changelogs for 5.3.0

[Joerg Bornemann]

On 23-Apr-14 09:04, Giuseppe D'Angelo wrote:

> And no, commit message and changelog can't use the same rules. A
> commit message is usually in the imperative mode, present tense ("Fix
> foo"), and uses pluralis maiestatis + indicative in the body ("We do
> this, but we should do that, so this commit fixes it"). A changelog
> uses indicative past simple ("Fixed foo"), or passive present perfect
> ("Foo has been fixed"), and in general privileges an impersonal form
> ("It is now possible to use foo"), all of which indicate that the
> change has already happened in the past.

Well you can have simple rules or people making mistakes. It's as simple 
as that.

At the very least it should be more visible which linguistic mode we 
have to use in what context and where a haiku would be appropriate.


Cheers,

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

Re: [Development] Changelogs for 5.3.0

[Thiago Macieira]

Em qua 23 abr 2014, às 08:49:47, Samuel Gaist escreveu:
> >> - QTBUG-4714:
> >>   * [QTBUG-4714] Use the grid size for wordwrapping when available in
> >>icon
> >> mode Task-number: QTBUG-4714 Change-Id:
> >> I2cb63809d3ee8bd262f38bc11de91df9ff5cf237 Reviewed-by: Stephen Kelly
> >> 
> >
> > 
> 
> QtWidgets/QListView:
> 
> Until now, when QListView was in icon mode, the word wrapping was always
> done using the icon size which would be ugly if you had small icons on a
> "big" grid. From now on, if the grid size is set, it will be used for word
> wrapping.

Can you make it a little shorter? Please use the rest of the changelog as a 
template.

You don't need to justify the change. You just need to say *what* behaviour 
the user should expect. Only if it's important should you mention the old 
behaviour.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

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

Re: [Development] Changelogs for 5.3.0

[Thiago Macieira]

Em qua 23 abr 2014, às 09:04:35, Giuseppe D'Angelo escreveu:
> And no, commit message and changelog can't use the same rules. A
> commit message is usually in the imperative mode, present tense ("Fix
> foo"), and uses pluralis maiestatis + indicative in the body ("We do
> this, but we should do that, so this commit fixes it"). A changelog
> uses indicative past simple ("Fixed foo"), or passive present perfect
> ("Foo has been fixed"), and in general privileges an impersonal form
> ("It is now possible to use foo"), all of which indicate that the
> change has already happened in the past.

To be clear: there are two different audiences here.

The main commit message is intended to other Qt developers, notably the 
reviewers and your future selves. It's intended to explain *why* the change 
was made and why this particular change, as opposed to other possible 
alternatives. Don't describe the change -- we can read diffs. Describe the 
solution; describe the issue you found and how you're fixing it; describe your 
clever hacks; etc.

We generally use the imperative for commit messages ("Fix this" or "Make that 
, but third person present indicative ("Fixes this" and "Makes that") as well 
as past tense ("Fixed this" and "Made that") are fine. A commit message is 
always attached to a commit, so it's co-temporal with it.

The changelog, however, is not intended for other Qt developers. It's intended 
for Qt users, to be published on our website along with the release. Users 
don't care how a bug was fixed, only that it was; they don't care much about 
what the old and broken behaviour was, they care about what the new behaviour 
is. Changelogs are not attached to commits, but instead to releases and they 
refer to things that happened in the development of that release. That's why 
you describe things that happened in the past ("Fixed a bug") or about 
behaviour that the user should expect now and in the future.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

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

Re: [Development] Changelogs for 5.3.0

[Giuseppe D'Angelo]

On 23 April 2014 08:30, Joerg Bornemann  wrote:
> According to The Law I have to write the commit message in imperative
> and the changelog in indicative mode.

I think it's time to become way more strict on our changelog entries,
as I feel we're abusing of Thiago's patience to fix them up before
every release.

And no, commit message and changelog can't use the same rules. A
commit message is usually in the imperative mode, present tense ("Fix
foo"), and uses pluralis maiestatis + indicative in the body ("We do
this, but we should do that, so this commit fixes it"). A changelog
uses indicative past simple ("Fixed foo"), or passive present perfect
("Foo has been fixed"), and in general privileges an impersonal form
("It is now possible to use foo"), all of which indicate that the
change has already happened in the past.

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

Re: [Development] Changelogs for 5.3.0

[Samuel Gaist]

Hi,

On 23 avr. 2014, at 01:09, Thiago Macieira  wrote:

> Here's some editing I've done. This serves as suggestions for other editors.
> 
>> - QPA/Android:
>>   * [QTBUG-36025] Fixed a memory leak in the clipboard
> 
> Moved to Android changes. Why was this in QtCore in the first place? QPA is a 
> QtGui technology…
> 

My bad, I was thinking GUI core component and mistyped the module.

>> -
>> - QTBUG-4714:
>>   * [QTBUG-4714] Use the grid size for wordwrapping when available in icon
>> mode Task-number: QTBUG-4714 Change-Id:
>> I2cb63809d3ee8bd262f38bc11de91df9ff5cf237 Reviewed-by: Stephen Kelly
>> 
> 

QtWidgets/QListView:

Until now, when QListView was in icon mode, the word wrapping was always done 
using the icon size which would be ugly if you had small icons on a "big" grid. 
From now on, if the grid size is set, it will be used for word wrapping.



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

Re: [Development] Changelogs for 5.3.0

[Joerg Bornemann]

On 23-Apr-14 01:09, Thiago Macieira wrote:

> [...] It's also in the
> imperative -- why are you telling the user to rework the implementation?

I reckon, it's because our commit policy 
(http://qt-project.org/wiki/Commit_Policy) suggests to use it for commit 
messages: "consider the generic Git commit message guidelines", which 
says "Write your commit message in the imperative".
According to The Law I have to write the commit message in imperative 
and the changelog in indicative mode.
I suggest to use the same mode for commit messages and change logs (I 
really don't care which one). This would reduce the chances for mistakes.


Cheers,

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

Re: [Development] Changelogs for 5.3.0

[Blasche Alexander]

qtconnectivity and qtlocation were taken care of by me.

--
Alex


From: development-bounces+alexander.blasche=digia@qt-project.org 
[development-bounces+alexander.blasche=digia@qt-project.org] on behalf of 
Thiago Macieira [thiago.macie...@intel.com]
Sent: Wednesday, April 23, 2014 00:13
To: development@qt-project.org
Subject: [Development] Changelogs for 5.3.0

Please find attached the raw logs for each of the modules that had any
[ChangeLog] in the v5.2.1..origin/release range.

I'm taking responsibility of editing the one for qtbase.

For all other modules, I'd like someone to reply to this email saying they'll
be the editor. Otherwise, there will be no changelog for the module at all,
because I won't do it.
--
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Changelogs for 5.3.0

[Thiago Macieira]

Em ter 22 abr 2014, às 16:09:07, Thiago Macieira escreveu:
> >  - QTextDocumentLayout:
> >* [QTBUG-36743] Emit updateBlock signal in QTextDocumentLayout.
> 
> "The updateBlock() signal is now emitted".
> 
> This implies we had a signal that was never emitted before. If that's not 
> correct, please provide a better entry.
> 
> By the way, that's a bad signal name. Signals are supposed to indicate
> state  changes. "Update block" has a verb in the imperative for a core
> component, which is naming rule for slots. Please deprecate this signal and
> introduce a better one.

Entry removed. This is changelog entry is complete nonsense.

There's no such signal in QTextDocumentLayout. You can't emit a signal that 
doesn't exist.

And QTextDocumentLayout is a private class.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

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

Re: [Development] Changelogs for 5.3.0

[Thiago Macieira]

Here's some editing I've done. This serves as suggestions for other editors.

Everyone who has committed to qtbase please read through because I have 
editing questions for you.

Em ter 22 abr 2014, às 15:13:41, Thiago Macieira escreveu:
>  GLES3 and desktop OpenGL are now fully supported with EGL
> --
> 
>  - [QTBUG-37332] 

Source:
[ChangeLog] GLES3 and desktop OpenGL are now fully supported with EGL

>  Native (that is, not distance field based) text
> rendering is now functional on OpenGL 3.2+ core profiles too.
> 
> --
> 
>  - [QTBUG-36993] 

Source:
[ChangeLog] Native (that is, not distance field based) text
rendering is now functional on OpenGL 3.2+ core profiles too.

The above two are actually properly formatted changelogs, but they don't 
specify which area you'd like them in. I've placed them under [QtGui].

> 
>  QFileSelector: the identifier for OS X has been changed back
> to 'osx' from 'mac', and 'mac' and 'darwin' have now been added as
> selectors for Darwin OS (which is the base of both OS X and iOS).
> 
> 
> --
> 
>  - [QTBUG-35073] 

Moved to [QtCore][QFileSelector]

> Android
> ---

>  - [QTBUG-34650] Rework the raster and opengl implementation.
>[ChangeLog][Android] Create a single android platform plugin.

Deleted. This is useless information to the end user. It's also in the 
imperative -- why are you telling the user to rework the implementation?

It's also missing an empty line between the two changelogs.

>  - [QTBUG-30652] Allow the developers to define a splash screen which will
>be visible until the first window is created.

"It is now possible to define ..."

>  - [QTBUG-33704] Speed up first time directory listing in assets by using
>pregenerated entry list.

"Sped up"

>  - [QTBUG-36974] Fixed double click events

Requires more information. Were all double click events so bad that they were 
unusable?

Deleted until I get more information.

> QDrag
> -
> 
>  - Windows:
>* Fixed Drag and Drop driven by touch-synthesized mouse events.

Moved to [QtGui][QDrag] and added "on Windows".

> QTextDocument
> -
> 
>  - [QTBUG-6] Add support for empty inline elements in block tags.

"Added'

> QWidget
> ---
> 
>  - Windows:
>* [QTBUG-21371][QTBUG-4397] QWidget::restoreGeometry() now restores
>  maximized/full screen widgets to the correct screen.

Moved to [QtGui][QWidget].

>  - Important Behavior Changes:
>* Running Qt applications that are setuid has been prevented. If you
>  really need to do this then you can call
>  QCoreApplication::setSetuidAllowed(true) before creating the
>  QCoreApplication instance.

Moved to [Important Behavior Changes] (out of QtCore). Changed "has been 
prevented" to "is no longer allowed by default".

>  - JSON:
>* QJsonValue::fromVariant() will now convert single-precision Floats
>  into Doubles instead of Strings

Moved to [QtCore][QJsonValue]

> 
>  - Logging:
>* Allow qCDebug macros to be used in a printf style.

"It's now possible for the..."

>* Enable qCDebug's for all categories except qt one's

"All qCDebug categories are enabled by default, except for Qt's own 
categories"

>* Make Q_LOGGING_CATEGORY and Q_DECLARE_LOGGING_CATEGORY return a const
>  object.

Removed "make" (why are you telling the user to do that?) and made it "now 
return".

>  - Objective-C:
>* Added NSData/CDataRef converters for QByteArray

Moved to [QtCore][QByteArray]

>  - QHash:
>* Allowed QFont to be used as a key in QHash/QSet.

Dropped, since there's a nicer version in [QtGui][QFont].

>  - QHash/QSet:
>* Allowed to use float, double and long double as QHash/QSet keys.

"Added qHash overloads for float, double and long double"

>  - QJsonArray:
>* Added convenience methods to QJsonArray for appending QJsonValues
> 
>  - QJsonValue:
>* Added constructor to QJsonValue for const char *
> 
>  - QMargins:
>* Added missing addition and subtraction operators.
> 
>  - QPA/Android:
>* [QTBUG-36025] Fixed a memory leak in the clipboard

Moved to Android changes. Why was this in QtCore in the first place? QPA is a 
QtGui technology...

> QtDBus
> --
> 
>  - Important Behavior Changes:
>* QtDBus adaptors now include the PropertiesChanged signal in
>  introspection data

Removed the "important behaviour changes" heading, leaving it directly under 
[QtDBus].

> QtGui
> -
> 
>  - [QTBUG-35220] Support reading bmp images with alpha channel

"Reading bmp images with alpha channel is now supported"

>  - Accessibility on Linux reported all objects as being editable instead of
>just edi

[Development] Changelogs for 5.3.0

[Thiago Macieira]

Please find attached the raw logs for each of the modules that had any 
[ChangeLog] in the v5.2.1..origin/release range.

I'm taking responsibility of editing the one for qtbase.

For all other modules, I'd like someone to reply to this email saying they'll 
be the editor. Otherwise, there will be no changelog for the module at all, 
because I won't do it.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center

 GLES3 and desktop OpenGL are now fully supported with EGL
--

 - [QTBUG-37332] 

 Native (that is, not distance field based) text
rendering is now functional on OpenGL 3.2+ core profiles too.
--

 - [QTBUG-36993] 

 QFileSelector: the identifier for OS X has been changed back
to 'osx' from 'mac', and 'mac' and 'darwin' have now been added as
selectors for Darwin OS (which is the base of both OS X and iOS).
--

 - [QTBUG-35073] 

Android
---

 - [QTBUG-34781] Fixed regression in "make install" on library projects on
   Android so they can be used inside subdirs projects again.
 - [QTBUG-34650] Rework the raster and opengl implementation.
   [ChangeLog][Android] Create a single android platform plugin.
 - [QTBUG-36074] Fixed crash on populating large combo boxes or menus.
 - [QTBUG-36528] Fixed QDir::entryList() for assets scheme to no longer
   skip the first file in the directory.
 - [QTBUG-30652] Allow the developers to define a splash screen which will
   be visible until the first window is created.
 - [QTBUG-33704] Speed up first time directory listing in assets by using
   pregenerated entry list.
 - [QTBUG-36974] Fixed double click events
 - [QTBUG-37738] Fixed font merging problem which caused e.g. missing
   glyphs for Arabic numerals.

 - Fonts:
   * [QTBUG-36789] Fixed support for Arabic text.

CHANGELOG FIX
-

 - Remove the line about QByteArrayList being added.

Compiler Specific Changes
-

 - Variadic macros are now enabled more liberally for gcc, clang, icc. If
   you have warnings (because you e.g. compile with -pedantic), disable
   them by -Wno-variadic-macros.

General
---

 - Support for the following platforms has been removed, due to lack of
   interest in updating support: INTEGRITY, VxWorks, Solaris on UltraSPARC
   (with the Sun Studio compiler suite), AIX on POWER processors (with IBM
   Visual Age compiler suite).
 - Builtin command-line options such as -reverse,
   -session, -style etc. now all support double dash, e.g. --reverse,
   --session, --style...

Important Behavior Changes
--

 - [QTBUG-30440] Qt no longer checks for support for the Neon FPU on ARM
   platforms at runtime. Code optimized for Neon must be enabled
   unconditionally at compile time by ensuring the compiler supports Neon.
   You may need to edit your mkspec for that.
 - Qt now automatically generates code for processors supporting SSE2 on
   i386 platforms. To disable this, pass the -no-sse2 option during Qt
   configuration. Since this feature has been present on CPUs for 10 years
   and since Qt no longer checks for runtime support for SSE2, we strongly
   encourage users to leave the default setting on for best performance.
   - For Linux distributions that must retain support for CPUs without
   SSE2, we recommend doing two builds of Qt and installing the
   SSE2-enabled libraries in the LIBDIR/sse2 directory. Tools, plugins, and
   examples are not affected.
   - See discussion on the Qt development mailing list:
   http://lists.qt-project.org/pipermail/development/2013-November/014085.h
   tml
 - The default set of ciphers used by QSslSocket has been changed to
   exclude ciphers that are using key lengths smaller than 128 bits. These
   ciphers are still available and can be enabled by applications if
   required.
 - [QTBUG-20666] Support for DH and ECDH key exchange cipher suites when
   acting as an SSL server has been made possible. This change means the
   you can now implement servers that offer forward-secrecy using Qt.

OS X


 - [QTBUG-18980 (relates)][QTBUG-38246] Use CoreText text shaping engine
   for support of complex scripts. If required, the shaping engine used in
   previous versions can be preferred by configuring Qt with -no-harfbuzz.
   Alternatively, the QT_HARFBUZZ environment variable could be set to
   "old".

Platform Specific Changes
-

 - Linux:
   * Systems with systemd may now pass
 -journald to configure to send logging output to journald. Logging
 will still be sent to stderr for interactive applications (run from a
 tty) or with QT_NO_JOURNALD_LOG se

Re: [Development] Changelogs for Qt 5.1.x and 5.2

[Thiago Macieira]

On quinta-feira, 18 de julho de 2013 13.18.32, Richard Moore wrote:
> On 18 July 2013 01:34, Thiago Macieira  wrote:
> > On quarta-feira, 17 de julho de 2013 21.45.11, Giuseppe D'Angelo wrote:
> >> Can we devise something simpler? Can we also put in our policies an
> >> example of how a changelog file is structured, and what are the right
> >> tags to use to add an entry to a given section?
> > 
> > "Use the tags that appear in the changelog file"
> 
> They should be listed in the commit log template to make it easy for
> people to just copy them.

Good idea, that's easy to do.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Changelogs for Qt 5.1.x and 5.2

[Thiago Macieira]

On quarta-feira, 17 de julho de 2013 21.45.11, Giuseppe D'Angelo wrote:
> I 100% agree with having the changelog entry in the commit message,
> but I fear the complexity there. We should try to work towards
> error-proof entries -- I fear that too many people will mispell
> "Important Behavior Changes" or similar, causing frustation when the
> sanity bots complains.

I don't see that a problem. I can do a case-insensitive comparison when 
grouping and the changelog is meant to be proof-read by a human anyway. Also, 
don't forget we have a Rohanbot that is doing spellchecking.

> Can we devise something simpler? Can we also put in our policies an
> example of how a changelog file is structured, and what are the right
> tags to use to add an entry to a given section?

"Use the tags that appear in the changelog file"

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Changelogs for Qt 5.1.x and 5.2

[Thiago Macieira]

On terça-feira, 16 de julho de 2013 14.40.25, Mitch Curtis wrote:
> > No. It's intentionally different so it does not match those. It might be
> > more than one line, so it needs to be a full paragraph. If you use
> > colons, the gerrit hook to add the Change-Id will add it in the same
> > paragraph. We don't want that.
>
> What would a full, compliant commit message look like (without the
> [ChangeLog] notation)?


Remove fully-decoded QUrl user info and authority sections

Those sections contain more than one components of a URL, separated by
delimiters. For that reason, QUrl::FullyDecoded and QUrl::DecodedMode do
not make sense, since they would cause the returned value to be
ambiguous and/or fail to parse again.

In fact, there was a comment in the test saying "look how it becomes
ambiguous".

Those modes are already forbidden in the setters and getters of the full
URL (setUrl(), url(), toString() and toEncoded()).

[ChangeLog][Important Behavior Changes][QUrl and QUrlQuery] QUrl no
longer supports QUrl::FullyDecoded mode in authority() and userInfo(),
nor QUrl::DecodedMode in setAuthority() and setUserInfo().

Change-Id: I538f7981a9f5a09f07d3879d31ccf6f0c8bfd940


See:
https://codereview.qt-project.org/60266
https://codereview.qt-project.org/60425

--
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] Changelogs for Qt 5.1.x and 5.2

[Thiago Macieira]

On terça-feira, 16 de julho de 2013 10.44.22, Rutledge Shawn wrote:
> On 16 Jul 2013, at 12:22 PM, Thiago Macieira wrote:
> > 3) the format for the changelog is:
> >
> > a) auto-guess module from the paths changed
> > [ChangeLog] Here is my slightly verbose text explaining that I've done
> > something awesome and should tell people about it.
>
> Did you mean
> Change-log: blah blah
>
> to match the existing Change-Id:, Task-number:, etc.?

No. It's intentionally different so it does not match those. It might be more
than one line, so it needs to be a full paragraph. If you use colons, the
gerrit hook to add the Change-Id will add it in the same paragraph. We don't
want that.

--
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

[Development] Changelogs for Qt 5.1.x and 5.2

[Thiago Macieira]

Hello

At the Qt Contributor Summit, we're proposing the following:

1) commits with changes worthy of being mentioned in the release's ChangeLog 
will have a note in the *commit* *message*
  not in a Git note
  not in JIRA

2) however automated we make the changelog creation, it will still require a 
human to re-read the text and prettify. Hopefully, a native speaker.

3) the format for the changelog is:

a) auto-guess module from the paths changed
[ChangeLog] Here is my slightly verbose text explaining that I've done 
something awesome and should tell people about it.

b) explicit heading in the changelog:
[ChangeLog][Important Behavior Changes] Here I am telling you that I changed 
something in QUrl that you should be aware of, but is for the greater good.

[ChangeLog][QtCore][QUrl / QUrlQuery] Blah blah blah

I am volunteering to write a (Perl) script to read all commit messages in a 
release and produce an update to the changelog. The script will also extract 
the the Task-number from the commit (if there's any) and add to the text.

If there are no objections, I'll update the commit template in qtbase.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Alan Alpert]

On Tue, Mar 12, 2013 at 8:55 AM, Sergio Ahumada
 wrote:
> On 02/06/2013 07:25 PM, Olivier Goffart wrote:
>> On Thursday 31 January 2013 07:50:32 Koehne Kai wrote:
>>>> -Original Message-
>>>> From: development-bounces+kai.koehne=digia@qt-project.org
>>>> [mailto:development-bounces+kai.koehne=digia@qt-project.org] On
>>>> Behalf Of Matt Williams
>>>> Sent: Tuesday, January 29, 2013 11:14 AM
>>>> To: development
>>>> Subject: Re: [Development] ChangeLogs
>>>>
>>>> On 29 January 2013 00:31, Alan Alpert <4163654...@gmail.com> wrote:
>>>>> On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald
>>>>
>>>>  wrote:
>>>>>> 4. Let's try to make the job of our maintainers that little bit
>>>>>> easier by writing good commit summaries and diligently reviewing the
>>>>>> commit summaries of our peers.
>>>>>
>>>>> +1, but I think the tool is a more realistic way of making the task
>>>>> easier for the maintainers.
>>>>
>>>> Within KDE we use a tool called Enzyme (http://enzyme-project.org/) which
>>>> allows you to go through all the commits, marking certain ones as
>>>> interesting in a collaborative way. It might not have _all_ the feature
>>>> needed but it would probably help along the way. It's open-source so we
>>>> could always tweak it as needed.
>>>
>>> I'm all for a tool making things easier for the one writing the actual
>>> ChangeLog file. But I think it's somewhat orthogonal to the question
>>> whether the original author of a fix should write a ChangeLog line
>>> somewhere, too .
>>>
>>> So, did we come to any conclusion regarding adding a "ChangeLog: " entry to
>>> commits? IMO it's worth a try.
>>
>> I'd say yes,
>> Put a "Changelog:" entry somewhere with some text that will be processed
>> manually by the release manager to fill the changelog.
>>
>> (The release manager can grep for it, and that will ease his task a lot to
>> have already ready made sentence)
>>
>> [ The ones who are concerned about a bit of reddundancy in the commit message
>> should as well leave the commit empty since it is already redundent with the
>> diff itself :-) ]
>>
>
> Hi,
>
> Since it doesn't seem to be a final decision/consensus about this, I
> will just create empty changes files for 5.0.2 and Maintainers will have
> to fill them up.
>
> ps1: any idea about the "git merge-driver" suggestion and/or the (qml
> based?) UI tool suggestion ?

I did start prototyping a (QML based) tool to help. I've just gotten
it working on the qtdeclarative repo, and pushed it to
https://gitorious.org/aalperts-automatons/clam (I'd put it in a
qt-project repo but I don't know where it belongs - and
aalperts-automatons has no quality requirements ;) ).

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

Re: [Development] ChangeLogs

[Sergio Ahumada]

On 02/06/2013 07:25 PM, Olivier Goffart wrote:
> On Thursday 31 January 2013 07:50:32 Koehne Kai wrote:
>>> -Original Message-
>>> From: development-bounces+kai.koehne=digia@qt-project.org
>>> [mailto:development-bounces+kai.koehne=digia@qt-project.org] On
>>> Behalf Of Matt Williams
>>> Sent: Tuesday, January 29, 2013 11:14 AM
>>> To: development
>>> Subject: Re: [Development] ChangeLogs
>>>
>>> On 29 January 2013 00:31, Alan Alpert <4163654...@gmail.com> wrote:
>>>> On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald
>>>
>>>  wrote:
>>>>> 4. Let's try to make the job of our maintainers that little bit
>>>>> easier by writing good commit summaries and diligently reviewing the
>>>>> commit summaries of our peers.
>>>>
>>>> +1, but I think the tool is a more realistic way of making the task
>>>> easier for the maintainers.
>>>
>>> Within KDE we use a tool called Enzyme (http://enzyme-project.org/) which
>>> allows you to go through all the commits, marking certain ones as
>>> interesting in a collaborative way. It might not have _all_ the feature
>>> needed but it would probably help along the way. It's open-source so we
>>> could always tweak it as needed.
>>
>> I'm all for a tool making things easier for the one writing the actual
>> ChangeLog file. But I think it's somewhat orthogonal to the question
>> whether the original author of a fix should write a ChangeLog line
>> somewhere, too .
>>
>> So, did we come to any conclusion regarding adding a "ChangeLog: " entry to
>> commits? IMO it's worth a try.
>
> I'd say yes,
> Put a "Changelog:" entry somewhere with some text that will be processed
> manually by the release manager to fill the changelog.
>
> (The release manager can grep for it, and that will ease his task a lot to
> have already ready made sentence)
>
> [ The ones who are concerned about a bit of reddundancy in the commit message
> should as well leave the commit empty since it is already redundent with the
> diff itself :-) ]
>

Hi,

Since it doesn't seem to be a final decision/consensus about this, I 
will just create empty changes files for 5.0.2 and Maintainers will have 
to fill them up.

ps1: any idea about the "git merge-driver" suggestion and/or the (qml 
based?) UI tool suggestion ?
ps2: I only found https://codereview.qt-project.org/47802 using the 
ChangeLog entry

Cheers,
-- 
Sergio Ahumada
Release Engineer - Digia, Qt
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Olivier Goffart]

On Thursday 31 January 2013 07:50:32 Koehne Kai wrote:
> > -Original Message-
> > From: development-bounces+kai.koehne=digia@qt-project.org
> > [mailto:development-bounces+kai.koehne=digia@qt-project.org] On
> > Behalf Of Matt Williams
> > Sent: Tuesday, January 29, 2013 11:14 AM
> > To: development
> > Subject: Re: [Development] ChangeLogs
> > 
> > On 29 January 2013 00:31, Alan Alpert <4163654...@gmail.com> wrote:
> > > On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald
> > 
> >  wrote:
> > >> 4. Let's try to make the job of our maintainers that little bit
> > >> easier by writing good commit summaries and diligently reviewing the
> > >> commit summaries of our peers.
> > > 
> > > +1, but I think the tool is a more realistic way of making the task
> > > easier for the maintainers.
> > 
> > Within KDE we use a tool called Enzyme (http://enzyme-project.org/) which
> > allows you to go through all the commits, marking certain ones as
> > interesting in a collaborative way. It might not have _all_ the feature
> > needed but it would probably help along the way. It's open-source so we
> > could always tweak it as needed.
> 
> I'm all for a tool making things easier for the one writing the actual
> ChangeLog file. But I think it's somewhat orthogonal to the question
> whether the original author of a fix should write a ChangeLog line
> somewhere, too .
> 
> So, did we come to any conclusion regarding adding a "ChangeLog: " entry to
> commits? IMO it's worth a try.

I'd say yes, 
Put a "Changelog:" entry somewhere with some text that will be processed 
manually by the release manager to fill the changelog.

(The release manager can grep for it, and that will ease his task a lot to 
have already ready made sentence)

[ The ones who are concerned about a bit of reddundancy in the commit message 
should as well leave the commit empty since it is already redundent with the 
diff itself :-) ]

-- 
Olivier

Woboq - Qt services and support - http://woboq.com

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

Re: [Development] ChangeLogs

[Koehne Kai]

> -Original Message-
> From: development-bounces+kai.koehne=digia@qt-project.org
> [mailto:development-bounces+kai.koehne=digia@qt-project.org] On
> Behalf Of Matt Williams
> Sent: Tuesday, January 29, 2013 11:14 AM
> To: development
> Subject: Re: [Development] ChangeLogs
> 
> On 29 January 2013 00:31, Alan Alpert <4163654...@gmail.com> wrote:
> > On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald
>  wrote:
> >> 4. Let's try to make the job of our maintainers that little bit
> >> easier by writing good commit summaries and diligently reviewing the
> >> commit summaries of our peers.
> >
> > +1, but I think the tool is a more realistic way of making the task
> > easier for the maintainers.
> 
> Within KDE we use a tool called Enzyme (http://enzyme-project.org/) which
> allows you to go through all the commits, marking certain ones as interesting
> in a collaborative way. It might not have _all_ the feature needed but it
> would probably help along the way. It's open-source so we could always
> tweak it as needed.

I'm all for a tool making things easier for the one writing the actual 
ChangeLog file. But I think it's somewhat orthogonal to the question whether 
the original author of a fix should write a ChangeLog line somewhere, too .

So, did we come to any conclusion regarding adding a "ChangeLog: " entry to 
commits? IMO it's worth a try.

Regards

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

Re: [Development] ChangeLogs

[Matt Williams]

On 29 January 2013 00:31, Alan Alpert <4163654...@gmail.com> wrote:
> On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald  wrote:
>> 4. Let's try to make the job of our maintainers that little bit easier
>> by writing good commit summaries and diligently reviewing the commit
>> summaries of our peers.
>
> +1, but I think the tool is a more realistic way of making the task
> easier for the maintainers.

Within KDE we use a tool called Enzyme (http://enzyme-project.org/)
which allows you to go through all the commits, marking certain ones
as interesting in a collaborative way. It might not have _all_ the
feature needed but it would probably help along the way. It's
open-source so we could always tweak it as needed.

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

Re: [Development] ChangeLogs

[Thiago Macieira]

On terça-feira, 29 de janeiro de 2013 08.10.17, Knoll Lars wrote:
> It had a checkbox, so you could mark a particular change as processed, and
> it would store this locally. This allowed you to do the work in chunks and
> you would at least always know what you've already processed. IIRC, you
> could also limit the change sets you were interested in to a certain
> directory/set of files.

Actually, no. It uploaded your changes to an FTP server.

There was also a hidden release manager mode, which caused it to list the
directory in the FTP server and download everyone's files. That way, the
release manager got a listing of all the changes that had been checked by
everyone and what was left. That's how the release manager knew who to nag to
write their changelogs.

This is brought to you from the secret society of release management. In the
next installment, Jason will tell you about a tool called jollybumper. :-)

--
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Knoll Lars]

On Jan 29, 2013, at 1:31 AM, Alan Alpert <4163654...@gmail.com> wrote:

> On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald  wrote:
>> On Fri, Jan 18, 2013 at 1:05 AM, Oswald Buddenhagen
>>  wrote:
>>> as some certainly noted, the completeness of dist/changes-* severely
>>> deteriorated over the last few minor releases, and in particular 5.0.0
>>> is one of the poorest qt changelogs seen in a while.
>>> 
>>> also, sergio is now attempting to make 5.0.1 changelogs in a heroic
>>> one-man-effort - not entirely surprisingly, this turns out to be a tad
>>> more tedious than planned.
>> 
>> I was quietly wondering to myself how long it would take for someone
>> to notice that I stopped acting as editor for the changelogs when I
>> left Nokia.
>> 
>> As Sergio has no doubt discovered, manually generating the changes
>> file is a tedious and time-consuming process, particularly when the
>> level of co-operation from developers is low to non-existent.
>> 
>> [...]
>> 
>> So, based on my bitter experience, here are my recommendations:
>> 
>> 1. Let's acknowledge that writing the changes file is going to have to
>> be a manual process due to the complexity of the decision-making and
>> the lack of a strict development process.
> 
> Yes, it will have to be an ultimately manual process. But I like how
> your later suggestions provide hope that tools and processes can make
> the manual part easier.

Agree. I can't really see a way to automate this neither.
> 
>> 2. Let's agree that module maintainers should be responsible for their
>> module's changes file, and clearly document that responsibility on the
>> part of the wiki that lists a maintainer's duties.
> 
> +1. Release manager would still be responsible for chasing them up though ;) .
> 
>> 3. Let's call for volunteers to prototype a new changelog tool along
>> similar lines to the old one, but this time with a better UI, the
>> ability to share data between users via a git repo, and some kind of
>> checklist to assist the decision-making process.  I'm happy to help
>> with setting requirements, but I regret that I won't be able to do
>> much more than that as my new full-time job does not involve Qt.
> 
> I'd start playing around with a QML prototype (nothing I love better
> ;) ) but requirements like "better UI" are too vague to even get
> started. Especially since I can't recall what the old Trolltech tool
> looked like. Could you flesh out initial ideas a little more, so
> potential volunteers could prototype their prototype?

The old Trolltech tool was nothing more then a list view showing all the 
perforce changes between two revisions. Clicking on a change set would show you 
the detailed description and diff in a view on the right (a bit like gitk).

It had a checkbox, so you could mark a particular change as processed, and it 
would store this locally. This allowed you to do the work in chunks and you 
would at least always know what you've already processed. IIRC, you could also 
limit the change sets you were interested in to a certain directory/set of 
files.
> 
>> 4. Let's try to make the job of our maintainers that little bit easier
>> by writing good commit summaries and diligently reviewing the commit
>> summaries of our peers.
> 
> +1, but I think the tool is a more realistic way of making the task
> easier for the maintainers.

Yes, I remember that the Trolltech tool, simple as it was, was a tremendous 
help.

Cheers,
Lars

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

Re: [Development] ChangeLogs

[Alan Alpert]

On Mon, Jan 28, 2013 at 4:21 AM, Jason McDonald  wrote:
> On Fri, Jan 18, 2013 at 1:05 AM, Oswald Buddenhagen
>  wrote:
>> as some certainly noted, the completeness of dist/changes-* severely
>> deteriorated over the last few minor releases, and in particular 5.0.0
>> is one of the poorest qt changelogs seen in a while.
>>
>> also, sergio is now attempting to make 5.0.1 changelogs in a heroic
>> one-man-effort - not entirely surprisingly, this turns out to be a tad
>> more tedious than planned.
>
> I was quietly wondering to myself how long it would take for someone
> to notice that I stopped acting as editor for the changelogs when I
> left Nokia.
>
> As Sergio has no doubt discovered, manually generating the changes
> file is a tedious and time-consuming process, particularly when the
> level of co-operation from developers is low to non-existent.
>
> [...]
>
> So, based on my bitter experience, here are my recommendations:
>
> 1. Let's acknowledge that writing the changes file is going to have to
> be a manual process due to the complexity of the decision-making and
> the lack of a strict development process.

Yes, it will have to be an ultimately manual process. But I like how
your later suggestions provide hope that tools and processes can make
the manual part easier.

> 2. Let's agree that module maintainers should be responsible for their
> module's changes file, and clearly document that responsibility on the
> part of the wiki that lists a maintainer's duties.

+1. Release manager would still be responsible for chasing them up though ;) .

> 3. Let's call for volunteers to prototype a new changelog tool along
> similar lines to the old one, but this time with a better UI, the
> ability to share data between users via a git repo, and some kind of
> checklist to assist the decision-making process.  I'm happy to help
> with setting requirements, but I regret that I won't be able to do
> much more than that as my new full-time job does not involve Qt.

I'd start playing around with a QML prototype (nothing I love better
;) ) but requirements like "better UI" are too vague to even get
started. Especially since I can't recall what the old Trolltech tool
looked like. Could you flesh out initial ideas a little more, so
potential volunteers could prototype their prototype?

> 4. Let's try to make the job of our maintainers that little bit easier
> by writing good commit summaries and diligently reviewing the commit
> summaries of our peers.

+1, but I think the tool is a more realistic way of making the task
easier for the maintainers.

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

Re: [Development] ChangeLogs

[Jason McDonald]

On Fri, Jan 18, 2013 at 1:05 AM, Oswald Buddenhagen
 wrote:
> as some certainly noted, the completeness of dist/changes-* severely
> deteriorated over the last few minor releases, and in particular 5.0.0
> is one of the poorest qt changelogs seen in a while.
>
> also, sergio is now attempting to make 5.0.1 changelogs in a heroic
> one-man-effort - not entirely surprisingly, this turns out to be a tad
> more tedious than planned.

I was quietly wondering to myself how long it would take for someone
to notice that I stopped acting as editor for the changelogs when I
left Nokia.

As Sergio has no doubt discovered, manually generating the changes
file is a tedious and time-consuming process, particularly when the
level of co-operation from developers is low to non-existent.

Back in the Trolltech and Nokia days, I made a few (largely
unsuccessful) attempts to get people to describe their important
changes in the changes-file, but mostly I only succeeded in getting
myself flamed (and maybe this email will have the same effect), to the
point where one senior developer tried to wash his hands of this
particular duty by stating on an open mailing list that "the release
branch is the Release Manager's hostile fork of Qt for which the
developers have no responsibility".  While that gave the folks in Qt's
former QA team a good laugh, I would hope that attitudes have shifted
a little since then.

During my tenure as Qt's Release Manager, I came to the following
conclusions about the changes file:
(a) There is no feasible way to automatically produce a high-quality
changes file,
(b) The changes file is an important resource for Qt users,
(c) Jira is not an acceptable substitute for the changes file, and
(d) The git commit history is not an acceptable substitute for the changes file.

Therefore, I basically gave up chasing developers to update the
changes file and did it myself by examining both the bugtracker's list
of closed tasks for the release and the git log, making decisions
about what items were worthy of a mention in the changes file, what
kind of change they were (feature, fix, doc, approved BC/SC break,
etc) and trying to turn the task and commit descriptions into a brief,
high-level, human-readable description of what changed.  This could
take anything from one to five days work for each release depending on
how many commits were in the release.  The quality of the changes file
for each release was largely a factor of whether I could actually
spare the time to do it properly in addition to all the other things a
release manager has to do.

In my opinion, as Qt's most experienced past release manager, this
should have gotten a lot better with modularization, as the ultimate
responsibility for documenting the important changes for each module
is now very clear -- it belongs to the module maintainer.

Now, let me explain my reasons for the conclusions above:

(a) The changes file can't be automatically generated, partly because
the Qt Project's development processes are too flexible (i.e.
inconsistent, poorly-defined and, in some cases, highly resistant to
change) and partly because writing the changelog is a complex
decision-making process for which suitable AI will probably not exist
within our lifetimes.  You need to decide what's important to
end-users and what's not. You need to filter out stuff that user's
never saw in an official release (i.e. stuff that was broken and fixed
again between releases, bugs fixed before a new feature was first
released, fixes that got reverted, patches that were effectively empty
because of later changes and/or resolution of merge conflicts). You
need to figure out when multiple commits equal one fix from the user's
viewpoint.  You need to figure out when one commit equals multiple
fixes from the user's viewpoint.  You need to filter out duplicate
bug-tracker tasks.  You need to filter out changes to code that was
later completely removed or rewritten.  You need to figure out where
in the changes file a particular change belongs.  You need to turn one
or more commit descriptions into a user-understandable description.
Sometimes you even need to read diffs to figure out what really
changed.

That said, I believe that it is possible to create a tool to
assist/manage the process of manually writing the changes file.  The
old changelog tool we had in Trolltech basically showed you a list of
the commits in a release and allowed you to tick off the ones you had
already dealt with, so that you knew which ones you still had to make
decisions about.  Unfortunately, the tool was written for the
source-control system we used before moving to git and fell into
disuse thereafter because writing the changes file became less the
developers' problem and more my problem.

(b) End users do care about the changes file. I know this because I
always received emails and IRC messages each time Nokia's web team
forgot to post the changes file on the web when a new release went
out.  The changes fil

Re: [Development] ChangeLogs

[Oswald Buddenhagen]

On Tue, Jan 22, 2013 at 02:18:46PM +0100, Tor Arne Vestbø wrote:
> But isn't the merging done by the CI using regular Git by cherry-picking 
> 
the merging is done by gerrit itself, as you can (more or less) see when
you hit the stage button.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Tor Arne Vestbø]

On 1/21/13 17:14 , Thiago Macieira wrote:
> On segunda-feira, 21 de janeiro de 2013 17.02.10, Tor Arne Vestbø wrote:
>> On 1/21/13 16:37 , Giuseppe D'Angelo wrote:
>>> On 21 January 2013 15:08, Tor Arne Vestbø 
> wrote:
 If you're writing the ChangeLog entry at commit time, not right before
 the release, why can't your patch contain a change to dist/changelog
 from the get-go which, can be reviewed and integrated along with the
 code change?
>>>
>>> Because that usually causes silly conflicts when staging (=>merging)
>>> the patch. :(
>>
>> That can be solved by a git merge-driver for the changelog format.
>
> Note: the merging is done by Gerrit.

Hmm, and it doesn't support merge-drivers as far as I can tell :(

But isn't the merging done by the CI using regular Git by cherry-picking 
into the staging branch, and then integration is a fast-forward?

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

Re: [Development] ChangeLogs

[Thiago Macieira]

On segunda-feira, 21 de janeiro de 2013 17.02.10, Tor Arne Vestbø wrote:
> On 1/21/13 16:37 , Giuseppe D'Angelo wrote:
> > On 21 January 2013 15:08, Tor Arne Vestbø 
wrote:
> >> If you're writing the ChangeLog entry at commit time, not right before
> >> the release, why can't your patch contain a change to dist/changelog
> >> from the get-go which, can be reviewed and integrated along with the
> >> code change?
> >
> > Because that usually causes silly conflicts when staging (=>merging)
> > the patch. :(
>
> That can be solved by a git merge-driver for the changelog format.

Note: the merging is done by Gerrit.
--
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Tor Arne Vestbø]

On 1/21/13 16:37 , Giuseppe D'Angelo wrote:
> On 21 January 2013 15:08, Tor Arne Vestbø  wrote:
>> If you're writing the ChangeLog entry at commit time, not right before
>> the release, why can't your patch contain a change to dist/changelog
>> from the get-go which, can be reviewed and integrated along with the
>> code change?
>
> Because that usually causes silly conflicts when staging (=>merging)
> the patch. :(

That can be solved by a git merge-driver for the changelog format.

tor arne

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

Re: [Development] ChangeLogs

[Giuseppe D'Angelo]

On 21 January 2013 15:08, Tor Arne Vestbø  wrote:
> If you're writing the ChangeLog entry at commit time, not right before
> the release, why can't your patch contain a change to dist/changelog
> from the get-go which, can be reviewed and integrated along with the
> code change?

Because that usually causes silly conflicts when staging (=>merging)
the patch. :(

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

Re: [Development] ChangeLogs

[Tor Arne Vestbø]

If you're writing the ChangeLog entry at commit time, not right before 
the release, why can't your patch contain a change to dist/changelog 
from the get-go which, can be reviewed and integrated along with the 
code change?

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

Re: [Development] ChangeLogs

[Oswald Buddenhagen]

On Fri, Jan 18, 2013 at 09:38:05PM +0800, Thiago Macieira wrote:
> On sexta-feira, 18 de janeiro de 2013 14.03.18, Oswald Buddenhagen wrote:
> > what is much more important is that the ChangeLog entries need to be
> > "tagged", so they can be automatically sorted into the right categories:
> > 
> > ChangeLog: Core: SIC: renamed brokenName() to usefulName()
> > 
> 
> You raise another good point: how are we going to sort the changelog entries? 
> We don't have the class name, module name or the major section of the file 
> (Important behaviour changes, etc.)
> 
i think we need a manually maintained set of valid tags, and have the
sanity bot complain about incorrect tagging. the correct set of tags can
be deduced from the structure of existing changelogs (assuming we
consider it sane).
when this is done right and used consistently, the actual generation of
the prototypical changelog can be fully automated. 
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Thiago Macieira]

On sexta-feira, 18 de janeiro de 2013 14.03.18, Oswald Buddenhagen wrote:
> what is much more important is that the ChangeLog entries need to be
> "tagged", so they can be automatically sorted into the right categories:
> 
> ChangeLog: Core: SIC: renamed brokenName() to usefulName()
> 
> i.e., what many people do with commit message summaries (which i find
> just plain annoying, because it adds noise and doesn't really solve the
> problem it supposedly tries to address (the one we are discussing now)).

You raise another good point: how are we going to sort the changelog entries? 
We don't have the class name, module name or the major section of the file 
(Important behaviour changes, etc.)

Is this going to be a manual process?
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Thiago Macieira]

On sexta-feira, 18 de janeiro de 2013 13.57.02, Sylvain Pointeau wrote:
> > And that leads to another downside: what if two or more commits were
> > necessary
> > to fix a bug? Then the ChangeLog line would be referring to changes that
> > are
> > not found in that commit, which could be confusing later on.
> 
>  And additionally what if you solve multiple bugs in one commit?
> 
> Normally you should indicate which bugs you are trying to solve with a
> commit
> And a reviewer should close the bug in the bug tracker.
> 
> Then the right way is to use the bug tracking tool to generate a change log.

If they are part of one single change, then it's likely we can word the 
changelog such that it explains both bug fixes.

If they are not part of the same change, then you should split in two commits 
anyway.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Oswald Buddenhagen]

On Fri, Jan 18, 2013 at 07:49:41PM +0800, Thiago Macieira wrote:
> On sexta-feira, 18 de janeiro de 2013 11.49.12, Oswald Buddenhagen wrote:
> > yes, and the purist in me agrees. but as both kai and eskil pointed out,
> > this isn't so much additional clutter, so whatever - i kind of don't
> > see the change-id lines when i browse logs anyway.
> 
> The Change-Id is not redundant information. It's new information, not present 
> elsewhere.
> 
that wasn't the point. for the human reader, the change-id is noise most
of the time. still, it's necessary for the system. the same could be
said about the new footer, in a slightly different way.

> > an additional upside of doing this while creating the commit is that one
> > may be more thorough with the message and the whole commit, as one is
> > forced to consider it from an additional angle. so it plays in the same
> > league as "needlessly" insisting on commit atomicity and other "process
> > stuff".
> 
> And that leads to another downside: what if two or more commits were 
> necessary 
> to fix a bug? Then the ChangeLog line would be referring to changes that are 
> not found in that commit, which could be confusing later on.
> 
the actual, final bug fix should be in the last commit. if multiple
"terminal" commits refer to the same bug, i'd venture the assertion that
something is wrong with the definition of the bug (atomicity). and if the
same type of bug is fixed in multiple places, the placement of the
changelog footer is arbitrary (provided no reference to the specific
function is deemed necessary. otherwise the lines need duplication, and
can be manually merged at log generation time (the automatic log
extractor can be made clever enough to pre-group similar entries to ease
this)).

> I don't buy the "be more thorough" argument. If the commit message was 
> written 
> properly, the ChangeLog line is redundant because it's rephrasing what has 
> already been said before, except that it's less detailed and is written in 
> the 
> past tense (as opposed to the imperative that most people seem to prefer).
> 
the point is that the commit message is often *not* written properly,
because people have a too focused mindset at the time of writing (or are
just too lazy, but that's another topic ;). bringing in the additional
aspect to consider is exactly what may help addressing this problem to
some degree.
and yes, i know that *your* commit messages are (usually) already as
perfect as it gets. but let's face it: you are the exception.

> If we're going to do this, then let's agree that it must always be the 
> *second* paragraph of the commit message -- that is, the first paragraph of 
> the 
> body -- and it must go with the flow.
> 
i'd already add an exception to that: if the description is a
grammatical continuation of the summary, shift one down:


don't do foobar when bazbaking terzknolfs and some other stuff

... because otherwise frudings will crash in yHa().

ChangeLog: oh, well

you know, things happen ...


the point is that it gets arbitrarily complex, and adding more rules
won't help. of course we can endorse a particular style to reduce
redundancy, but it's technically not necessary and can be left to the
discretion of the contributor (and his reviewers).

what is much more important is that the ChangeLog entries need to be
"tagged", so they can be automatically sorted into the right categories:

ChangeLog: Core: SIC: renamed brokenName() to usefulName()

i.e., what many people do with commit message summaries (which i find
just plain annoying, because it adds noise and doesn't really solve the
problem it supposedly tries to address (the one we are discussing now)).

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

Re: [Development] ChangeLogs

[Sylvain Pointeau]

>
>
>
> And that leads to another downside: what if two or more commits were
> necessary
> to fix a bug? Then the ChangeLog line would be referring to changes that
> are
> not found in that commit, which could be confusing later on.
>
>
 And additionally what if you solve multiple bugs in one commit?

Normally you should indicate which bugs you are trying to solve with a
commit
And a reviewer should close the bug in the bug tracker.

Then the right way is to use the bug tracking tool to generate a change log.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Thiago Macieira]

On sexta-feira, 18 de janeiro de 2013 11.49.12, Oswald Buddenhagen wrote:
> yes, and the purist in me agrees. but as both kai and eskil pointed out,
> this isn't so much additional clutter, so whatever - i kind of don't
> see the change-id lines when i browse logs anyway.

The Change-Id is not redundant information. It's new information, not present 
elsewhere.

> an additional upside of doing this while creating the commit is that one
> may be more thorough with the message and the whole commit, as one is
> forced to consider it from an additional angle. so it plays in the same
> league as "needlessly" insisting on commit atomicity and other "process
> stuff".

And that leads to another downside: what if two or more commits were necessary 
to fix a bug? Then the ChangeLog line would be referring to changes that are 
not found in that commit, which could be confusing later on.

I don't buy the "be more thorough" argument. If the commit message was written 
properly, the ChangeLog line is redundant because it's rephrasing what has 
already been said before, except that it's less detailed and is written in the 
past tense (as opposed to the imperative that most people seem to prefer).

If we're going to do this, then let's agree that it must always be the 
*second* paragraph of the commit message -- that is, the first paragraph of the 
body -- and it must go with the flow.

I'd rewrite my commit message to be:


Clear the current thread data for the main thread

ChangeLog: Fixed a crash that would cause the QObject constructor to crash if 
it was run during application shut down (that is, in global destructors).

A common case of QObjects being created on shutdown are qDebug or qWarning 
calls in destructors (due to QTextStream's device close notification QObject).

==41000== Invalid read of size 4
==41000==at 0x5F01ED5: bool QBasicAtomicOps<4>::ref(int&) 
(qatomic_x86.h:208)
==41000==by 0x5F01309: QBasicAtomicInteger::ref() 
(qbasicatomic.h:147)
==41000==by 0x5F24051: QThreadData::ref() (qthread.cpp:100)
==41000==by 0x614A984: QObject::QObject(QObject*) (qobject.cpp:681)
==41000==by 0x605E562: QDeviceClosedNotifier::QDeviceClosedNotifier() 
(qtextstream.cpp:324)
==41000==by 0x6057E90: 
QTextStreamPrivate::QTextStreamPrivate(QTextStream*) (qtextstream.cpp:441)
==41000==by 0x605935D: QTextStream::QTextStream(QString*, 
QFlags) (qtextstream.cpp:1059)
==41000==by 0x5F19B4B: QDebug::Stream::Stream(QtMsgType) (in 
/home/thiago/obj/qt/qt5/qtbase/lib/libQt5Core.so.5.0.1)
==41000==  Address 0x6ee73f0 is 0 bytes inside a block of size 152 free'd
==41000==at 0x4A0736C: operator delete(void*) (vg_replace_malloc.c:480)
==41000==by 0x5F240BF: QThreadData::deref() (qthread.cpp:109)
==41000==by 0x6113F6B: QCoreApplicationData::~QCoreApplicationData() 
(qcoreapplication.cpp:268)

Change-Id: I0dba895b041fe6cf81e6f8939ca85035cd00aad1
===

Note how the change log line is a relevant part of the explanation of the 
problem, and is followed by more detail that doesn't need to be part of the 
changelog.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Oswald Buddenhagen]

On Thu, Jan 17, 2013 at 11:48:50PM +0800, Thiago Macieira wrote:
> On quinta-feira, 17 de janeiro de 2013 16.05.40, Oswald Buddenhagen wrote:
> > 5.0.0 is one of the poorest qt changelogs seen in a while.
> 
> Qt 5.0.0 is also one of the most major releases seen in a while -- 7.5
> years to be precise. The major release deserves special treatment: we
> agreed on listing what was important for the porting effort.
> 
that's for the "source incompatible changes" section.
but the "mostly source compatible" also implies that in many aspects it
is just like a regular minor version, so the "screw the changelog,
everything is totally different now anyway" mentality applied to
previous major versions just doesn't seem appropriate.

On Fri, Jan 18, 2013 at 05:23:24PM +0800, Thiago Macieira wrote:
> ChangeLog: Fixed a crash that would cause the QObject constructor to crash if 
> it was run during application shut down (that is, in global destructors).
> 
> Change-Id: I0dba895b041fe6cf81e6f8939ca85035cd00aad1
> ===
> 
> Note how it's repeating information that was already present in the commit 
> message (it's redundant), just in a different way. Also note how the change 
> log 
> is not a line, but a longer sentence.
>
yes, and the purist in me agrees. but as both kai and eskil pointed out,
this isn't so much *additional* clutter, so whatever - i kind of don't
see the change-id lines when i browse logs anyway.

an additional upside of doing this while creating the commit is that one
may be more thorough with the message and the whole commit, as one is
forced to consider it from an additional angle. so it plays in the same
league as "needlessly" insisting on commit atomicity and other "process
stuff".
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Thiago Macieira]

On sexta-feira, 18 de janeiro de 2013 09.54.37, Eskil Abrahamsen Blomfeldt 
wrote:
> Having it as part of the commit message seems a lot less complex to me, 
> and I don't think it would do any harm to an extra line of 
> meta-information in the bottom section with the change-id and 
> task-number where there's already lots of clutter.

It's not always just one line. We're talking about a paragraph.

Here's what a commit message would look like, if I had used that for the 
commit I've just pushed:

===
Clear the current thread data for the main thread

This avoids crashes accessing deleted memory when creating a QObject
after the last QObject had been deleted, like a qDebug() in global
destructors.

==41000== Invalid read of size 4
==41000==at 0x5F01ED5: bool QBasicAtomicOps<4>::ref(int&) 
(qatomic_x86.h:208)
==41000==by 0x5F01309: QBasicAtomicInteger::ref() 
(qbasicatomic.h:147)
==41000==by 0x5F24051: QThreadData::ref() (qthread.cpp:100)
==41000==by 0x614A984: QObject::QObject(QObject*) (qobject.cpp:681)
==41000==  Address 0x6ee73f0 is 0 bytes inside a block of size 152 free'd
==41000==at 0x4A0736C: operator delete(void*) (vg_replace_malloc.c:480)
==41000==by 0x5F240BF: QThreadData::deref() (qthread.cpp:109)
==41000==by 0x6113F6B: QCoreApplicationData::~QCoreApplicationData() 
(qcoreapplication.cpp:268)

ChangeLog: Fixed a crash that would cause the QObject constructor to crash if 
it was run during application shut down (that is, in global destructors).

Change-Id: I0dba895b041fe6cf81e6f8939ca85035cd00aad1
===

Note how it's repeating information that was already present in the commit 
message (it's redundant), just in a different way. Also note how the change log 
is not a line, but a longer sentence.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Jedrzej Nowacki]

On Thursday 17. January 2013 18.25.29 Oswald Buddenhagen wrote:
> On Thu, Jan 17, 2013 at 04:05:40PM +0100, Oswald Buddenhagen wrote:
> > two more approaches have been previously proposed:
> hjk suggested yet another approach: use gerrit itself to collect the
> changelog entries. after some thinking, i came up with this process:
> - add a ChangeLog: line to the commit message as in the previous
>   proposal
> - the commit-msg hook extracts and removes that line; the post-commit
>   hook re-adds that line via git-notes
> - change is pushed as usual - with git-gpush (which gets extended to
>   push the notes as well)
> - gerrit receives the commit and notes, creates a change, and attaches
>   the changelog entry as an additional attribute to it
> - up to now, everything was an optional extension - to save the
>   contributor opening the gerrit page to add a changelog entry
> - but of course, it would be possible to edit the changelog entry in the
>   gui
> - the changelog entry would be approved together with the actual change.
>   whether this would happen in a separate review category, with the
>   stage/submit button, or something yet different, i don't know.
> - the system would require explicit action to approve the lack of a
>   changelog entry
> - for final storage, changelogs would be probably re-added as git
>   notes again
> - automated entry collection at release time would follow as with
>   in-commit-message ChangeLog: entries
> 
> the advantages of the system:
> - there is no "media break" like with a wiki or jira, as we use git and
>   gerrit anyway
> - the commit messages themselves are not "polluted"
> - the changelog entries can be modified without amending and re-pushing
>   the commit, thus not invalidating the actual review
> - it would be also possible to let the reviewers write the changelog
>   entry (which would then have to be approved by the contributor or
>   another reviewer in turn)
> - we could seamlessly switch from the in-commit-message ChangeLog:
>   variant, as nothing would change in the manual steps at commit
>   creation time (provided the notes-for-submission stuff would be
>   implemented right away)
> the downside is rather obvious:
> - this needs to be implemented in gerrit (unless somebody already did
>   something similar)
> 
> this is just a "step 2". it is in so far relevant, as the possibility of
> adding this later may be considered an endorsement for the original
> ChangeLog: variant.
> ___
> Development mailing list
> Development@qt-project.org
> http://lists.qt-project.org/mailman/listinfo/development

I like the approach, I'm just afraid that nobody will work on patching gerrit. 
It means that in real live we will end-up with the original ChangeLog variant. 
It seems that it is the best solution anyway. 

Cheers,
  Jędrek
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Eskil Abrahamsen Blomfeldt]

On 01/17/2013 04:05 PM, Oswald Buddenhagen wrote:
> we introduce a new footer ("ChangeLog:") to commit messages. this would
> shift the burden to the contributor, and it could be properly reviewed.
> the generation the logs could be fully automated, and only minimal
> redactional work would be necessary.
> a (somewhat minor) downside would be some redundancy in the commit
> messages.
> don't suggest to change the style of the commit summaries to be
> ready-made changelog entries - this would be neither without
> disadvantages (different target audience), nor would it fully solve the
> problem (selection of commits for the changelog).
>
> an alternative would be auto-generating the changelog from jira tasks.
> consequently, if you consider something important enough for a changelog
> entry, you need to create a task for it if there is none yet. i guess
> some metrics guys would love that idea, too. for developers, it's of
> course additional work.

I'd prefer adding it to the commit message. There are times when we want 
to link a commit to a task number without having it appear in a commit 
log, e.g. when fixing a regression which was never released or adding 
some internal enablers which would only clutter the changelog and not 
provide any extra value to users. Thus we would either have to add a lot 
of logic to interpret the Jira tasks and try to determine whether it 
should be included in the log or not, or we would have to add the 
possibility of manually overriding it. It just seems like a lot of extra 
potential for committers to break the system.

Having it as part of the commit message seems a lot less complex to me, 
and I don't think it would do any harm to an extra line of 
meta-information in the bottom section with the change-id and 
task-number where there's already lots of clutter.

-- Eskil

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

Re: [Development] ChangeLogs

[Koehne Kai]

> -Original Message-
> From: development-bounces+kai.koehne=digia@qt-project.org
> [mailto:development-bounces+kai.koehne=digia@qt-project.org] On
> Behalf Of Thiago Macieira
> Sent: Thursday, January 17, 2013 4:49 PM
> To: development@qt-project.org
> Subject: Re: [Development] ChangeLogs
> 
> > [...]
> > first a bit of historical background: in The Good Old Trolltech Days
> > ™,
> > *every* developer was compelled to write changelog fragments for their
> > own commits before the release.
> > this was assisted by a somewhat primitive commit log browser with a
> > checkbox next to each entry, which created a prototypical changelog
> > entry for each checked commit.
> 
> I don't think it did that. The checkbox was only an aid to let you know
> whether you had reviewed everything. And for the release manager to know
> whom to bug about not having done their changelogs.

Anyway, most Qt committers were working full-time in one company. Times are 
different now, we're many more, a lot not working full time on Qt, so just 
asking all the committers to fix the log before a release doesn't really work 
out any more, even if we had a tool like above for git.

> > we introduce a new footer ("ChangeLog:") to commit messages. this
> > would shift the burden to the contributor, and it could be properly
> reviewed.
> > the generation the logs could be fully automated, and only minimal
> > redactional work would be necessary.
> > a (somewhat minor) downside would be some redundancy in the commit
> > messages.
> > don't suggest to change the style of the commit summaries to be
> > ready-made changelog entries - this would be neither without
> > disadvantages (different target audience), nor would it fully solve
> > the problem (selection of commits for the changelog).
> 
> I don't like writing it in the commit message because it clutters the message
> with redundant information. Maybe we should consider git notes -- if Gerrit
> can propagate them.

If git notes would be seamlessly integrated that might work out indeed. But 
honestly speaking I don't think an additional line in some important commits 
does hurt too much either ... Often enough the commit message might actually be 
!= the changelog entry != the JIRA task, because all of them have different 
audiences & purposes.

Anyway, if I understood Ossi's second mail right the message would in a final 
system not even be part of the git log any more.

> > an alternative would be auto-generating the changelog from jira tasks.
> > consequently, if you consider something important enough for a
> > changelog entry, you need to create a task for it if there is none
> > yet. i guess some metrics guys would love that idea, too. for
> > developers, it's of course additional work.
> 
> But not by much. This would be acceptable, provided that generating such a
> draft changelog isn't too difficult.

I personally wouldn't go the JIRA route. I consider changing the title and the 
text of a user's bug report by myself impolite, and asking the original 
reporter to fix it , split things into different tasks etc just for the sake of 
a clean commit log is also not very appealing. 

So I'd go for adding a 'Commit-log:' message to the git, with the potential 
extension of extracting it in gerrit later on.

Regards

Kai


> --
> Thiago Macieira - thiago.macieira (AT) intel.com
>   Software Architect - Intel Open Source Technology Center
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Thiago Macieira]

On quinta-feira, 17 de janeiro de 2013 16.05.40, Oswald Buddenhagen wrote:
> hi *,
>
> as some certainly noted, the completeness of dist/changes-* severely
> deteriorated over the last few minor releases, and in particular 5.0.0
> is one of the poorest qt changelogs seen in a while.

Qt 5.0.0 is also one of the most major releases seen in a while -- 7.5 years
to be precise. The major release deserves special treatment: we agreed on
listing what was important for the porting effort.

> first a bit of historical background: in The Good Old Trolltech Days ™,
> *every* developer was compelled to write changelog fragments for their
> own commits before the release.
> this was assisted by a somewhat primitive commit log browser with a
> checkbox next to each entry, which created a prototypical changelog
> entry for each checked commit.

I don't think it did that. The checkbox was only an aid to let you know
whether you had reviewed everything. And for the release manager to know whom
to bug about not having done their changelogs.

> we introduce a new footer ("ChangeLog:") to commit messages. this would
> shift the burden to the contributor, and it could be properly reviewed.
> the generation the logs could be fully automated, and only minimal
> redactional work would be necessary.
> a (somewhat minor) downside would be some redundancy in the commit
> messages.
> don't suggest to change the style of the commit summaries to be
> ready-made changelog entries - this would be neither without
> disadvantages (different target audience), nor would it fully solve the
> problem (selection of commits for the changelog).

I don't like writing it in the commit message because it clutters the message
with redundant information. Maybe we should consider git notes -- if Gerrit
can propagate them.

> an alternative would be auto-generating the changelog from jira tasks.
> consequently, if you consider something important enough for a changelog
> entry, you need to create a task for it if there is none yet. i guess
> some metrics guys would love that idea, too. for developers, it's of
> course additional work.

But not by much. This would be acceptable, provided that generating such a
draft changelog isn't too difficult.

--
Thiago Macieira - thiago.macieira (AT) intel.com
  Software Architect - Intel Open Source Technology Center


signature.asc
Description: This is a digitally signed message part.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

Re: [Development] ChangeLogs

[Oswald Buddenhagen]

On Thu, Jan 17, 2013 at 04:05:40PM +0100, Oswald Buddenhagen wrote:
> two more approaches have been previously proposed:
> 
hjk suggested yet another approach: use gerrit itself to collect the
changelog entries. after some thinking, i came up with this process:
- add a ChangeLog: line to the commit message as in the previous
  proposal
- the commit-msg hook extracts and removes that line; the post-commit
  hook re-adds that line via git-notes
- change is pushed as usual - with git-gpush (which gets extended to
  push the notes as well)
- gerrit receives the commit and notes, creates a change, and attaches
  the changelog entry as an additional attribute to it
- up to now, everything was an optional extension - to save the
  contributor opening the gerrit page to add a changelog entry
- but of course, it would be possible to edit the changelog entry in the
  gui
- the changelog entry would be approved together with the actual change.
  whether this would happen in a separate review category, with the
  stage/submit button, or something yet different, i don't know.
- the system would require explicit action to approve the lack of a
  changelog entry
- for final storage, changelogs would be probably re-added as git
  notes again
- automated entry collection at release time would follow as with
  in-commit-message ChangeLog: entries

the advantages of the system:
- there is no "media break" like with a wiki or jira, as we use git and
  gerrit anyway
- the commit messages themselves are not "polluted"
- the changelog entries can be modified without amending and re-pushing
  the commit, thus not invalidating the actual review
- it would be also possible to let the reviewers write the changelog
  entry (which would then have to be approved by the contributor or
  another reviewer in turn)
- we could seamlessly switch from the in-commit-message ChangeLog:
  variant, as nothing would change in the manual steps at commit
  creation time (provided the notes-for-submission stuff would be
  implemented right away)
the downside is rather obvious:
- this needs to be implemented in gerrit (unless somebody already did
  something similar)

this is just a "step 2". it is in so far relevant, as the possibility of
adding this later may be considered an endorsement for the original
ChangeLog: variant.
___
Development mailing list
Development@qt-project.org
http://lists.qt-project.org/mailman/listinfo/development

[Development] ChangeLogs

[Oswald Buddenhagen]

hi *,

as some certainly noted, the completeness of dist/changes-* severely
deteriorated over the last few minor releases, and in particular 5.0.0
is one of the poorest qt changelogs seen in a while.

also, sergio is now attempting to make 5.0.1 changelogs in a heroic
one-man-effort - not entirely surprisingly, this turns out to be a tad
more tedious than planned.


first a bit of historical background: in The Good Old Trolltech Days ™,
*every* developer was compelled to write changelog fragments for their
own commits before the release.
this was assisted by a somewhat primitive commit log browser with a
checkbox next to each entry, which created a prototypical changelog
entry for each checked commit.

this mechanism won't work any more without modification: CI makes the
integration turnaround time too long, and thus the conflicts unbearable.
a workaround would be maintaining pending ChangeLogs in a wiki, and
putting them into git right before the releases. i think this can work
in principle. a bit of a problem is determining who "owns" a change -
the contributor (who can be a drive-by contributor who just happens to
be never seen when it's time to update changelogs, and doesn't want to
create a wiki account to start with), or the approvers (which one of
them?). such unclear responsibilities tend to produce poor results
(c.f.: current situation).


what sergio attempted now: mostly automated changelog generation from
the commit summaries. this failed spectacularly: the log contains way
too many useless entries, and many entries are meaningless. the main
problem is that the commit summaries are (rightfully) written from a
code change perspective, while the changelog needs to be user-oriented.
redacting this by hand by a single person is No Fun ™ for a patch
release, and outright insane for anything bigger.


two more approaches have been previously proposed:

we introduce a new footer ("ChangeLog:") to commit messages. this would
shift the burden to the contributor, and it could be properly reviewed.
the generation the logs could be fully automated, and only minimal
redactional work would be necessary.
a (somewhat minor) downside would be some redundancy in the commit
messages.
don't suggest to change the style of the commit summaries to be
ready-made changelog entries - this would be neither without
disadvantages (different target audience), nor would it fully solve the
problem (selection of commits for the changelog).

an alternative would be auto-generating the changelog from jira tasks.
consequently, if you consider something important enough for a changelog
entry, you need to create a task for it if there is none yet. i guess
some metrics guys would love that idea, too. for developers, it's of
course additional work.


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