Moving examples to a separate module

[c***@nokia.com]

Hi,

I would like to rename the current qt-webkit-examples-and-demos module to just qtexamples and put ALL examples in there, even the ones that only depend on a specific module (e.g. only QtCore).

What this means for the individual modules is that the /examples folder will disappear and will be put in the qtexamples module. Also most content from the /doc folder can be moved, since the text belonging with the examples should probably be in the qtdoc module.

Advantages:

* This repo can depend on everything in the CI system, then all examples are built in one go and we can see errors easier.
* We don't have examples all over the place, which makes it simpler for me to maintain, since I only have to look in the qtexamples repo.
* We get a place for examples that depend on multiple qt5 modules (e.g. QtWidgets and QtSvg).
* The SDK has only one place to look for examples.

Disadvantages:

* People have to clone the whole repo for just a few examples. (People that compile Qt from source will have to live with this, if you use the SDK this should not impact these people)
* If the API of a module changes and an example breaks it will not be caught by the CI system the moment the change is going into mainline.

I am wondering if any of you has opinions about this?

Casper

[r***@nokia.com]

On 09/14/11 at 12:50P, ext ***@nokia.com wrote:

[...]

> What this means for the individual modules is that the /examples
> folder will disappear and will be put in the qtexamples module. Also
> most content from the /doc folder can be moved, since the text
> belonging with the examples should probably be in the qtdoc module.

Moving examples out of the module might have an affect on the Qt5
release process. Thinking along those lines.

[...]

> * We don't have examples all over the place, which makes it
> simpler for me to maintain, since I only have to look in the
> qtexamples repo.

Why can't we integrate the examples in qt-webkit-examples-and-demos
module into qt-webkit?

> * We get a place for examples that depend on multiple qt5 modules
> (e.g. QtWidgets and QtSvg).

At the moment, QtWidgets and QtSvg are add-on modules. This means that
eventually the release maintainer has the flexibility to decide if these
modules makes sense for their configuration. If not, they can drop it
from their release.

However, if qt-examples, includes examples from QtCore + a number of
addons, the release maintainer will need to go thru' the hassle of
cleaning up qt-examples for every release and remove examples of addons
which doesn't belong in the release.

> * The SDK has only one place to look for examples.

This can still be done by looking into the examples directory in the
module and providing one picture to the SDK user. So, to me it doesn't
seem like a major advantage.

>
> Disadvantages:
>
> * People have to clone the whole repo for just a few
> examples. (People that compile Qt from source will have to live
> with this, if you use the SDK this should not impact these
> people)

> * If the API of a module changes and an example breaks it will not
> be caught by the CI system the moment the change is going into
> mainline.

Additional disadvantages.

- We now create a dependency between the module maintainer of any module
and the qt-examples module maintainer. Every time some change to the
example which could be because of a number of reasons - API change,
improving the example for additional clarity etc., the change needs to
be pushed into qt-examples.

- If somebody decides to create a new addon module, their ability to
release the module is now dependent on their examples being integrated
into qt-examples. Some module maintainers might decide to keep their
examples in their own repo to avoid the hassle. This would mean that
we'll end up having our examples all over the place.

Best,
Rajiv

[Stephen Kelly]

***@nokia.com wrote:
>> * We get a place for examples that depend on multiple qt5 modules
>> (e.g. QtWidgets and QtSvg).
>
> At the moment, QtWidgets and QtSvg are add-on modules.

> This means that
> eventually the release maintainer has the flexibility to decide if these
> modules makes sense for their configuration. If not, they can drop it
> from their release.

What's this about? What is a release maintainers configuration? Why would a
Qt module not be part of a release maintainers configuration?

>
> However, if qt-examples, includes examples from QtCore + a number of
> addons, the release maintainer will need to go thru' the hassle of
> cleaning up qt-examples for every release and remove examples of addons
> which doesn't belong in the release.
>

You seem to be saying some Qt modules will not be part of some releases.

Is a release maintainers configuration a release of a particular set of
versions of Qt modules? Why would there be multiple different
configurations?

> - We now create a dependency between the module maintainer of any module
> and the qt-examples module maintainer. Every time some change to the
> example which could be because of a number of reasons - API change,
> improving the example for additional clarity etc., the change needs to
> be pushed into qt-examples.

After the 5.0 release there presumably won't be API changes. Doesn't this
issue only apply to times when APIs are changing, which is presumably rarely
between releases?

>
> - If somebody decides to create a new addon module, their ability to
> release the module is now dependent on their examples being integrated
> into qt-examples. Some module maintainers might decide to keep their
> examples in their own repo to avoid the hassle. This would mean that
> we'll end up having our examples all over the place.

Just create incentives put examples in the same place. If people don't put
them in the right repo anyway, they're creating issues for themselves
because their stuff won't appear in the SDK examples for example, or won't
show up in the examples list in the docs.

[r***@nokia.com]

On 09/14/11 at 09:41P, ext Stephen Kelly wrote:

[...]

> > This means that
> > eventually the release maintainer has the flexibility to decide if these
> > modules makes sense for their configuration. If not, they can drop it
> > from their release.
>
> What's this about? What is a release maintainers configuration? Why would a
> Qt module not be part of a release maintainers configuration?

>From [1],

"A (release) configuration is a detailed specification of an operating
system version, a tool chain version, a graphics system, and possibly
other dependencies. The supported configurations of Qt are defined by
what is used in the build bots."

In order to meet the Qt5 release criteria, a release maintainer has to
just include Qt5 essential modules. In addition its really up to the
release maintainer to select the addons that makes sense for their
configuration.

For e.g., in Qt5 desktop configuration, is makes sense to include
QWidgets as an addon module, but then there could be a configuration on
a different OS where it might not make sense.

At that time, qtexamples module should not become an hinderance to that
release maintainer.

[...]

> > - We now create a dependency between the module maintainer of any module
> > and the qt-examples module maintainer. Every time some change to the
> > example which could be because of a number of reasons - API change,
> > improving the example for additional clarity etc., the change needs to
> > be pushed into qt-examples.
>
> After the 5.0 release there presumably won't be API changes. Doesn't this
> issue only apply to times when APIs are changing, which is presumably rarely
> between releases?

