[Development] New Qt example development guideline and revamping examples

[Tuukka Turunen]

”The point of examples is to show how to use Qt to do specific things.  Some of them are redundant? Well there is not only one way to do things; why should we hide something cool just because it’s only the second of several choices? In the future I think we will hesitate to write new examples if the risk of deletion is so high. ”

On the contrary, target is to make the examples more useful by ensuring all examples follow the best practices and improving how they are shown in documentation and creator welcome page. No-one want to delete examples that are good and useful for our users.

The list I sent is examples that are currently not shown in docs or creator, so users are not that likely to find them. We should also think why these examples are not shown? Typically this is not by accident, but it has been determined that it is better to hide the example.

The list contains 113 examples, so I am sure there are some that would be better to fix to meet the example guideline, write the documentation and show the example. But for many of these the value as an example is low. Thus is better to move to manual tests in case we need it for testing purposes.

Yours,

                Tuukka

From: Development <development-bounces at qt-project.org> on behalf of Shawn Rutledge via Development <development at qt-project.org>
Date: Friday, 3. February 2023 at 15.56
To: Qt Development <development at qt-project.org>
Subject: Re: [Development] New Qt example development guideline and revamping examples

On 3 Feb 2023, at 13:56, Tuukka Turunen via Development <development at qt-project.org> wrote:

pdf/pdfviewer

Depends which one you mean.  They are all new and maintained at this point.  There is some redundancy on purpose, because there are multiple PDF-viewing components.  So I wouldn’t delete any of them.


quick/delegatechooser

We need to make sure we are showing DelegateChooser somewhere; it’s quite useful.  I don’t see it in any other examples.


quick/pointerhandlers

I plan to give the pointerhandlers example some proper docs.  It only recently graduated from being a manual test.  It may not look like a “proper desktop application” but that’s not the point.

… many more I don’t remember so well, and then...
wayland/custom-extension
wayland/custom-extension/compositor
wayland/custom-extension/cpp-client
wayland/custom-extension/qml-client
wayland/custom-shell/client-plugin
wayland/custom-shell/compositor
wayland/hwlayer-compositor
wayland/minimal-cpp
wayland/server-buffer
wayland/server-buffer/compositor
wayland/server-buffer/cpp-client
widgets/itemviews/flattreeview
widgets/itemviews/storageview
...


As Kimmo mentioned, we should aim to check and move (or remove if not seen relevant as a manual test by the module maintainer) these during February.

You are talking about removing them from the manifest, not removing the code, I hope? Even so...

The point of examples is to show how to use Qt to do specific things.  Some of them are redundant? Well there is not only one way to do things; why should we hide something cool just because it’s only the second of several choices?

In the future I think we will hesitate to write new examples if the risk of deletion is so high.

Move them to manual tests?  Well that’s better than deleting, but users will not tend to find those, because we don’t ship them.

Snippets? I think those should be complete enough to actually run.  Otherwise it’s too much work to keep re-verifying that they still work.  And it is more useful to users to start with a complete, minimal example that already runs, and then add the extra functionality that they want, rather than just some stanza of code that got broken at some point along the way.  With QML that’s not too hard; so my rule is every QML snippet should be a complete standalone file that can run with the qml tool.  But with C++ snippets it’s not convenient to make them runnable; so when we convert C++ examples to snippets, we can expect them to rot, unless we come up with a way to auto-wrap them with boilerplate and test them automatically on a periodic basis (in CI, in pre-release testing or whatever).

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20230203/bc4f9b49/attachment-0001.htm>