Turn Grantlee into Frameworks module(s)
Closed, ResolvedPublic

Description

KF5 or KF6?
While the plan so far was to only include Grantlee for KF6, there are reasons to do that work already before KF6:

  • the KF6 plan also includes some redesigns at least on repo level, so being able to gather experience with the new design before allows to have a clean and perfect version right on the start of KF6
  • a version in KF5 allows Grantlee users to port already now to the KF variant and all it potential differences to the current Grantlee, reducing the workload at the actual Qt6/KF6 port

Current state
Grantlee itself consists of two independent libraries:

  • Grantlee::Templates, a text-template system based on Qt introspection
  • Grantlee::TextDocument, a builder design pattern implementation for processing QTextDocuments

KDE has the GrantleeTheme project, extending Grantlee with generic features as loading templates from the Qt resource system, a localizer variant using KF's KI18n and support for "icon" tag in templates.

Known Grantlee users (December 2019):

$ apt-cache rdepends libgrantlee-templates5
libgrantlee-templates5
Reverse Depends:
   libgrantlee5-dev
   skrooge
   rocs
   libkf5pimcommon5abi3
   libkf5messageviewer5abi5
   libkf5messageviewer-plugins
   libkf5kaddressbookgrantlee5
   libkf5grantleetheme5
   libkf5grantleetheme-plugins
   libkf5calendarutils5abi1
   libkf5calendarutils-bin
   kdepim-addons
   kjots
   khelpcenter
   kdevelop52-libs
   kdevelop
$ apt-cache rdepends libgrantlee-textdocument5
libgrantlee-textdocument5
Reverse Depends:
   libgrantlee5-dev
   libkf5pimtextedit5abi3
   libkf5messageviewer5abi5
   libkf5messagecomposer5abi2
   kjots

As of October 2021, libgrantlee-textdocument5 only has 1 user, KJots. KPimTextEdit has a fork since 5d4095836ef32e941479133015ae19fc003318ef,

Plans for new design:
The following so far are current ideas to develop off from:

Namespace: keeping "Grantlee" for the template library

While dropping the name Grantlee name has been proposed, possibly in favour of generic K & KF, given the otherwise generic terms in the API like "text", "template", etc., the use of "Grantlee" (and thus its associated solution space and features) removes the need for having to use more generic terms to differentiate the library and classes from other things dealing with text and templates.

So the namespace Grantlee would be kept, for the Grantlee::Template library though only. But it also means extra work needed to ensure no naming clashes with the old grantlee libraries in builds (cmake config, library names) and at runtime (symbol names), by whatever approaches.

The Grantlee::TextDocument should see a new dedicated namespace though, being in a different solution space.

Library/plugin distributions over repos: two separate KF modules

The library Grantlee::Templates is used by many consumers without its silbling Grantlee::TextDocument. To ease usage by packagers and bundled app builds, having it in its own repo and responding release tarballs, without further build flags needed, should improve experience and thus help reuse. Names would be "grantlee" for the repo, "KF5Grantlee" for the library.

The library Grantlee::TextDocument would be split into a second repository. Names would be "?" for the repo, "?" for thel ibrary (placeholder "KF5GrantleeTextDocument" right now). As there is currently only one user with kjots, and kpimtextedit having a fork, to speed things up kjots gets a fork as well for now. From both forks and the original a new dedicated library is then developed with all patience.

Execution plan:

Target releases:
Given most consumers of Grantlee as PIM projects, part of KDE Gear release cycle, current target for execution is to have KF modules part of KF releases in time for KDE Gear 21.12, which means KF 5.88 begin of November.
The Grantlee::TextDocument successor would be done at a later time.

Artifacts:
https://gitlab.com/kossebau/grantlee for now serves as repository to collect the initial work (invent.kde.org has some commit check hooks not happy with existing commits, with more to be added, move to invent.kde.org planned once all are in).

TODO list:

  • commits to github grantlee (modulo buildsystem & code reformat)
  • commits from earlier kf-import work, found at https://github.com/kde/grantlee
  • commits from Cuteless
  • missing license headers -> https://github.com/steveire/grantlee/pull/75
  • switching to SPDX license headers (commit prepared, but needs ^ first in)
  • create full template-only repo (either by repo split or deleting the textdocument subdir)
  • run clazy/clang-tidy a bit more over the codebase, at least for catching any BC affecting issues before the first release
  • reformat with KF format rules (to be done as last step before first release in case upstream/forks have more patches/commits to pick)

Repos that need porting
KDE Gear:

Own release schedule:

External:

Background:
Stephen Kelly in December 2019 proposed to include his Grantlee project into KDE Frameworks:
https://marc.info/?l=kde-core-devel&m=157566819811019&w=2
The initial discussion how to do that ended with Stephen deciding he rather would want that happen for KF6 only: https://marc.info/?l=kde-frameworks-devel&m=157757468828735&w=2

Meanwhile upstream development has fully stalled, e.g. https://github.com/steveire/grantlee/pull/70 never getting any reaction. Which triggered the Cutelyst project to even fork it as a new Cutelee project: https://github.com/cutelyst/cutelee. Cutelyst might be interested to switch to a KF version of Grantlee, but as they already need Qt6 support now, that might only happen in KF6 time.

kossebau created this task.Sep 19 2021, 2:38 PM
kossebau updated the task description. (Show Details)Sep 27 2021, 1:28 PM
kossebau updated the task description. (Show Details)Sep 27 2021, 1:35 PM
kossebau updated the task description. (Show Details)Sep 30 2021, 5:07 PM
kossebau updated the task description. (Show Details)
kossebau updated the task description. (Show Details)Oct 3 2021, 12:48 AM
kossebau updated the task description. (Show Details)Oct 3 2021, 1:49 PM
kossebau updated the task description. (Show Details)Oct 4 2021, 9:34 PM
kossebau updated the task description. (Show Details)Oct 4 2021, 10:37 PM

Hi,
when you will move "https://gitlab.com/kossebau/grantlee" in invent.kde.org is it possible to keep git history ?
Regards

when you will move "https://gitlab.com/kossebau/grantlee" in invent.kde.org is it possible to keep git history ?

Keeping the history would be my plan, yes. That is why I juggle with commits on the separate repo for now, to keep those as clean as possible. Planning though to move to invent end of this week, as no bigger changes are expected now by me

kossebau updated the task description. (Show Details)Oct 5 2021, 11:10 PM

Hi,

Any updates on this task?

Any progress on Grantlee?

kossebau closed this task as Resolved.Aug 24 2022, 5:01 PM
kossebau claimed this task.

Any progress on Grantlee?

The author of Grantlee, @skelly , is discontinuiing Grantllee for Qt6, to be substituted by KTextTemplate. Please see the link in the comment before your comment.

I should close this task though, given it was about a different approach, so people are not confused any more.