That's the goal and hopefully there'll be minimal changes to the APIs in
modules that are a part of Qt Essentials.

However, other Qt Modules might undergo API changes. So for those add-on
modules, the API compatibility promise could be different. It would
largely depend on the module maintainer.

Best,
Rajiv

[1] http://developer.qt.nokia.com/groups/qt_contributors_summit/wiki/Qt5ProductDefinition

[BRM]

>From: "***@nokia.com" <***@nokia.com>
>To: ***@gmail.com
>Cc: qt5-***@qt.nokia.com
>Sent: Wednesday, September 14, 2011 5:42 PM
>Subject: Re: [Qt5-feedback] Release configurations and API stability (Was: Re: Moving examples to a separate module)
>
>On 09/14/11 at 09:41P, ext Stephen Kelly wrote:
>
>[...]
>
>> > This means that
>> > eventually the release maintainer has the flexibility to decide if these
>> > modules makes sense for their configuration. If not, they can drop it
>> > from their release.
>>
>> What's this about? What is a release maintainers configuration? Why would a
>> Qt module not be part of a release maintainers configuration?
>
>>From [1],
>
>"A (release) configuration is a detailed specification of an operating
>system version, a tool chain version, a graphics system, and possibly
>other dependencies. The supported configurations of Qt are defined by
>what is used in the build bots."
>
>In order to meet the Qt5 release criteria, a release maintainer has to
>just include Qt5 essential modules. In addition its really up to the
>release maintainer to select the addons that makes sense for their
>configuration.
>
>For e.g., in Qt5 desktop configuration, is makes sense to include
>QWidgets as an addon module, but then there could be a configuration on
>a different OS where it might not make sense.
>
>At that time, qtexamples module should not become an hinderance to that
>release maintainer.
>
>[...]
>
>> > - We now create a dependency between the module maintainer of any module
>> >   and the qt-examples module maintainer. Every time some change to the
>> >   example which could be because of a number of reasons - API change,
>> >   improving the example for additional clarity etc., the change needs to
>> >   be pushed into qt-examples.
>>
>> After the 5.0 release there presumably won't be API changes. Doesn't this
>> issue only apply to times when APIs are changing, which is presumably rarely
>> between releases?
>
>That's the goal and hopefully there'll be minimal changes to the APIs in
>modules that are a part of Qt Essentials.
>
>However, other Qt Modules might undergo API changes. So for those add-on
>modules, the API compatibility promise could be different. It would
>largely depend on the module maintainer.
>
>[1]  http://developer.qt.nokia.com/groups/qt_contributors_summit/wiki/Qt5ProductDefinition
>


Please don't make Release Configurations overly complex in implementation.
That is - there should only be a handful of release configurations:

Windows
Mac
X11/Wayland/etc
Embedded/General (QWS)

Embedded/Symbian
Embedded/MeeGo

Each of these ought to be pretty straight forward and contain all modules by default; allowing developers to disable individual ones when they want just like in Qt4.
The exception might be Embedded/Symbian and Embedded/MeeGo where QtWidgets might not be used as QtGraphicsWidget+QML is likely the priority and main use there; but even there it should probably be available for developers to enable if desired.


It would only make things more difficult for people deciding which to use if you have to select from different flavors of Qt; as it is, the above can be problematic enough for Commercial Users - where X11/Mac/Windows while targetting different OS could simply be Qt Desktop instead.

There is not reason to follow Microsoft's lead of splitting Windows into Windows Starter Edition, Windows Home Premium, Windows Professional/Business Edition, Windows Ultimate, and the other variants that I am missing and doing something similar with Qt as that is not useful for developers when it comes to a toolkit.


$0.02

Ben

[l***@nokia.com]

On 9/15/11 3:05 PM, "ext BRM" <***@yahoo.com> wrote:
[snip]
>Please don't make Release Configurations overly complex in implementation.
>That is - there should only be a handful of release configurations:
>
>Windows
>Mac
>X11/Wayland/etc
>Embedded/General (QWS)
>
>Embedded/Symbian
>Embedded/MeeGo
>
>Each of these ought to be pretty straight forward and contain all modules
>by default; allowing developers to disable individual ones when they want
>just like in Qt4.
>The exception might be Embedded/Symbian and Embedded/MeeGo where
>QtWidgets might not be used as QtGraphicsWidget+QML is likely the
>priority and main use there; but even there it should probably be
>available for developers to enable if desired.
>
>
>It would only make things more difficult for people deciding which to use
>if you have to select from different flavors of Qt; as it is, the above
>can be problematic enough for Commercial Users - where X11/Mac/Windows
>while targetting different OS could simply be Qt Desktop instead.
>
>There is not reason to follow Microsoft's lead of splitting Windows into
>Windows Starter Edition, Windows Home Premium, Windows
>Professional/Business Edition, Windows Ultimate, and the other variants
>that I am missing and doing something similar with Qt as that is not
>useful for developers when it comes to a toolkit.

I actually want to simplify this significantly. Currently each linux
distribution usually builds Qt with a whole lot of custom flags. I'd like
to narrow this down to one standard configuration at least for desktop
OS'es.

On embedded systems, I'd rather like to do the feature selection on the
module level (ie. leave out QtWidgets if you want, no QtSvg, etc). rather
than disabling individual features and crippling the libraries.

The reason is that maintaining the defines for individual features has
been a huge hazzle in the past. Some configurations where always broken.
The added value that still was there when you had to fit things into 32MB
or ROM has mostly disappeared today, and savings for a sensible system
where not all that big.

Cheers,
Lars

[BRM]

----- Original Message -----

