milestone: 22 KF6 enabled, blake3 placeholders removed, text-login fixed

- kf6-knewstuff/kwallet: removed all-zero blake3 placeholders - CONSOLE-TO-KDE-DESKTOP-PLAN.md: 20→22 KF6 enabled count - BOOT-PROCESS-IMPROVEMENT-PLAN.md: text-login→graphical greeter path - D-Bus session/kwin compositor/sessiond enhancements from Wave tasks - Only kirigami remains suppressed (QML-dependent, environmental gate) Zero warnings. 24 commits total.
2026-04-29 14:48:47 +01:00
parent cb2e75e640
commit edb68153e3
621 changed files with 1034826 additions and 223 deletions
@@ -0,0 +1,21 @@
+Utility classes, useful also outside of KNewStuff2:
+ KTranslatable
+ Security
+
+Container classes:
+ Author
+ Entry
+ Provider
+ Category
+ Feed
+ Installation
+
+Parser/dumper classes:
+ EntryHandler
+ ProviderHandler
+
+Engine classes (asynchronous, therefore qobjects):
+ EntryLoader
+ ProviderLoader
+ CoreEngine
+
@@ -0,0 +1,146 @@
+KNewStuff2 Engine Design
+========================
+
+The KNewStuff2 engine is one of the central pieces of activity of the
+KNewStuff2 library. First and foremost, it handles the synchronization of
+data on the internet with data on the local hard disk. The local data
+might come from previous downloads, but also from (initial) installation.
+
+On startup, after being initialized to use a certain configuration,
+the engine loads up potentially dozens of files. This will require some
+activity on the harddisk, but will speed up network operations by quite
+a bit afterwards.
+
+There are three groups of files being loaded: the cache for providers,
+the cache for entries, and the registry of entries.
+The first two ones may contain all data about providers and entries
+ever downloaded by KNewStuff2. The cache doesn't have to survive
+machine reboots, but should generally live very long. A strategy for
+file replacements and invalidation will have to be found.
+The third group contains all the entries which are currently installed.
+This group starts out empty, or with some initial system-wide installed
+files. For every download, the corresponding cache file (which exists) is
+copied to the registry dir, afterwards the cached file isn't strictly
+needed anymore. Such files might also be removed again, in case the referenced
+data is deinstalled.
+
+Entity         | Loading                 | Root tag
+---------------+-------------------------+---------
+               |                         |
+provider cache | file(s)                 | <ghnsproviders>
+               |                         |
+entry cache    | directory(ies)->file(s) | <ghnscache>
+               |                         |
+entry registry | directory->file(s)      | <ghnsinstall>
+
+Directly after a download, the downloaded files are scanned for their
+objects (providers or entries), which are added to the in-memory cache.
+By doing so, they might replace older cached entries. For all those older
+entries which are already installed, their status is marked as updateable.
+
+On shutdown of the engine, e.g. when deleting the object, the whole
+cache in memory is freed, but the cache files remain of course.
+
+KNewStuff2 Workflow
+===================
+
+There are two main workflows with KNewStuff: Uploads and downloads. Together
+and repeated over time, these workflows form the data sharing cycle.
+In addition, when DXS is used, some direct interaction with the service is
+possible, which adds a few workflows. Those will be explained after upload
+and download.
+
+Uploads
+-------
+The engine fetches information about the providers which accept uploads for
+a certain mime type or data type. Basically, the list of providers is taken
+minus those who do not support uploads, because not all of them do.
+A provider selection dialog lets the user select one of the remaining
+providers. In case no upload is possible at all, a webpage with uploading
+capabilities or at least information about contact by e-mail may be offered
+by at least one provider. This so-called 'noupload' fallback page will be
+displayed in a browser to the user.
+
+If upload is available, the upload dialog pops up. In it, metadata about the
+upload can be edited. Some of it (especially preview images) might be preset
+already by the application.
+Upload then happens through the engine again. The upload might require
+authentication, which is handled transparently.
+
+When server-side versioning is activated, then no version number needs to be
+given by the user for updates to existing entries.
+
+Downloads
+---------
+Similar to uploads, all providers suitable for the application's data types
+are loaded. However, they appear in parallel, whereas only one provider is
+selected for uploads. Each provider might offer different data types, some
+matching those needed by the application, some rather not. The provider's
+download URL is used to download meta information about all entries, and those
+whose data type is not of interest are filtered out.
+The provider can offer "tagged" download URLs, the so-called feeds, for
+the latest entries, the highest rated ones, or certain other criteria. When
+this is the case, the generic download URL is not used, and instead the
+feeds are offered to the user as alternative selections, e.g. by being
+displayed as tabs on a dialog.
+
+Entries provide meta information which can be viewed, and which might include
+a preview image. They also reference the data itself, which is called payload.
+Installing the payload means downloading the data, and running it through
+a series of checks and installation steps. The data integrity is checked for
+using hash sums and digital signatures, if available. The installation routine
+moves the data file to its correct location, probably involving decompression,
+unpacking and the emission of signals.
+
+For each downloaded and installed entry, the meta information is kept in an
+entry registry. In general, all entries and providers are cached.
+Deinstallation works the other way around: The meta information is read,
+the data deleted and the meta file also deleted afterwards.
+
+Direct interaction
+------------------
+As opposed to upload and download, all other workflows are only possible when
+the provider supports DXS. Such interaction includes:
+* Translation. An entry is referenced and a translation for it is submitted
+  to the server. Translations might end up in an admin queue or be applied
+  directly, depending on the site configuration.
+* Request for removal. Entries which are deemed unnecessary or offending
+  are scheduled for removal into an admin queue.
+* Comments. Comments can be added (again ending up in a queue or applied
+  directly), but they can also be requested for viewing.
+* Several others. See short descriptions in the feature guide.
+
+Library structure
+=================
+
+Proposed structure:
+knewstuff/knewstuff2/core - conventional ghns + coreengine
+knewstuff/knewstuff2/dxs  - dxs + dxsengine
+knewstuff/knewstuff2/ui   - dialogs
+knewstuff/knewstuff2      - workflow wrapper (engine)
+knewstuff/tests           - test applications
+knewstuff/data            - icons and other data
+knewstuff/doc             - documentation
+
+Under review:
+plasmagik/                - packaging handler
+
+
+knsrc file format:
+[KNewStuff2]
+Name=
+ProvidersUrl=
+TargetDir/InstallPath/etc=
+Uncompress=always/never/archive/subdir
+CachePolicy=never/resident/only/replaceable
+Categories=foo,bar
+
+[foo]
+TargetDir/InstallPath/etc=
+Uncompress=...
+CachePolicy=
+
+[bar]
+# empty, then use defaults
+
+
@@ -0,0 +1,63 @@
+How do providers, categories, feeds and entries correlate?
+And authors on top of that?
+
+Authors are simple: each entry is linked to one author, even if the
+author is the same the objects differ. We can change this in the future,
+right now there is no need to do that.
+The other objects are a bit more difficult.
+
+DXS: provider -> category -> feed/list -> entries
+GHNS: provider -> feed [with categories] -> entries
+
+Example
+-------
+
+The maintainer of an application offers extensions in the categories
+"image" and "script". Since the application has a lot of users, both
+kde-coolextensions.org and kde-betterextensions.org offer such extensions.
+The provider.xml file would thus contain the two <provider>s. When fetching
+the feed files for most popular/most downloaded/most recent, those files
+need to contain entries of *all* categories! A workaround is to add virtual
+providers for each category (there won't be much difference in the UI), but
+ideally with frameworks such as Hotstuff the right number of items will be
+inserted into the feed.
+With DXS, the problem doesn't exist since DXS fetches all categories first
+and then the feeds for each category. DXS also allows to retrieve all entries
+of a certain category, so it is much more flexible in general.
+
+GHNS setup:
+-----------
+ provider kde-coolextensions.org
+  feed most-recent
+   entry a [category image]
+   entry b [category script]
+   ...
+  feed most-downloaded
+  ...
+ provider kde-betterextensions.org
+  ...
+
+Alternative GHNS setup:
+-----------------------
+ provider kde-coolextensions.org/image
+  feed most-recent
+   entry a [image]
+   entry c [image]
+   ..
+  ..
+ provider kde-coolextensions.org/script
+  ...
+
+DXS setup:
+----------
+ provider kde-coolextensions.org
+  category image
+   feed most-recent
+    entry a [image]
+    entry c [image]
+    ...
+   ...
+  ...
+ provider kde-betterextensions.org
+  ...
+
@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: none
+# SPDX-License-Identifier: CC0-1.0
+
+### KApiDox Project-specific Overrides File
+
+# define so that deprecated API is not skipped
+PREDEFINED += \
+    "KNEWSTUFFCORE_ENABLE_DEPRECATED_SINCE(x, y)=1" \
+    "KNEWSTUFFCORE_BUILD_DEPRECATED_SINCE(x, y)=1" \
+    "KNEWSTUFFCORE_DEPRECATED_VERSION(x, y, t)=" \
+    "KNEWSTUFFWIDGETS_ENABLE_DEPRECATED_SINCE(x, y)=1" \
+    "KNEWSTUFFWIDGETS_BUILD_DEPRECATED_SINCE(x, y)=1" \
+    "KNEWSTUFFWIDGETS_DEPRECATED_VERSION(x, y, t)=" \
+    "KNEWSTUFF_ENABLE_DEPRECATED_SINCE(x, y)=1" \
+    "KNEWSTUFF_BUILD_DEPRECATED_SINCE(x, y)=1" \
+    "KNEWSTUFF_DEPRECATED_VERSION(x, y, t)=" \
+    "KNEWSTUFF_DEPRECATED_VERSION_BELATED(x, y, xt, yt, t)="
@@ -0,0 +1,48 @@
+This is how the KNS::Engine works....
+it is a higher-level view which does not talk about KNS::DxsEngine
+or KNS::CoreEngine yet, those will be documented later.
+
+General
+-------
+
+The KNS::Engine class is the only class that applications need to care
+about (beside the information from *.knsrc files of course).
+As such, this class should be as comfortable as possible.
+
+There are two principal operations supported by it, upload and download.
+Other operations, especially direct interaction through DXS, is also
+handled by it since it inherits from DxsEngine.
+
+Both principal operations have a modal and a non-modal way of being called.
+The modal way is the easiest one and translates the old
+	KNS::DownloadDialog::open()
+call from KNewStuff1 to the new
+	KNS::Engine::downloadDialogModal()
+call in KNewStuff2. Similarly, calling ::uploadDialogModal() handles all
+upload in a modal way, without the need for signals and slots.
+
+The modal calls return the list of affected entries directly. These entries
+should be queried about their status for installed, removed and updated
+entries in the download dialog, and a single entry returned for the upload
+dialog.
+The non-modal calls will send signals for each affected entry.
+
+Upload
+------
+
+The state machine for modal upload is as follows:
+
+* provider loading
+  * failure(*) -> stop
+  * finish(*) -> next/provider selection
+  * provider(1) -> discard
+* provider selection
+  * reject -> stop
+  * accept -> next/meta data selection
+* meta data selection
+  * reject -> stop
+  * accept -> next/upload
+* upload
+  * failure -> stop
+  * success -> stop + result
+
@@ -0,0 +1,31 @@
+How to identify entries
+-----------------------
+
+The KNS2::CoreEngine uses id() for entries and pid() for providers to find out
+a unique identifier which can be used to compare one of them to another one of
+the same kind.
+
+In KNS1, the name and the payload URL were used to compare the entries, as
+they're guaranteed to exist. In KNS2, the internationalised nature of those
+tags is honoured.
+The proposed comparison algorithm is hence called "internationalised
+identification" (i18n-id) and is already implemented by Hotstuff.
+It will also be implemented by KNewStuff2.
+
+How does i18n-id work?
+Out of all the tags of an entry, one is taken randomly. Its content together
+with its language form the identity tuple. When an entry is to be compared,
+the tag with the same language as used in the id is used for comparison.
+Note that i18n-id works even in the absence of a language attribute. However,
+in GHNS, a language attribute will almost always be present. It'd be naive to
+throw information away when it is present already.
+
+What i18n-id assumes is that translations never vanish, once added. It would
+of course be trivial to extend the algorithm to check through all of the
+languages once present, hence it would work as long as at least one
+translation is kept.
+
+What i18n-id achieves is that one doesn't have to rely on "unique ids"
+maintained by the server, which would definitely change if repositories are
+merged.
+
@@ -0,0 +1,44 @@
+KHotNewStuff2  Application use-cases:
+
+Wallpaper 
+
+Wallpapers are installed to a shared location (share/wallpapers) and many 
+interfaces might want to invoke KNS Download Dialog to get them (desktop containment config
+window, maybe kdm, other containment config windows, maybe the frame widget config dialog.
+
+
+Vocabulary
+
+Vocabulary files can be shared by a few applications, those that want to share install
+their files to share/apps/kvtml/ optionally in a locale sub-folder.  Each app currently
+has it's own provider and it's own data files, but they can all use each others files.
+
+
+Color Schemes
+
+ColorSchemes are installed to a common place, and are only invoked from the colors kcm module.
+
+
+Game apps
+
+Game apps probably will want to have different categories in it's knsrc file so it can use one
+knsrc file (and one download dialog) to download themes and levels (maybe?).
+
+
+
+KHotNewStuff2  End-user use-cases:
+
+Extendability:
+
+Fred, Sysadmin for school X is asked by language teachers to set up a KNS provider for them to
+upload vocabulary files to on their website, and have it be accessible by registered students from
+home.
+
+
+
+System installs:
+
+Fred is then asked to install all the teacher's uploaded vocab files onto each machine at the lab
+at school for students to have them accessible, each student has their own home folder, but Fred
+doesn't want to install to each person's folder, so uses the "Install to share" option, and they
+are installed to system folder, since his user has rights to write there.
@@ -0,0 +1,6 @@
+#!/bin/sh
+
+for i in *.dia; do echo $i; dia --export=$i.png --filter=png --nosplash $i; done
+
+#for i in *.dia; do echo $i; dia --export=$i.png --export-to-format=png --nosplash $i; done
+
@@ -0,0 +1,16 @@
+This file lists known packaging formats/drafts so we know if
+we need to do anything about it (e.g. provide convenience APIs
+for some packages).
+
+Plasma: https://techbase.kde.org/Projects/Plasma/Package
+
+GGZ level packs: /playground/gamedata/README.gamedata in GGZ SVN
+
+... (TODO: find out structure of KNewStuff1 packages)
+
+I considered also:
+* Artworks
+* Kross
+* QtScript
+* Custom (standard KGHNS2 package, supported additions app-specific)
+
@@ -0,0 +1,50 @@
+KNewStuff2 Porting Information
+==============================
+
+«Where did all the classes go?»
+
+data/
+ (GHNS format schemas and example data)
+ -> see http://ghns.freedesktop.org/spec/ now
+
+downloaddialog.*
+uploaddialog.*
+providerdialog.*
+ (graphical dialogs)
+ -> upload/providerdialog still used, in knewstuff2/ui/
+ -> the download dialog is the one from okular
+ -> the old knewstuff1 download dialog is gone
+
+ghns.*
+testnewstuff.*
+ (test applications)
+ -> see tests/ for some new tests (has its own README.tests)
+
+entry.*
+provider.*
+ (entities/data handling classes)
+ -> see knewstuff2/core/
+ -> author, feed and category are now additional entities
+
+security.*
+ -> see knewstuff2/core/
+
+knewstuffbutton.*
+ -> TODO
+ -> will go to knewstuff2/ui/ (there's already kdxsbutton)
+
+engine.*
+ (non-graphical upload/download functionality)
+ -> there are 3 engine classes now
+ -> the one in knewstuff2/core/coreengine.* is similar
+ -> but it also handles installation and caching
+ -> the one in knewstuff2/dxs/dxsengine.* implements DXS
+ -> the one in knewstuff2/engine.* is for applications (use only this one!)
+
+knewstuff.*
+knewstuffgeneric.*
+knewstuffsecure.*
+  -> doesn't exist anymore
+  -> inherited from it? bad luck, was discouraged by tutorial
+  -> all custom installation etc. is now handled by *.knsrc files
+