I spent my weekend working this out so hopefully it'll help someone else when they look. Once you know what to look for and what to change it's quite mechanistic. There are really only a few things that need changed. But it's hard to find it all set out in one place and easy to keep trying different combinations. If you follow these rules then it should work without too much extra debugging.
For me the key was only changing the extension of the class even although it was tempting to adjust lots of the code!
Upgrading from version 2.5 to 3.x
I’m assuming the component is already installed and that it worked on 2.5. I was upgrading a site to 3.8 so I upgraded the site and then came back to upgrade the component (this might not work in your case especially if a 2.5 component has plugins and aren't compatible with 3.x - in that case I suggest delete the plugins and sort it out once the upgrade to Joomla is complete).
Go to the root of the component and find the componentname.php file.
There will be a line which has JController this needs changed to JControllerLegacy
$controller = JControllerLegacy::getInstance(‘RelevantView’);
Next go the the controller.php (also in the root) change the class to be extended JControllerLegacy
class ComponentNameController extends JControllerLegacy {
If you have sub controllers ( in a controllers folder) you need to make sure that the extension of the class is:
For list view JControllerAdmin
For single view JControllerForm
Next go to the models folder. For each model:
For list view JModelList
For single view JModelAdmin
Finally go to the views and the view.html files.
All of these should use JViewLegacy
class ComponentNameViewLetter extends JViewLegacy {
There are some other things like JUtilty and JRequest that have been deprecated that might throw errors you should sort them on a case by case basis. See here:
https://docs.joomla.org/Potential_backward_compatibility_issues_in_Joomla_3_and_Joomla_Platform_12.2