> From: "***@nokia.com" <***@nokia.com>
> On 9/15/11 3:05 PM, "ext BRM" <***@yahoo.com> wrote:
> [snip]
>> Please don't make Release Configurations overly complex in
> implementation.
>> That is - there should only be a handful of release configurations:
>>
>> Windows
>> Mac
>> X11/Wayland/etc
>> Embedded/General (QWS)
>>
>> Embedded/Symbian
>> Embedded/MeeGo
>>
>> Each of these ought to be pretty straight forward and contain all modules
>> by default; allowing developers to disable individual ones when they want
>> just like in Qt4.
>> The exception might be Embedded/Symbian and Embedded/MeeGo where
>> QtWidgets might not be used as QtGraphicsWidget+QML is likely the
>> priority and main use there; but even there it should probably be
>> available for developers to enable if desired.
>>
>>
>> It would only make things more difficult for people deciding which to use
>> if you have to select from different flavors of Qt; as it is, the above
>> can be problematic enough for Commercial Users - where X11/Mac/Windows
>> while targetting different OS could simply be Qt Desktop instead.
>>
>> There is not reason to follow Microsoft's lead of splitting Windows into
>> Windows Starter Edition, Windows Home Premium, Windows
>> Professional/Business Edition, Windows Ultimate, and the other variants
>> that I am missing and doing something similar with Qt as that is not
>> useful for developers when it comes to a toolkit.
>
> I actually want to simplify this significantly. Currently each linux
> distribution usually builds Qt with a whole lot of custom flags. I'd like
> to narrow this down to one standard configuration at least for desktop
> OS'es.
>
> On embedded systems, I'd rather like to do the feature selection on the
> module level (ie. leave out QtWidgets if you want, no QtSvg, etc). rather
> than disabling individual features and crippling the libraries.
>
> The reason is that maintaining the defines for individual features has
> been a huge hazzle in the past. Some configurations where always broken.
> The added value that still was there when you had to fit things into 32MB
> or ROM has mostly disappeared today, and savings for a sensible system
> where not all that big.
>

I can very well agree on that. I just don't want us to end up in a situation where developers are trying to figure out if the "Release" they got has all the features they need.
The developer compiling the software should be in charge of it - whether a distro or commercial user; but they shouldn't have to go through a major hassle to make sure the version they got is what they need - comparison charts should not be necessary when selecting a "Release" to use.

For sake of a comparison, kind of like with Windows - if you get the Windows 7 Business Edition then you don't get the Multimedia stuff that is in Windows 7 Home Premium, things you might need though for presentations.

Ben

[l***@nokia.com]

On 9/15/11 10:02 PM, "ext BRM" <***@yahoo.com> wrote:

>----- Original Message -----
>
>> From: "***@nokia.com" <***@nokia.com>
>> On 9/15/11 3:05 PM, "ext BRM" <***@yahoo.com> wrote:
>> [snip]
>>> Please don't make Release Configurations overly complex in
>> implementation.
>>> That is - there should only be a handful of release configurations:
>>>
>>> Windows
>>> Mac
>>> X11/Wayland/etc
>>> Embedded/General (QWS)
>>>
>>> Embedded/Symbian
>>> Embedded/MeeGo
>>>
>>> Each of these ought to be pretty straight forward and contain all
>>>modules
>>> by default; allowing developers to disable individual ones when they
>>>want
>>> just like in Qt4.
>>> The exception might be Embedded/Symbian and Embedded/MeeGo where
>>> QtWidgets might not be used as QtGraphicsWidget+QML is likely the
>>> priority and main use there; but even there it should probably be
>>> available for developers to enable if desired.
>>>
>>>
>>> It would only make things more difficult for people deciding which to
>>>use
>>> if you have to select from different flavors of Qt; as it is, the above
>>> can be problematic enough for Commercial Users - where X11/Mac/Windows
>>> while targetting different OS could simply be Qt Desktop instead.
>>>
>>> There is not reason to follow Microsoft's lead of splitting Windows
>>>into
>>> Windows Starter Edition, Windows Home Premium, Windows
>>> Professional/Business Edition, Windows Ultimate, and the other variants
>>> that I am missing and doing something similar with Qt as that is not
>>> useful for developers when it comes to a toolkit.
>>
>> I actually want to simplify this significantly. Currently each linux
>> distribution usually builds Qt with a whole lot of custom flags. I'd
>>like
>> to narrow this down to one standard configuration at least for desktop
>> OS'es.
>>
>> On embedded systems, I'd rather like to do the feature selection on the
>> module level (ie. leave out QtWidgets if you want, no QtSvg, etc).
>>rather
>> than disabling individual features and crippling the libraries.
>>
>> The reason is that maintaining the defines for individual features has
>> been a huge hazzle in the past. Some configurations where always broken.
>> The added value that still was there when you had to fit things into
>>32MB
>> or ROM has mostly disappeared today, and savings for a sensible system
>> where not all that big.
>>
>
>I can very well agree on that. I just don't want us to end up in a
>situation where developers are trying to figure out if the "Release" they
>got has all the features they need.
>The developer compiling the software should be in charge of it - whether
>a distro or commercial user; but they shouldn't have to go through a
>major hassle to make sure the version they got is what they need -
>comparison charts should not be necessary when selecting a "Release" to
>use.
>
>For sake of a comparison, kind of like with Windows - if you get the
>Windows 7 Business Edition then you don't get the Multimedia stuff that
>is in Windows 7 Home Premium, things you might need though for
>presentations.

Don't want this. Just have a look at the Qt product definition (see some
earlier thread on this list). We have Qt essentials that have to be there
on all platforms, and addons that are optional or only supported on
certain platforms. That should make this a lot clearer than with Qt 4.

Cheers,
Lars

[Thiago Macieira]

On Thursday, 15 de September de 2011 21.08.51, ***@nokia.com wrote:
> >For sake of a comparison, kind of like with Windows - if you get the
> >Windows 7 Business Edition then you don't get the Multimedia stuff that
> >is in Windows 7 Home Premium, things you might need though for
> >presentations.
>
> Don't want this. Just have a look at the Qt product definition (see some
> earlier thread on this list). We have Qt essentials that have to be there
> on all platforms, and addons that are optional or only supported on
> certain platforms. That should make this a lot clearer than with Qt 4.

"All the features" are defined by the Qt release, which is done by the Qt
community. The Qt community and project are the only ones entitled to
attributing a new version number.

