Re: [Development] Nominating Jøger Hansegård for approver rights

[Topi Reiniö via Development]

+1

From: Development  on behalf of Matthias 
Rauter via Development 
Sent: Tuesday, March 26, 2024 10:12 AM
To: development 
Subject: Re: [Development] Nominating Jøger Hansegård for approver rights

+1 

From: Development  on behalf of Tor Arne 
Vestbø via Development 
Sent: Thursday, March 14, 2024 10:06 AM
To: development 
Subject: [Development] Nominating Jøger Hansegård for approver rights

Hi,

I would like to nominate Jøger Hansegård for approver rights in the Qt project.

Jøger joined The Qt Company 10 months ago and has since then been getting his 
hands dirty in Qt Multimedia, and lately focusing on color management.

Jøger is a thorough and responsible engineer and I trust that he will make a 
good approver for the Qt project.

Authored changes: 
https://codereview.qt-project.org/q/owner:joger.hansegard%2540qt.io
Reviews: https://codereview.qt-project.org/q/reviewer:joger.hansegard%2540qt.io

Cheers,
Tor Arne
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] How to document API only deprecated in future Qt versions

[Topi Reiniö via Development]

> I'm not sure how viable this is, it's just an idea off the top of my head: we 
> could perhaps implement support
> for "from/until" e.g. in the class members section, similar to what's on 
> cppreference.com (e.g. void foo()
> [since 5.15, until 6.5]). The docs for something that's gone could then 
> possibly link to the published docs for
> the last version (defined by whatever sets the "until" version) that 
> particular feature is documented in, such
> that the members list for e.g. 6.7 would carry members that don't exist in 
> 6.7 but link to the last known state
> of that member. Then we could drop the -obsolete pages entirely (they 
> sometimes confuse  search engines,
> so that's an argument in favor of getting rid of them) and we'd point users 
> of older Qt versions to versions of
> the docs that are possibly more relevant for them anyway.

Yes, having QDoc support both 'since' and 'until', presented in the same 
context, would be an improvement.
Potentially, QDoc could also parse the deprecation macros and apply them to 
documentation, or ideally,
warn the author about missing deprecation docs. This would be useful to ensure 
that the 'use this instead'
information, as mentioned by Eddy, is available. Dropping deprecated docs in 
favor of linking to old archives
would mean we'd likely lose that bit of useful info. There's a benefit of 
having all the docs in a self-contained
set as well.

-Topi

From: Development  on behalf of Paul 
Wicking via Development 
Sent: Friday, September 15, 2023 11:25 AM
To: Edward Welbourne 
Cc: development@qt-project.org 
Subject: Re: [Development] How to document API only deprecated in future Qt 
versions



On 15 Sep 2023, at 10:44, Edward Welbourne via Development 
 wrote:

On 9/15/23 09:36, Kai Köhne via Development wrote:
The methods are formally marked as deprecated for Qt 6.10. But the
methods are already in the '-obsolete' page for Qt 6.6, which leaves
the API in a weird in-between state.

Christian Kandeler (15 September 2023 10:31) wrote:
Radical idea: Treat all deprecated functions as if they didn't exist,
i.e. remove the documentation entirely. It seems counter-intuitive
that legacy interfaces should take more documentation effort than
current ones. Also, this way, fewer people will even be tempted to
short-sightedly use them.

Tempting as that radical approach is, the temptation you're trying to
prevent is mostly avoided by hiding the docs of deprecated functions on
the -obsolete page; and we do have to think of folk who are trying to
work out what their existing code does.  It's hard to port away from an
old API if you don't have a clear description of what your old code was
achieving by using it, so as to be sure you've achieved the same result
with your use of the new API.  The documentation of a deprecated
function should, also, tell the reader what to use instead, to help them
work that out; they can't read that advice if it's not there.

I'm not sure how viable this is, it's just an idea off the top of my head: we 
could perhaps implement support for "from/until" e.g. in the class members 
section, similar to what's on cppreference.com (e.g. 
void foo() [since 5.15, until 6.5]). The docs for something that's gone could 
then possibly link to the published docs for the last version (defined by 
whatever sets the "until" version) that particular feature is documented in, 
such that the members list for e.g. 6.7 would carry members that don't exist in 
6.7 but link to the last known state of that member. Then we could drop the 
-obsolete pages entirely (they sometimes confuse  search engines, so that's an 
argument in favor of getting rid of them) and we'd point users of older Qt 
versions to versions of the docs that are possibly more relevant for them 
anyway.

//! Paul

Eddy.
--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] New Qt example development guideline and revamping examples

[Topi Reiniö via Development]

Hi,

Heads up for anyone involved in the work of revamping examples and specifically 
their documentation:

We've updated the guideline for adding an example to a specific category. 
Instead of using the \meta {category} {} command directly, please use 
the newly introduced \examplecategory macro instead. This macro expands to the 
above \meta command and also adds the example to a category-specific group. 
This enables automatic listing of examples per category, as in 
https://doc-snapshots.qt.io/qt6-dev/qtexamplesandtutorials.html#application-examples.

Here's the updated part of the guideline: 
https://wiki.qt.io/Qt6/Example-Guideline#Categorisation

We've already updated existing occurrences in all qt5 submodules.

Thanks!
\topi


From: Development  on behalf of Tuukka 
Turunen via Development 
Sent: Friday, February 3, 2023 4:07 PM
To: Shawn Rutledge ; Qt Development 

Subject: Re: [Development] New Qt example development guideline and revamping 
examples


”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  on behalf of Shawn 
Rutledge via Development 
Date: Friday, 3. February 2023 at 15.56
To: Qt Development 
Subject: Re: [Development] New Qt example development guideline and revamping 
examples



On 3 Feb 2023, at 13:56, Tuukka Turunen via Development 
 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