On Fri, Jul 04, 2025 at 03:54:50PM +0200, Jochen Becher via Qt-creator wrote: > Hi,
Hi Jochen. > every time I migrate our plugins to a new QtCreator version, I run into > the same issue: > > Some concepts have changed and I have no idea how to adopt the plugin. > I must analyse the changes myself. > > Latest example: From version 15 to 16 the methods > IOptionsPage::setDisplayCategory and IOptionsPage::setCategoryIconPath > have been removed. It looks like I have to call > IOptionsPage::registerCategory now. But this is totally not obvious to > me. Understood. > Could you please write a Plugin Migration Guide and update it with > every version of QtCreator? Document all breaking changes and give a > short help how to fix it. Referencing some source code would be enough > in most cases. > > It is really not funny to struggle with one ore more cases like the > above example several times a year... Also understood. And the requests makes sense. However given the expected total effort for a complete document here I wonder whether we can get a better benefit/cost ratio somewhere between this and the current 'nothing': We could (and actually already started this week doing so), mark all "relevant" commits with a tag "Api: <from> -> <to>". In "difficult" cases there could also be a bit of explanation. At release time (or, rather more likely around beta1 time) these hints could be collected in some document and a bit hand-edited like the current ChangeLog files, and be published alongside the ChangeLogs. We could discuss what "relevant" commits are. The current idea is to cover (only) the main libraries and plugins, specifically Utils, ExtensionSystem, Core, ProjectExplorer and TextEditor, as it is unlikely that external plugins depend on more "leaf-ish" plugins. If people have further dependencies, it would be good to know which ones exactly. Besides this there's always the possibility to mark specific API with code comments '// This is used by FooBar plugin' which generally reduces the chance that these are changed without discussion to practically zero. Do you think such an approach could help to ease your pain? > Regards, Jochen Regards, Andre' -- Qt-creator mailing list Qt-creator@qt-project.org https://lists.qt-project.org/listinfo/qt-creator