Anything else is a "vendor branch". Vendors are allowed to apply patches if
they need them. They may not add or remove features, break binary
compatibility or invent a new version number.

--
Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
Software Architect - Intel Open Source Technology Center
PGP/GPG: 0x6EF45358; fingerprint:
E067 918B B660 DBD1 105C 966C 33F5 F005 6EF4 5358

[BRM]

>From: Thiago Macieira <***@kde.org>

>To: qt5-***@qt.nokia.com
>Sent: Friday, September 16, 2011 3:22 AM
>Subject: Re: [Qt5-feedback] Release configurations and API stability (Was: Re: Moving examples to a separate module)
>
>On Thursday, 15 de September de 2011 21.08.51, ***@nokia.com wrote:
>> >For sake of a comparison, kind of like with Windows - if you get the
>> >Windows 7 Business Edition then you don't get the Multimedia stuff that
>> >is in Windows 7 Home Premium, things you might need though for
>> >presentations.
>>
>> Don't want this. Just have a look at the Qt product definition (see some
>> earlier thread on this list). We have Qt essentials that have to be there
>> on all platforms, and addons that are optional or only supported on
>> certain platforms. That should make this a lot clearer than with Qt 4.
>
>"All the features" are defined by the Qt release, which is done by the Qt
>community. The Qt community and project are the only ones entitled to
>attributing a new version number.
>
>Anything else is a "vendor branch". Vendors are allowed to apply patches if
>they need them. They may not add or remove features, break binary
>compatibility or invent a new version number.
>


Thanks that is very good to know.

Ben

[Stephen Kelly]

Thiago Macieira wrote:

> On Thursday, 15 de September de 2011 21.08.51, ***@nokia.com wrote:
>> >For sake of a comparison, kind of like with Windows - if you get the
>> >Windows 7 Business Edition then you don't get the Multimedia stuff that
>> >is in Windows 7 Home Premium, things you might need though for
>> >presentations.
>>
>> Don't want this. Just have a look at the Qt product definition (see some
>> earlier thread on this list). We have Qt essentials that have to be there
>> on all platforms, and addons that are optional or only supported on
>> certain platforms. That should make this a lot clearer than with Qt 4.
>
> "All the features" are defined by the Qt release, which is done by the Qt
> community. The Qt community and project are the only ones entitled to
> attributing a new version number.
>
> Anything else is a "vendor branch". Vendors are allowed to apply patches
> if they need them. They may not add or remove features, break binary
> compatibility or invent a new version number.
>

What would such patches be? Patches to cpp files only?

What is a feature? If a vendor adds a method to a class is that a feature?

[c***@nokia.com]

________________________________________
From: Ranganath Rajiv (Nokia-DXM/SiliconValley)
Sent: Wednesday, September 14, 2011 9:14 PM
To: Vandonderen Casper (Nokia-MP-Qt/Oslo)
Cc: <qt5-***@qt.nokia.com>
Subject: Re: [Qt5-feedback] Moving examples to a separate module

On 09/14/11 at 12:50P, ext ***@nokia.com wrote:

[...]

>> What this means for the individual modules is that the /examples
>> folder will disappear and will be put in the qtexamples module. Also
>> most content from the /doc folder can be moved, since the text
>> belonging with the examples should probably be in the qtdoc module.
>>
>Moving examples out of the module might have an affect on the Qt5
>release process. Thinking along those lines.

I would say that the release process becomes simpler, since automatically only the examples that you have the modules for will be built, so if someone wants to do a release and does not want a specific module the examples for this module will not be built.

[...]

>> * We don't have examples all over the place, which makes it
>> simpler for me to maintain, since I only have to look in the
>> qtexamples repo.
>>
>Why can't we integrate the examples in qt-webkit-examples-and-demos
>module into qt-webkit?

They were there at some point, but now our qtwebkit repo only reflects upstream + our patches that have not gone upstream yet, since examples are not allowed upstream they are in a separate repository.

>> * We get a place for examples that depend on multiple qt5 modules
>> (e.g. QtWidgets and QtSvg).
>>
>At the moment, QtWidgets and QtSvg are add-on modules. This means that
>eventually the release maintainer has the flexibility to decide if these
>modules makes sense for their configuration. If not, they can drop it
>from their release.
>
>However, if qt-examples, includes examples from QtCore + a number of
>addons, the release maintainer will need to go thru' the hassle of
>cleaning up qt-examples for every release and remove examples of addons
>which doesn't belong in the release.

See above and this can be solved by copying the examples that belong with the modules you have to a different folder (automatically using .pro files, since we do that already in some cases)

>Additional disadvantages.
>
>- We now create a dependency between the module maintainer of any module
> and the qt-examples module maintainer. Every time some change to the
> example which could be because of a number of reasons - API change,
> improving the example for additional clarity etc., the change needs to
> be pushed into qt-examples.

This dependency is there anyway, since there will probably be a specific maintainer for the examples. Since the maintainer of the other modules is also a contributor and an approver I hope he/she can make a conscious decision about putting the example in.

>- If somebody decides to create a new addon module, their ability to
> release the module is now dependent on their examples being integrated
> into qt-examples. Some module maintainers might decide to keep their
> examples in their own repo to avoid the hassle. This would mean that
> we'll end up having our examples all over the place.

I am wondering if this is a valid point, since if we don't put the examples in the qtexamples module we have the examples all over the place anyway.

Casper

[r***@nokia.com]

On 09/14/11 at 02:28P, Vandonderen Casper (Nokia-MP-Qt/Oslo) wrote:

[...]

> >Why can't we integrate the examples in qt-webkit-examples-and-demos
> >module into qt-webkit?
>
> They were there at some point, but now our qtwebkit repo only reflects
> upstream + our patches that have not gone upstream yet, since
> examples are not allowed upstream they are in a separate repository.

So, this is a very WebKit specific issue. Why can't we just keep it as
it is? Have two repos for WebKit. We can just explain why its the case.

For the rest, examples stays in the examples directory inside the
module.

[...]

