A case of premature removal of the "pyocd-flashtool" command

[pfalcon]

Some feedback about removal of the "pyocd-flashtool" command (entrypoint) in pyocd 0.30.

0.13 is the version of PyOCD shipped in stabled release of Debian and related distributions, like Ubuntu:

• https://packages.debian.org/search?keywords=pyocd&searchon=names&suite=buster&section=all
• https://packages.ubuntu.com/search?suite=focal&searchon=names&keywords=pyocd

Thus, version 0.13 is the version using which many users get acquainted with PyOCD, and which is used in many deployments "by default" (users upgrade to another version, bypassing distro package manager, only when face a pressing need to do so, e.g. need to use one of the newer boards not supported in previous versions).

And the version 0.13 lacked the "multiplex" pyocd executable, and instead provided a few action-specific executables, among them pyocd-flashtool. Now with 0.30, there's the opposite situation - there's no pyocd-flashtool command, and it's requirement to use pyocd flash instead. In other words, it's not possible to use pyocd's version shipped in popular distros, and the latest version with the same command line - users would always need to look back and figure out which version they currently have. And all that without any real change in functionality - from user point of view, the only difference is support for more boards, and otherwise pyocd-flashtool and pyocd flash are doing exactly the same thing.

This is especially painful for integration projects concerned with user ease of use. For example, we integrate PyOCD in Linaro LAVA. As any complex integration project, we try to rely as much as possible on the distro packages, as it makes it easier both for users and for us (otherwise a system easily becomes mish-mash patchwork). And yet we'd like to support newer tool version too. And in the case of PyOCD, we can't - we have to decide whether to support known stable version shipped by the distro, or the newer version, but not both. And supporting newer version isn't that easy either, as we again ship and QA a complete integrated package, where all parts fit together, for example attempt to support 0.30's "pyocd flash" breaks CI, as we actually test it (against standard distro package, which is again 0.13): https://git.lavasoftware.org/lava/lava/-/merge_requests/1481

I hope this story might help to maintain pyocd in a more sustainable way for the wider community. I'm well aware that for a long time (relatively), "pyocd-flashtool" threw a warning that it's deprecated and "pyocd flash" should be used instead. Apparently, that wasn't for long enough - e.g., distros didn't catch up with the newer releases. As an example of better approach, "pyocd-flashtool" could stay deprecated, but still available, throughout 1.x releases, and only removed in 2.0. (And when I name releases, I mean the same release velocity as now, where 0.13 was released end of 2018, and 0.29 - end of 2020, i.e. 1.0 isn't expected in next couple of years).

Thanks for the wonderful tool and your consideration!

[cederom]

Hello @pfalcon :-)

There has been a long road in the project since 0.13 and more stuff changed than you think, but yes major number change in case of big API change (here it will be binary names and dropping python2 support) is a common way to solve compatibility problems, maybe it still can be done @flit ? This way Debian could still use 0.X release in the old way and create a 1.X branch to work in the new manner.. i am not sure about python modules but packages would not have to be even mutually exclusive if the file names changed, correct? :-)

Another solution may be some sort of distro-specific wrapper scripts if major number bump is not an option? :-)

[pfalcon]

@cederom: Thanks for the reply. Note that the topic of the issue above is not what PyOCD version the Debian packages use (it's of course not good that the packages are so dated, but it's a separate question, with which I'm personally no involved, and PyOCD core team might be not either). Nor it's about multitude of workarounds downstream projects can adopt - we know that IT is an industry built on workarounds ;-).

It's literally feedback about PyOCD's own external interfaces change control. I'm not sure how often the project receives such, so decided to share one. If it's a common topic, let it be another "+1". And if not, that maybe the project already gets enough outreach that it should consider being more conservative in changes like that.