Migrating from Qt3 to 5.15.13

[DevMattew]

My responsibility is to migrate a software suite comprising five internal libraries, which were created using Qt and are used by over 100 executables, from Qt 3 to Qt 5.15.13. This suite has been developed over a period of more than 20 years.
The main objective is to ensure complete functional and graphical non-regression.
These five libraries are used by several developers within the company and form the core of all our programs.
Fifty legacy Qt and Qwt objects are listed below.
More than three developers have been working on this migration project for over three years.
I have been working on the project for a year and have just started to put my first programs into production.
This is my first real full-time professional experience as a developer.
Several factors make the migration process very complicated.
The code is uncommented, and the development mentality is quick & dirty.
I am at a stage where this initial task has taken a long time. I feel that we are close to achieving our goal, but I am also now faced with lots of small behavioural bugs, and each problem is becoming increasingly difficult to solve.
I am explaining all this to you in order to find solutions and explore new avenues. If you need any more information, please do not hesitate to ask.
Thank you for reading and have a good day.

• QAbstractTableModel
• QApplication
• QBoxLayout
• QCheckBox
• QColor
• QComboBox
• QDateEdit
• QDialog
• QDomDocument
• QDomElement
• QFile
• QFont
• QFrame
• QGridLayout
• QGroupBox
• QHash
• QLabel
• QLineEdit
• QList
• QMainWindow
• QMenu
• QMultiMap
• QObject
• QPainter
• QPoint
• QPolygon
• QPrinter
• QProgressBar
• QPushButton
• QRadioButton
• QRect
• QScrollArea
• QSize
• QSlider
• QSortFilterProxyModel
• QSplitter
• QString
• QStyledItemDelegate
• QTabWidget
• QTableView
• QTcpServer
• QTcpSocket
• QTextEdit
• QTime
• QTimeEdit
• QTimer
• QTreeWidget
• QTreeWidgetItem
• QValidator
• QVariant
• QWidget
• QwtPlot
• QwtScaleDraw

[jsulm]

@DevMattew said in Migrating from Qt3 to 5.15.13:

Fifty legacy Qt and Qwt objects are listed below.

What do you mean by "legacy"? These classes are still there in Qt5.
You should do the porting in two steps:

1. Port to Qt4, use qt3to4 tool to make this step easier
2. Port from Qt4 to Qt5, this step should be easier

[DevMattew]

These custom classes based on Qt are still present after 20 years of development. :/
Everything already works under Qt5, but there are still a lot of tiny regressions.
Behaviours that have changed and that only users notice as they go along, which makes the task very time-consuming.

[Pl45m4]

@DevMattew said in Migrating from Qt3 to 5.15.13:

The code is uncommented, and the development mentality is quick & dirty.

We all know what this feels like :)
Good and easy in the short term, regrettable in the long term.

Even though all these classes exist in Qt5 (and mostly Qt6), you can't expect them to be consistent. From Qt3 -> Qt4 -> Qt5 there will be a lot that got cancelled/removed, renamed/changed or is "now" a bad practise.
And I don't know whether or not the auto porting tools will cover all this.
If you are at Qt5 already and everything compiles, you have won half the battle.

but I am also now faced with lots of small behavioural bugs, and each problem is becoming increasingly difficult to solve.

Do you know what exactly behaves differently or where it happens?
Maybe you want to ask more specific questions later...
Unless it involves (secret) business logic, it should be possible to solve the problem.

[Ronel_qtmaster]

@DevMattew This is a very long and complex task. If you need assistance feel free to contact Me

[JKSH]

@DevMattew said in Migrating from Qt3 to 5.15.13:

from Qt 3 to Qt 5.15.13

May I ask:

1. What motivated your company to begin this migration?
2. Why did you choose Qt 5 as your end-point? Qt 5 reached end-of-life in March 2025.

This is my first real full-time professional experience as a developer.
...
The code is uncommented, and the development mentality is quick & dirty.

This is not a fun combination. Such code is time-consuming to migrate, even for experienced developers.

@DevMattew said in Migrating from Qt3 to 5.15.13:

