Calligra/Schedules/3.0/Porting Plan: Difference between revisions

From KDE Community Wiki
(Initial version)
 
 
(38 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Dates =
'''See also: [[Calligra/Schedules/3.0/Porting_Notes|Detailed porting notes]]'''
__TOC__
== Dates ==
* "End of Merge window for master"^ until: Wed March 4th (proposed)
* "End of Merge window for master"^ until: Wed March 4th (proposed)
* "Porting start": same day of merge window close
* "Porting start": same day of merge window close
Line 8: Line 10:
now and get it in!
now and get it in!


= General =
== Stages of Port ==
* Porting branch named "frameworks" usually, some stuff expects it even.
Given the modular structure of Calligra not all components are in the same stage and sometimes the borders of the stages are unsharp, but ideally everyone works on the same stage
* Min Qt5 version: 5.2 (matches current KF5 min required version)
# Restoring build on Qt5/KF5: minimal port of buildsystem and all code, so everything builds at least again (using kdelibs4support and marking any temporary solution with the tag "QT5TODO". Deprecated warnings are turned off here, there are too many from kdelibs4support. Pick your back-to-build task on [https://todo.kde.org/?controller=board&action=show&project_id=73 todo.kde.org]. See for more [[#Initial_porting_steps | Initial porting steps]] - <span style="background:orange">UNCOMPLETE</span>
* Min KF5 version: 5.?
# Fixing any regressions and anything marked with "QT5TODO": to reach release state as soon as possible (so kdelibs4support usage is very fine). Tests should all pass. Deprecated warnings are still turned off - <span style="background:salmon">STARTED</span>
* Min CMake version: ?
# Porting away from kdelibs4support (only if other components are still in stage 2, but best help there). Turn on deprecation warnings in the respective subdirs with '''remove_definitions(-Wno-deprecated -Wno-deprecated-declarations)''' - <span style="background:salmon">TODO</span>
* Min ECM version: 1.?


= Porting Rules =
== General ==
* Porting branch: "frameworks"
* Min. Qt5 version: 5.2 (matches current KF5 min required version)
* Min. KF5 version: 5.7?
* Min. CMake version: 2.8.12? (proposal: min required version of used KF5)
* Min. ECM version: 1.7.0? (proposal: min required version of used KF5)
 
== Porting Rules ==
* do not port away from kdelibs4support initally, but see to get it added to the build as quickly as possible (only then go perhaps further)
* do not port away from kdelibs4support initally, but see to get it added to the build as quickly as possible (only then go perhaps further)
* ensure CI always manages to build (to ease life of co-porters)
* ensure CI always manages to build (to ease life of co-porters)
* love the tests
* love the tests
* anything that needs temporarily to be disabled by commenting out should get a tag "QT5TODO" (anything better?), so it will not be forgotton before 3.0
* anything that needs temporarily to be disabled by commenting out should get a tag "QT5TODO", so it will not be forgotton before 3.0
 
To not have people step on each other toes and do conflicting work there will be a board on todo.kde.org where people can take a product before they start working on making it build. (TODO for Friedrich)
 
= Porting Helpers =
* [https://community.kde.org/Frameworks/Porting_Notes Frameworks 5 porting notes]
* [http://api.kde.org/frameworks-api/frameworks5-apidocs/ Frameworks 5 apidox]
* [https://community.kde.org/Frameworks/Building Frameworks 5 build instructions]
* [[Calligra/Building|Building Calligra]] is still the same, just with new deps
* [http://quickgit.kde.org/?p=kde-dev-scripts.git kde-dev-scripts.git] on git.kde.org has useful porting scripts


On #kde-devel the recommendation was to not blindly run any porting scripts
== Porting Targets ==
that are available, but rather decide case-by-case if to run the script or
just do manual porting. Another reason why splitting the porting work into
different people makes more sense.
 
= Porting Targets =
Different parts of Calligra will go different miles for 3.0. Some might  
Different parts of Calligra will go different miles for 3.0. Some might  
port away from kdelibs4support as there is not a lot to do, some might be  
port away from kdelibs4support as there is not a lot to do, some might be  
Line 41: Line 35:
Important are as few regressions as possible and something that is usable :)
Important are as few regressions as possible and something that is usable :)


= Stuff that can be removed =
== Stuff that can be removed ==
* 3rdparty/kdchart/
* 3rdparty/kdchart/
* 3rdparty/kdchartpatches/
* 3rdparty/kdchartpatches/
Line 49: Line 43:
* libs/koproperty/
* libs/koproperty/
* libs/koreport/
* libs/koreport/
* plugins/reporting/  
* plugins/reporting/


kdchart & kdgantt are to be replaced by kdiagram (kchart,kgantt, ask frinring).
kdchart & kdgantt are to be replaced by kdiagram (kchart,kgantt, ask frinring).


koproperty & koreport are to be replaced by kproperty & kreport (ask jstaniek).
(DONE) db, koproperty & koreport are to be replaced by kdb, kproperty & kreport, respectively (managed by jstaniek, see [[Kexi/Porting to Qt&KF 5]]).
Removing these libs/plugins will also render some Find*,cmake macros unneeded, but best check the buildsystem before just removing them.
 
== Stuff to be done before the port ==
=== Reformatting ===
Any reformatting should be ideally done also in 2.9, to easy porting any further bug fixes.
* rename all krita files to the calligra standard. (cc -> cpp, underscore -> CamelCaps)
* from kde-dev-scripts, run:
** clean-forward-declaration.sh (remove unused forward declarations)
* from plasma-framework/src/tools/, run:
** port-qslots.sh (to port to Q_SLOTS and Q_SIGNALS)
** port-includes.sh (to get rid of the module prefixes in includes)
** port-cmake-style.sh (to get a bit more consistency)
* rest of the scripts at least for pigment and krita (boud)
 
==== Under discussion still ====
* from kde-dev-scripts, run:
** astyle-kdelibs (prevents the astyle problems with foreach and so on)
 
Notes about how to apply it:
https://docs.google.com/document/d/1jhq6oXuXKvTilJhcoS6FVKO7yYRu2yCgBS9ojhc2QRU/edit
 
Pro:
* clean code
Contra:
* "Applying full astyle is IMHO not OK, and even against efforts of everyone who keeps eye on proper coding style while doing code reviews." (jstaniek)
* "Secondly, breaking git blame is unacceptable. Unlike file renames, there's no equivalent of --follow or ignoring whitespace while patching, it's a massive irreversible break in history." (jstaniek)<br />People who try this would have to work with scripts like these [http://stackoverflow.com/questions/5098256/git-blame-prior-commits git-blame-prior-commits]
 
==== Not to be done ====
* replace all header guards with '#pragma once' <br/> "because errors with header guards are actually quite frequent, and all compilers support this pragma now." (boud)
Reason against: not part of official spec, [https://bugreports.qt.io/browse/QTCREATORBUG-7317  QtCreator fails on that], not very [http://lxr.kde.org/search?_filestring=&_string=%22pragma+once%22 spread]
 
=== Prepare architecture/technology changes ===
* That branch also contains some patches for Qt regressions (like bcd822eac52e09b6bf7a4c9fe293c9b3234a6486 or a5361d299b3991f9414466ad9d0c83537e6f2778), so it might be useful to refer to it while porting the libs, Words, Sheets and Stage.


=Initial porting steps=
Any takers?
 
== Stuff not to be done for 3.0 ==
General rules, exception as maintainers allow, but under the risk of being left out from 3.0 release
 
* Splitting up the repository some more
* Refactoring/rewrite of basic libs
* Refactoring /rewrite of apps (without having ported the app first and have it ready for release)
* Rewrite of plugins (without having ported the old version first as much as needed and ready for release)
 
==Initial porting steps==
done by 1 person
done by 1 person


Line 66: Line 103:
# Request a build on KDE CI for the "frameworks" branch
# Request a build on KDE CI for the "frameworks" branch
# Take disabled product from end of product dep tree^ and make it build:
# Take disabled product from end of product dep tree^ and make it build:
## make yours on https://todo.kde.org/?controller=board&action=show&project_id=73
## remove "UNPORTED" tag
## remove "UNPORTED" tag
## port it as much as needed to make it build
## port it as much as needed to make it build
Line 75: Line 113:
or
or
     dot -Tpng product_deps.dot > product_deps.png
     dot -Tpng product_deps.dot > product_deps.png
== Porting Plans of Subprojects ==
*[[Kexi/Porting_to_Qt%26KF_5|Porting Kexi to Qt 5 / KF 5]]

Latest revision as of 22:46, 12 January 2016

See also: Detailed porting notes

Dates

  • "End of Merge window for master"^ until: Wed March 4th (proposed)
  • "Porting start": same day of merge window close

^ To get some patches in that do not fit for the 2.9 branch and otherwise would bitrot due to the Qt5/KF5 port, there will be a merge window for master. Everyone having some WIP stuff that is good enough for merging, brush it up now and get it in!

Stages of Port

Given the modular structure of Calligra not all components are in the same stage and sometimes the borders of the stages are unsharp, but ideally everyone works on the same stage

  1. Restoring build on Qt5/KF5: minimal port of buildsystem and all code, so everything builds at least again (using kdelibs4support and marking any temporary solution with the tag "QT5TODO". Deprecated warnings are turned off here, there are too many from kdelibs4support. Pick your back-to-build task on todo.kde.org. See for more Initial porting steps - UNCOMPLETE
  2. Fixing any regressions and anything marked with "QT5TODO": to reach release state as soon as possible (so kdelibs4support usage is very fine). Tests should all pass. Deprecated warnings are still turned off - STARTED
  3. Porting away from kdelibs4support (only if other components are still in stage 2, but best help there). Turn on deprecation warnings in the respective subdirs with remove_definitions(-Wno-deprecated -Wno-deprecated-declarations) - TODO

General

  • Porting branch: "frameworks"
  • Min. Qt5 version: 5.2 (matches current KF5 min required version)
  • Min. KF5 version: 5.7?
  • Min. CMake version: 2.8.12? (proposal: min required version of used KF5)
  • Min. ECM version: 1.7.0? (proposal: min required version of used KF5)

Porting Rules

  • do not port away from kdelibs4support initally, but see to get it added to the build as quickly as possible (only then go perhaps further)
  • ensure CI always manages to build (to ease life of co-porters)
  • love the tests
  • anything that needs temporarily to be disabled by commenting out should get a tag "QT5TODO", so it will not be forgotton before 3.0

Porting Targets

Different parts of Calligra will go different miles for 3.0. Some might port away from kdelibs4support as there is not a lot to do, some might be happily using it for 3.0. Both should be very fine. Important are as few regressions as possible and something that is usable :)

Stuff that can be removed

  • 3rdparty/kdchart/
  • 3rdparty/kdchartpatches/
  • 3rdparty/kdgantt/
  • 3rdparty/kdganttpatches/
  • libs/db/
  • libs/koproperty/
  • libs/koreport/
  • plugins/reporting/

kdchart & kdgantt are to be replaced by kdiagram (kchart,kgantt, ask frinring).

(DONE) db, koproperty & koreport are to be replaced by kdb, kproperty & kreport, respectively (managed by jstaniek, see Kexi/Porting to Qt&KF 5). Removing these libs/plugins will also render some Find*,cmake macros unneeded, but best check the buildsystem before just removing them.

Stuff to be done before the port

Reformatting

Any reformatting should be ideally done also in 2.9, to easy porting any further bug fixes.

  • rename all krita files to the calligra standard. (cc -> cpp, underscore -> CamelCaps)
  • from kde-dev-scripts, run:
    • clean-forward-declaration.sh (remove unused forward declarations)
  • from plasma-framework/src/tools/, run:
    • port-qslots.sh (to port to Q_SLOTS and Q_SIGNALS)
    • port-includes.sh (to get rid of the module prefixes in includes)
    • port-cmake-style.sh (to get a bit more consistency)
  • rest of the scripts at least for pigment and krita (boud)

Under discussion still

  • from kde-dev-scripts, run:
    • astyle-kdelibs (prevents the astyle problems with foreach and so on)

Notes about how to apply it: https://docs.google.com/document/d/1jhq6oXuXKvTilJhcoS6FVKO7yYRu2yCgBS9ojhc2QRU/edit

Pro:

  • clean code

Contra:

  • "Applying full astyle is IMHO not OK, and even against efforts of everyone who keeps eye on proper coding style while doing code reviews." (jstaniek)
  • "Secondly, breaking git blame is unacceptable. Unlike file renames, there's no equivalent of --follow or ignoring whitespace while patching, it's a massive irreversible break in history." (jstaniek)
    People who try this would have to work with scripts like these git-blame-prior-commits

Not to be done

  • replace all header guards with '#pragma once'
    "because errors with header guards are actually quite frequent, and all compilers support this pragma now." (boud)

Reason against: not part of official spec, QtCreator fails on that, not very spread

Prepare architecture/technology changes

  • That branch also contains some patches for Qt regressions (like bcd822eac52e09b6bf7a4c9fe293c9b3234a6486 or a5361d299b3991f9414466ad9d0c83537e6f2778), so it might be useful to refer to it while porting the libs, Words, Sheets and Stage.

Any takers?

Stuff not to be done for 3.0

General rules, exception as maintainers allow, but under the risk of being left out from 3.0 release

  • Splitting up the repository some more
  • Refactoring/rewrite of basic libs
  • Refactoring /rewrite of apps (without having ported the app first and have it ready for release)
  • Rewrite of plugins (without having ported the old version first as much as needed and ready for release)

Initial porting steps

done by 1 person

  1. Merge "calligra/2.9" another time into "master"
  2. Branch off "frameworks" from "master"
  3. Apply https://git.reviewboard.kde.org/r/121541/
  4. Remove subdirs of stuff moved outside already
  5. Port just the buildsystem to Qt5/KF5/ECM as much as needed to get "cmake" configure pass and "make" && "make install" also pass with success, without porting any code (should be all disabled still by step 3).
  6. Create commit and push "frameworks" branch to central Calligra repo
  7. Request a build on KDE CI for the "frameworks" branch
  8. Take disabled product from end of product dep tree^ and make it build:
    1. make yours on https://todo.kde.org/?controller=board&action=show&project_id=73
    2. remove "UNPORTED" tag
    3. port it as much as needed to make it build
    4. commit to "frameworks" branch
  9. if LIB_CALLIGRA has been added to the build, tell everyone to join
    goto 8. until there is no more "UNPORTED" tag

^The dep tree of products can be either seen from content of CalligraProducts.cmake or in a picture by using the generated "product_deps.dot" in the toplevel build dir:

   dot -Tsvg product_deps.dot > product_deps.svg

or

   dot -Tpng product_deps.dot > product_deps.png

Porting Plans of Subprojects