bbcmicrobit
Lack of a method deprecation process creates poor user experience
Regarding this example: https://github.com/bbcmicrobit/micropython/issues/591
I think we should have a simple but controlled process for managing breaking changes to the language/API.
Comments welcomed @carlosperate @jaustin
Removing methods will break existing users code. We all know that, but its worth remembering that, as it provides a bad experience for users who expect their code to always work on the latest editors and languages.
Should we mark removed methods in the docs as 'deprecated, please use x instead', and have a deprecation process a bit like Java, where one major release marks it as deprecated, the next major release actually removes it?
And, any method that once existed that is now deprecated and removed should be listed at the base of the readthedocs page for that module, so that users that miss the deprecation steps can still work out themselves what has gone wrong (and don't think 'how did this code ever work, like I just did??!!)
Should we mark removed methods in the docs as 'deprecated, please use x instead', and have a deprecation process a bit like Java, where one major release marks it as deprecated, the next major release actually removes it?
Yes, I think that would be good. And since a deprecated method would be a breaking change it makes sense to trigger a major version (readall was deprecated from v0.9 to v1.0).
Because readall was deprecated before we had a good process I think we should keep the deprecation notice in the docs for v1.0 for a while, but for how long?
The default answer would be to only remove it on the next major release (v2.0), but our aim is to never do a breaking change again (new backwards-compatible features would trigger only a minor version), and so we might never get to v2.0.