> >- If somebody decides to create a new addon module, their ability to
> > release the module is now dependent on their examples being integrated
> > into qt-examples. Some module maintainers might decide to keep their
> > examples in their own repo to avoid the hassle. This would mean that
> > we'll end up having our examples all over the place.
>
> I am wondering if this is a valid point, since if we don't put the
> examples in the qtexamples module we have the examples all over the
> place anyway.

Well, then it'll only be in the examples directory inside the module,
with the exception of WebKit.

Best,
Rajiv

[l***@nokia.com]

> On 09/14/11 at 02:28P, Vandonderen Casper (Nokia-MP-Qt/Oslo) wrote:
>
> [...]
>
> > >Why can't we integrate the examples in qt-webkit-examples-and-demos
> > >module into qt-webkit?
> >
> > They were there at some point, but now our qtwebkit repo only reflects
> > upstream + our patches that have not gone upstream yet, since examples
> > are not allowed upstream they are in a separate repository.
>
> So, this is a very WebKit specific issue. Why can't we just keep it as it is? Have
> two repos for WebKit. We can just explain why its the case.

I'd say we can fix this for WebKit as well. WebKit already comes with some examples, and as long as we can fit the examples development to the existing WebKit contribution model, I do not see a problem. Personally I support keeping QtWebKit examples on webkit.org trunk.

Regards,
Laszlo

[Alan Alpert]

On Wed, 14 Sep 2011 22:50:37 ext ***@nokia.com wrote:
> Hi,
>
> I would like to rename the current qt-webkit-examples-and-demos module to
> just qtexamples and put ALL examples in there, even the ones that only
> depend on a specific module (e.g. only QtCore).
>
> What this means for the individual modules is that the /examples folder
> will disappear and will be put in the qtexamples module. Also most content
> from the /doc folder can be moved, since the text belonging with the
> examples should probably be in the qtdoc module.
>
> Advantages:
>
> * This repo can depend on everything in the CI system, then all
> examples are built in one go and we can see errors easier.
> * We don't
> have examples all over the place, which makes it simpler for me to
> maintain, since I only have to look in the qtexamples repo.
> * We get a
> place for examples that depend on multiple qt5 modules (e.g. QtWidgets and
> QtSvg).

I believe these used to be called 'Demos'. I have no objection to placing
demos in a separate repo, but they should be practically the only ones that
1) Will not have errors closely linked to module changes (such as API changes
or regressions).
2) Might not be directly maintained by the code maintainers.
3) Pull in multiple modules.

I strongly support bringing back the concept of demos, distinct from examples.
Demos - More well rounded, like a real application, using multiple features
and with larger and more complex code.
Examples - Very simple code showing off just one small feature, or just one
aspect of a large feature. It will not look like a real application, and
that's fine.

> * The SDK has only one place to look for examples.
>
> Disadvantages:
>
> * People have to clone the whole repo for just a few examples. (People
> that compile Qt from source will have to live with this, if you use the
> SDK this should not impact these people)
> * If the API of a module
> changes and an example breaks it will not be caught by the CI system the
> moment the change is going into mainline.
>
> I am wondering if any of you has opinions about this?

This sounds to me like it's missing a key point of our examples. They aren't
just there for documentation, they're also very useful for validation and
testing. The examples for a feature are currently one of the few ways we have
for the implementer and maintainer of that feature to have it running, on its
own, somewhere in the Qt code base. They need to be written by the maintainers
because they need to show the way it's meant to be used. And they need to be
maintained by the feature maintainers because if the usage pattern evolves
that's an important consideration for the API.

When they're used like that, then the people who work on those examples
already have that repo - and not some generic repo - cloned. The changes to
the example will likely follow directly from API changes leading to the
aforementioned CI problems. On top of that you won't be sole maintainer of it,
which makes some of the advantages less necessary.

--
Alan Alpert
Senior Engineer
Nokia, Qt Development Frameworks

[a***@nokia.com]

>-----Original Message-----
>From: qt5-feedback-bounces+alex.blasche=***@qt.nokia.com
>[mailto:qt5-feedback-bounces+alex.blasche=***@qt.nokia.com] On
>Behalf Of ext Alan Alpert

>> Disadvantages:
>>
>> * People have to clone the whole repo for just a few examples. (People
>> that compile Qt from source will have to live with this, if you use the
>> SDK this should not impact these people)
>> * If the API of a module
>> changes and an example breaks it will not be caught by the CI system the
>> moment the change is going into mainline.
>>
>> I am wondering if any of you has opinions about this?
>
>This sounds to me like it's missing a key point of our examples. They aren't
>just there for documentation, they're also very useful for validation and
>testing. The examples for a feature are currently one of the few ways we
>have
>for the implementer and maintainer of that feature to have it running, on its
>own, somewhere in the Qt code base. They need to be written by the
>maintainers
>because they need to show the way it's meant to be used. And they need to
>be
>maintained by the feature maintainers because if the usage pattern evolves
>that's an important consideration for the API.
>
>When they're used like that, then the people who work on those examples
>already have that repo - and not some generic repo - cloned. The changes to
>the example will likely follow directly from API changes leading to the
>aforementioned CI problems. On top of that you won't be sole maintainer of
>it,
>which makes some of the advantages less necessary.

Just to put more weight behind Alan's argument. I fully agree with his statement. The disadvantages are far more significant than the benefits. I would go as far as saying that the main purpose of the example is quick testing and the doc aspect is just sugar on top. Let's not make the current repo split situation worse than it is already.

--
Alex

[Mark Constable]

On 2011-09-15 05:07 AM, ***@nokia.com wrote:
> >When they're used like that, then the people who work on those
> >examples already have that repo - and not some generic repo -
> >cloned. The changes to the example will likely follow directly
> >from API changes leading to the aforementioned CI problems. On
> >top of that you won't be sole maintainer of it, which makes some
> >of the advantages less necessary.
>
> Just to put more weight behind Alan's argument. I fully agree with
> his statement. The disadvantages are far more significant than the
> benefits. I would go as far as saying that the main purpose of the
> example is quick testing and the doc aspect is just sugar on top.
> Let's not make the current repo split situation worse than it is
> already.