Everything already works under Qt5, but there are still a lot of tiny regressions.
Behaviours that have changed and that only users notice as they go along, which makes the task very time-consuming.

Yes, so treat this as a project that will last another 20 years.

Each time you fix a regression (or any other bug), add an automated unit test for what you just fixed, so that any further regressions will get caught automatically (For example, you might fix one area now, but then it breaks again when you're trying to fix another area -- automated testing will help you catch such cases quickly).

Start paying off the technical debt that has been building up over the past 20 years (all that quick-and-dirty coding). Add comments; refactor; simplify; clean up code without changing behaviour -- all these activities are much easier than migrating to a new version of Qt/Qwt. Remember to add unit tests for the parts that you touch. Even if this doesn't advance your migration efforts directly, it could make the migration easier down the track (and it will help you maintain your libraries over the next 20 years). It also helps you to gain deeper understanding of your libraries and of Qt, which improves your future work.

If you're not using a bug tracker, start using one. Collect your users' reports about the "tiny regressions". Close the bug reports as you fix things. Even if this doesn't advance your migration efforts directly, it helps you to see your progress and keeps you from drowning in despair.

I am at a stage where this initial task has taken a long time. I feel that we are close to achieving our goal, but I am also now faced with lots of small behavioural bugs, and each problem is becoming increasingly difficult to solve.

Release new versions even if you haven't fixed everything 100% (you can use v2.0.0-beta1, v2.0.0-beta-2, v2.0.0-beta3...) For each release, keep a list of known issues and fixed bugs.

Even when you haven't reached the quality needed for the final release, get some of your colleagues to help you test things anyway (choose a variety of people who care about different parts of your 100 executables -- this helps you to get extensive test coverage without involving the entire company)

[DevMattew]

@Ronel_qtmaster I appreciate thanks a lot

[DevMattew]

@Pl45m4 Thanks for responding. It happens in a very specific situation where I have to ensure a perfectly transparent migration.
For example:
We have a custom objects who herits from QButtonGroup in Qt3 & 5.
In many programs, this custom object is used to create buttons groups of different types, such as radio buttons and checkboxes.
In Qt3, radio buttons are mutually exclusive by default, meaning you can only click on one at a time. Checkboxes, on the other hand, are not mutually exclusive, so you can select multiple options.
In Qt5, however, radio buttons are not exclusive by default.
This is a simple task, but I have to do it all day and it's very time consuming for many different Qt object.

[DevMattew]

1. What motivated your company to begin this migration?

Much of the code that runs the company today is based on Qt3, and development of this is ongoing. They have invested heavily in these libraries.
Also to catch up on technical debt and utilise the new features of Qt.

2. Why did you choose Qt 5 as your end-point? Qt 5 reached end-of-life in March 2025.

The migration project started three years ago.
Fun fact: when I took on this mission, someone gave me the entire project and the folder was named xxxx-Qt6, but the compiled version of Qt was actually 5.15.11.

This is my first real full-time professional experience as a developer.
...
The code is uncommented, and the development mentality is quick & dirty.

This is not a fun combination. Such code is time-consuming to migrate, even for experienced developers.

@DevMattew said in Migrating from Qt3 to 5.15.13:

Everything already works under Qt5, but there are still a lot of tiny regressions.
Behaviours that have changed and that only users notice as they go along, which makes the task very time-consuming.

Yes, so treat this as a project that will last another 20 years.

Yes, of course.

Each time you fix a regression (or any other bug), add an automated unit test for what you just fixed, so that any further regressions will get caught automatically (For example, you might fix one area now, but then it breaks again when you're trying to fix another area -- automated testing will help you catch such cases quickly).

Start paying off the technical debt that has been building up over the past 20 years (all that quick-and-dirty coding). Add comments; refactor; simplify; clean up code without changing behaviour -- all these activities are much easier than migrating to a new version of Qt/Qwt. Remember to add unit tests for the parts that you touch. Even if this doesn't advance your migration efforts directly, it could make the migration easier down the track (and it will help you maintain your libraries over the next 20 years). It also helps you to gain deeper understanding of your libraries and of Qt, which improves your future work.

If you're not using a bug tracker, start using one. Collect your users' reports about the "tiny regressions". Close the bug reports as you fix things. Even if this doesn't advance your migration efforts directly, it helps you to see your progress and keeps you from drowning in despair.

I completely agree with your way of thinking.
I will try to devote more time to understanding the project as a whole and adding unit tests or commenting on refactored code, even if it does not directly advance my migration.
I mentioned unit testing, but I was told that it didn't align with the company's mindset. The same goes for comments in the code, but I'll add them anyway and take a look at the bug tracker.

I really appreciate your reply and all your advice.

[Pl45m4]

@DevMattew said in Migrating from Qt3 to 5.15.13:

We have a custom objects who herits from QButtonGroup in Qt3 & 5.
[...]
In Qt5, however, radio buttons are not exclusive by default.

Once they are part of a QButtonGroup they are. So this should not make any difference if you have a group anyway.

@DevMattew said in Migrating from Qt3 to 5.15.13:

Fun fact: when I took on this mission, someone gave me the entire project and the folder was named xxxx-Qt6, but the compiled version of Qt was actually 5.15.11.

Maybe the plan was to migrate to Qt6 (which I also would recommend when you reached a point of a "running" Qt5 build), but the installed version at that time was Qt5.15...

@DevMattew said in Migrating from Qt3 to 5.15.13:

I mentioned unit testing, but I was told that it didn't align with the company's mindset. The same goes for comments in the code, but I'll add them anyway and take a look at the bug tracker.

Doing things quick & dirty is very common and no shame... but refusing to fix it when you re-visit the code again anyway during the migration process is stupid...
Because the whole idea of "quick and dirty" is to, hopefully, come back to it later and clean things up, which - unfortunately - does not happen very often :)

Good luck :)

