[Development] New Qt example development guideline and revamping examples

[Shawn Rutledge]

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/c45261e8/attachment-0001.htm>