OTOH it could be useful for the developer to know their example code
will build and run outside of their cosey checkout and, perhaps,
encourage them to interact with the other code examples as well. It's
a bit more bother for individual developers but the overall health of
all the examples may improve.

[Alan Alpert]

On Thu, 15 Sep 2011 14:45:59 ext Mark Constable wrote:
> On 2011-09-15 05:07 AM, ***@nokia.com wrote:
> > >When they're used like that, then the people who work on those
> > >examples already have that repo - and not some generic repo -
> > >cloned. The changes to the example will likely follow directly
> > >from API changes leading to the aforementioned CI problems. On
> > >top of that you won't be sole maintainer of it, which makes some
> > >of the advantages less necessary.
> >
> > Just to put more weight behind Alan's argument. I fully agree with
> > his statement. The disadvantages are far more significant than the
> > benefits. I would go as far as saying that the main purpose of the
> > example is quick testing and the doc aspect is just sugar on top.
> > Let's not make the current repo split situation worse than it is
> > already.
>
> OTOH it could be useful for the developer to know their example code
> will build and run outside of their cosey checkout and, perhaps,
> encourage them to interact with the other code examples as well. It's
> a bit more bother for individual developers but the overall health of
> all the examples may improve.
>

You're thinking of demos. Examples should be so simple and single-minded that
it's pointless to interact with other examples. Or even other repositories.

Now if we had demos again, they could interact with other examples and verify
that things run against a full and common checkout or something. But the extra
complexity is only going to confuse the matter for a example that's trying to
demonstrate/test a single thing with utmost clarity.

--
Alan Alpert
Senior Engineer
Nokia, Qt Development Frameworks

[c***@nokia.com]

On 9/15/11 9:05 AM, "ext Alan Alpert" <***@nokia.com> wrote:

>On Thu, 15 Sep 2011 14:45:59 ext Mark Constable wrote:
>> On 2011-09-15 05:07 AM, ***@nokia.com wrote:
>> > >When they're used like that, then the people who work on those
>> > >examples already have that repo - and not some generic repo -
>> > >cloned. The changes to the example will likely follow directly
>> > >from API changes leading to the aforementioned CI problems. On
>> > >top of that you won't be sole maintainer of it, which makes some
>> > >of the advantages less necessary.
>> >
>> > Just to put more weight behind Alan's argument. I fully agree with
>> > his statement. The disadvantages are far more significant than the
>> > benefits. I would go as far as saying that the main purpose of the
>> > example is quick testing and the doc aspect is just sugar on top.
>> > Let's not make the current repo split situation worse than it is
>> > already.
>>
>> OTOH it could be useful for the developer to know their example code
>> will build and run outside of their cosey checkout and, perhaps,
>> encourage them to interact with the other code examples as well. It's
>> a bit more bother for individual developers but the overall health of
>> all the examples may improve.
>>
>
>You're thinking of demos. Examples should be so simple and single-minded
>that
>it's pointless to interact with other examples. Or even other
>repositories.
>
>Now if we had demos again, they could interact with other examples and
>verify
>that things run against a full and common checkout or something. But the
>extra
>complexity is only going to confuse the matter for a example that's
>trying to
>demonstrate/test a single thing with utmost clarity.


Before Open Governance it was decided between the team leads in the Qt
offices that Qt5 would only have examples, since the old wording for demos
and examples was not clear.

Also the decision was made that all examples that go into the Qt Project
should have documentation, no matter how simple or complex they are. A
'hello world' is therefore the same as someone building a full strategy
game in QML. (That this is outside of open governance is IMHO beside the
point, since I think we can agree that it is a good idea to have
documentation for examples)

The documentation for the examples should normally go into the qtdoc
module (which means that you would have to change your own module, the
qtexamples module and the qtdoc module). We can agree that all
documentation for examples would live in the qtexamples module.

That means that we move from 'module + qtdoc' to 'module + qtexamples' for
example content.


Casper

[Alan Alpert]

On Thu, 15 Sep 2011 17:46:11 Vandonderen Casper (Nokia-MP-Qt/Oslo) wrote:
> On 9/15/11 9:05 AM, "ext Alan Alpert" <***@nokia.com> wrote:
> >On Thu, 15 Sep 2011 14:45:59 ext Mark Constable wrote:
> >> On 2011-09-15 05:07 AM, ***@nokia.com wrote:
> >> > >When they're used like that, then the people who work on those
> >> > >examples already have that repo - and not some generic repo -
> >> > >cloned. The changes to the example will likely follow directly
> >> > >from API changes leading to the aforementioned CI problems. On
> >> > >top of that you won't be sole maintainer of it, which makes some
> >> > >of the advantages less necessary.
> >> >
> >> > Just to put more weight behind Alan's argument. I fully agree with
> >> > his statement. The disadvantages are far more significant than the
> >> > benefits. I would go as far as saying that the main purpose of the
> >> > example is quick testing and the doc aspect is just sugar on top.
> >> > Let's not make the current repo split situation worse than it is
> >> > already.
> >>
> >> OTOH it could be useful for the developer to know their example code
> >> will build and run outside of their cosey checkout and, perhaps,
> >> encourage them to interact with the other code examples as well. It's
> >> a bit more bother for individual developers but the overall health of
> >> all the examples may improve.
> >
> >You're thinking of demos. Examples should be so simple and single-minded
> >that
> >it's pointless to interact with other examples. Or even other
> >repositories.
> >
> >Now if we had demos again, they could interact with other examples and
> >verify
> >that things run against a full and common checkout or something. But the
> >extra
> >complexity is only going to confuse the matter for a example that's
> >trying to
> >demonstrate/test a single thing with utmost clarity.
>
> Before Open Governance it was decided between the team leads in the Qt
> offices that Qt5 would only have examples, since the old wording for demos
> and examples was not clear.

Judging from what I've seen of the reactions from team leads down here, you
may have missed an office...

Perhaps we can revisit the decision after Open Governance? Give the chief
maintainer a nice easy problem to get him started?