[JKSH]

@DevMattew said in Migrating from Qt3 to 5.15.13:

I mentioned unit testing, but I was told that it didn't align with the company's mindset. The same goes for comments in the code

That's very unfortunate... (I agree with @Pl45m4's sentiment)

On one hand, the tips above are based on general best practices for software engineering, which increase the chances of long-term project success. On the other hand, you have to to do what you're paid to do (and it sounds like they don't want to pay you to write unit tests and comments...)

Furthermore, "senior" developers might not appreciate "newcomers" who change how things are done, even if it improves the software's robustness. So, it sounds like you're in a precarious position, and you likely need to develop your political savviness more than your software engineering skills. (For example, what will you do if your attempts to add tests/comments are seen as "arrogance"/"disobedience" by your colleagues?)

All the best to you.

[DevMattew]

I added the architecture.md file mainly to help me understand the structure of the project. The team felt that if no one else was using it, it wasn't worth keeping, which I completely understand. I told them to delete it; I'll just keep a copy for myself.

It's the same use case for unit tests. I know there are pros and cons to both approaches, but since testing is part of my routine, I'm going to write them anyway. If the team doesn't want to include them in the main repository, that's fine, I'll just use them for my own peace of mind.
And i think they understand the complexity of the task and as you say "it helps you to see your progress and keeps you from drowning in despair."

Many thanks.

[DevMattew]

@Pl45m4 many thanks

[SGaist]

@DevMattew hi,

If they are that allergic to tests, I would create a test bed in a parallel project that you can keep in sync with the main one using a submodule so you can ensure that your code stays working as expected.

[lukas_kosinski]

Well, I am surprised to hear that someone might want to exclude unit tests.
The project is going to grow. It always does. It's not possible to remember every little aspect of the project.
And if the team changes and someone new joins, how on earth are they going to make sure there is no butterfly effect in a huge and old codebase that they do not know?

That's sad.

It reminds me of a similar situation I had a long time ago as a young programmer, saying that we need CI/CD and unit tests.

[DevMattew]

@SGaist hello,
Yes, that's probably the best way to avoid an endless discussion about unit-test.

[DevMattew]

@lukas_kosinski They don't want to waste time on that ..