> Also the decision was made that all examples that go into the Qt Project
> should have documentation, no matter how simple or complex they are. A
> 'hello world' is therefore the same as someone building a full strategy
> game in QML. (That this is outside of open governance is IMHO beside the
> point, since I think we can agree that it is a good idea to have
> documentation for examples)

This is a dig against the abysmal Plasma Patrol docs isn't it? :P

> The documentation for the examples should normally go into the qtdoc
> module (which means that you would have to change your own module, the
> qtexamples module and the qtdoc module). We can agree that all
> documentation for examples would live in the qtexamples module.
>
> That means that we move from 'module + qtdoc' to 'module + qtexamples' for
> example content.

As I understood it, the documentation for the examples should go into the
module in question - not qtdoc. We still have a doc directory in the module
structure that we can happily use for that, and the people writing the example
have to be the ones to write at least the first draft of the documentation. If
they aren't writing it now because they can't be bothered, then moving it to
another repository is only going to make things worse. So I don't think the
example docs should be in qtdoc - keep them with the examples (which I think
should be with the code).

That means that we move from 'module' to 'module + qtexamples' for example
content. No longer such an appealing switch.

--
Alan Alpert
Senior Engineer
Nokia, Qt Development Frameworks

[j***@nokia.com]

Hello,

Why not have both?

A Qt example is essentially a demo, where you are free to use multiple module dependencies. The individual repositories can keep the current code samples and snippets in their own repositories.

The problem is that we need to have the freedom to include examples that have dependencies and they do not belong to the individual repositories.

So, let's say we have a Media Player example. It depends on core, declarative, components, multimediakit, etc. This example cannot be in the qtbase, qtdeclarative, qtcomponents, qtmultimediakit, and so on. Since it's not documentation either, it shouldn't be in qtdoc. Hence, it should be in some sort of repository where it and others can exist.

Just to note, we receive many of these examples and they are needed in the overall Qt 5 landscape. One Qt story is the "porting" story whose content is quite anemic. We receive Qt+SymbianAPI examples which we cannot put into the main Qt 5 repo. We simply ignore them, which is a shame, really.

I would like to keep the trivial code into the submodule repository for these reasons:
-any bugs on these code will be filed against the module and module maintainers and not the doc team. Developers make them, so they should be responsible for them. There are simply too many to manage in too many repos. The module maintainer should have control of these issues and not the QtDoc or Qt Examples maintainers.
-any Qt examples are put into a separate repo, where its maintainer (ie. Casper) can handle the bugs and act like a proper maintainer.

The any qt5 module maintainer can simply ignore the Qt examples and they will still have their API, API listing, and their snippets. But the overall Qt 5 product pages and the Qt examples should be separate as they do have multiple dependencies.


With regards to definition:
Qt Example: "demos" and any other code samples, etc.
snippet code: trivial code, code samples.
The overlap is intentional. *Don't be afraid of overlap*

About the sugar comment. Sugar is good, it attracts people. A product without fluff is not a product.

Cheers,
Jerome P.
________________________________________
From: qt5-feedback-bounces+jerome.pasion=***@qt.nokia.com [qt5-feedback-bounces+jerome.pasion=***@qt.nokia.com] on behalf of Alpert Alan (Nokia-MP-Qt/Brisbane)
Sent: Thursday, September 15, 2011 9:05 AM
To: qt5-***@qt.nokia.com
Subject: Re: [Qt5-feedback] Moving examples to a separate module

On Thu, 15 Sep 2011 14:45:59 ext Mark Constable wrote:
> On 2011-09-15 05:07 AM, ***@nokia.com wrote:
> > >When they're used like that, then the people who work on those
> > >examples already have that repo - and not some generic repo -
> > >cloned. The changes to the example will likely follow directly
> > >from API changes leading to the aforementioned CI problems. On
> > >top of that you won't be sole maintainer of it, which makes some
> > >of the advantages less necessary.
> >
> > Just to put more weight behind Alan's argument. I fully agree with
> > his statement. The disadvantages are far more significant than the
> > benefits. I would go as far as saying that the main purpose of the
> > example is quick testing and the doc aspect is just sugar on top.
> > Let's not make the current repo split situation worse than it is
> > already.
>
> OTOH it could be useful for the developer to know their example code
> will build and run outside of their cosey checkout and, perhaps,
> encourage them to interact with the other code examples as well. It's
> a bit more bother for individual developers but the overall health of
> all the examples may improve.
>

You're thinking of demos. Examples should be so simple and single-minded that
it's pointless to interact with other examples. Or even other repositories.

Now if we had demos again, they could interact with other examples and verify
that things run against a full and common checkout or something. But the extra
complexity is only going to confuse the matter for a example that's trying to
demonstrate/test a single thing with utmost clarity.

--
Alan Alpert
Senior Engineer
Nokia, Qt Development Frameworks

[Alan Alpert]

On Thu, 15 Sep 2011 17:53:01 Pasion Jerome (Nokia-MP-Qt/Oslo) wrote:
> Hello,
>
> Why not have both?
>
> A Qt example is essentially a demo, where you are free to use multiple
> module dependencies. The individual repositories can keep the current code
> samples and snippets in their own repositories.
>
> The problem is that we need to have the freedom to include examples that
> have dependencies and they do not belong to the individual repositories.
>
> So, let's say we have a Media Player example. It depends on core,
> declarative, components, multimediakit, etc. This example cannot be in the
> qtbase, qtdeclarative, qtcomponents, qtmultimediakit, and so on. Since
> it's not documentation either, it shouldn't be in qtdoc. Hence, it should
> be in some sort of repository where it and others can exist.
>
> Just to note, we receive many of these examples and they are needed in the
> overall Qt 5 landscape. One Qt story is the "porting" story whose content
> is quite anemic. We receive Qt+SymbianAPI examples which we cannot put
> into the main Qt 5 repo. We simply ignore them, which is a shame, really.
>
> I would like to keep the trivial code into the submodule repository for
> these reasons: -any bugs on these code will be filed against the module
> and module maintainers and not the doc team. Developers make them, so they
> should be responsible for them. There are simply too many to manage in too
> many repos. The module maintainer should have control of these issues and
> not the QtDoc or Qt Examples maintainers. -any Qt examples are put into a
> separate repo, where its maintainer (ie. Casper) can handle the bugs and
> act like a proper maintainer.
>
> The any qt5 module maintainer can simply ignore the Qt examples and they
> will still have their API, API listing, and their snippets. But the
> overall Qt 5 product pages and the Qt examples should be separate as they
> do have multiple dependencies.
>
>
> With regards to definition:
> Qt Example: "demos" and any other code samples, etc.
> snippet code: trivial code, code samples.
> The overlap is intentional. *Don't be afraid of overlap*
>
> About the sugar comment. Sugar is good, it attracts people. A product
> without fluff is not a product.
>

I like this idea - though I still have my own opinions on the naming ;) .

Does this mean that $module_name/examples would be split up? The bigger
'examples' becoming Qt Examples and moving to qtexamples and the smaller ones
becoming snippets (but staying in $module_name/examples)? Who would be making
this decision?

--
Alan Alpert
Senior Engineer
Nokia, Qt Development Frameworks

[c***@nokia.com]

>
>I like this idea - though I still have my own opinions on the naming ;) .
>
>Does this mean that $module_name/examples would be split up? The bigger
>'examples' becoming Qt Examples and moving to qtexamples and the smaller
>ones
>becoming snippets (but staying in $module_name/examples)? Who would be
>making
>this decision?


The folder structure should be similar to that, for now the examples
therefore stay in the modules and their maintainer can request the
qtexamples module maintainer (e.g. probably me) to move it, or move it
themselves, because they are also approvers.

The qtexamples module maintainer should then figure out if there are
examples that are so similar in name/functionality that it might make
sense to remove/refactor some of them. (example: there are 3 calculator
examples in the source tree, one QML, one widgets and one Qt Designer.
They all show something completely different in Qt, but in Creator it will
show 3 calculator examples below each other, which might make it confusing
for users to understand which one they should use).

What this also means it that it is the maintainers responsibility for an
example inside a module to show up in the documentation in qtdoc (if you
would want the example to be visible in the documentation)

Casper

[Oswald Buddenhagen]

On Thu, Sep 15, 2011 at 09:28:53AM +0000, ext ***@nokia.com wrote:
> or move it themselves, because they are also approvers.
>
uhm, what?
the one wanting the change (probably the module maintainer) actually
performs it, and *somebody else* who is an approver (probably the
examples maintainer) approves it.

[c***@nokia.com]

On 9/15/11 11:34 AM, "ext Oswald Buddenhagen"
<***@nokia.com> wrote:

>On Thu, Sep 15, 2011 at 09:28:53AM +0000, ext
>***@nokia.com wrote:
>> or move it themselves, because they are also approvers.
>>
>uhm, what?
>the one wanting the change (probably the module maintainer) actually
>performs it, and *somebody else* who is an approver (probably the
>examples maintainer) approves it.

Sorry I was unclear there, that is what I meant, that the examples
maintainer is not the person who creates the patch to move it, and gets it
approved by the source module maintainer, but the other way around.

Casper

[Attila Csipa]

On Thursday 15 September 2011 11:45:36 Alan Alpert wrote:
> This sounds to me like it's missing a key point of our examples. They aren't
> just there for documentation, they're also very useful for validation and
> testing. The examples for a feature are currently one of the few ways we

A bit late, but ... Two things I miss dearly from the current example
structure:

1. No reference-to-example linking, so when looking at a class, one sees
snippets (good), but if one wants to quickly fire up an example implementing
that (to avoid boilerplate and copy-paste-itis), one has to traverse/search
through examples (or demos) and try to figure out just which ones use the
class in question.

2. Clear indication what (and which version of it) the example is an example
for (this ties into the validation part). I understand that examples are
supposed to be short, but we often lack context. The examples are just
extracted into a directory hierarchy that does not reflect
requirements/recommendations, so it's not that easy to tell if an example
fails that it's really a failure, or is it just being used with the wrong
target/Qt version/settings/use case. This was especially true for Mobility
classes, but as those are headed for inclusion into Qt5 modules, I guess
that's the same story.


Best regards,
Attila Csipa

[Jedrzej Nowacki]

On Wednesday 14. September 2011 14.50.37 ext ***@nokia.com
wrote:
> (...)
> Disadvantages:
>
> * People have to clone the whole repo for just a few examples. (People
> that compile Qt from source will have to live with this, if you use the
> SDK this should not impact these people) * If the API of a module
> changes and an example breaks it will not be caught by the CI system the
> moment the change is going into mainline.
> (...)

Another disadvantage is that currently autotest and benchmarks use demos, at
least for QtScript. That was done not because we are lazy and we didn't bother
to reduce size of an use case :-) The idea behind it was to not create only
micro benchmarks that shows performance of a method. We need a easy way to
benchmark full code stack for typical usage and I'm not sure if there is
something better then benchmarking a real, working application or demo.

Cheers,
Jędrek

[Kent Hansen]

Den 15. sep. 2011 09:42, skrev ext Jedrzej Nowacki:
>
> On Wednesday 14. September 2011 14.50.37 ext
> ***@nokia.com wrote:
>
> > (...)
>
> > Disadvantages:
>
> >
>
> > * People have to clone the whole repo for just a few examples. (People
>
> > that compile Qt from source will have to live with this, if you use the
>
> > SDK this should not impact these people) * If the API of a module
>
> > changes and an example breaks it will not be caught by the CI system the
>
> > moment the change is going into mainline.
>
> > (...)
>
>
> Another disadvantage is that currently autotest and benchmarks use
> demos, at least for QtScript. That was done not because we are lazy
> and we didn't bother to reduce size of an use case :-) The idea behind
> it was to not create only micro benchmarks that shows performance of a
> method. We need a easy way to benchmark full code stack for typical
> usage and I'm not sure if there is something better then benchmarking
> a real, working application or demo.
>
>
> Cheers,
>
> Jędrek
>
>

Yes, examples (not demos) are used for automatic testing.
Same deal for QtDeclarative, which Alan and Alex already mentioned.
This should be a compelling enough reason to keep them where they are.

Regards,
Kent