If adopting pyblish-base (and potentially pyblish-lite) it is important for us to know the thoughts and experience from you in regards to breaking changes and backwards compatibility between pyblish versions. Our goal would be to stay as up-to-date as possible with pyblish-base, and thus we’re concerned with potential changes to the api surface/logic and the impact it would have for us.
Is changes to pyblish-base api surface/logic common? Are there any best practices on what to avoid, e.g. not using _private_methods, or add instance/class level variables with the risk of shadowing newly introduced variables?
My biggest concern here is not that we would have to make some changes, but that we break things for users of our software.
Backwards compatibility is taken very seriously with Pyblish. Major changes always come with full support for backwards compatibility, and you should find that plug-ins written in 1.0 still work just fine in 1.4, and will continue to do so until at least 2.0. There are tests in place to ensure this.
And each commit is automatically tested and is never committed into the project unless it maintains compatibility.
Are there any best practices on what to avoid, e.g. not using privatemethods, or add instance/class level variables with the risk of shadowing newly introduced variables?
pyblish.api is the public-facing API towards Pyblish, this is the module with guaranteed backwards compatibility. Then there is pyblish.util which is a convenience module for basic publishing via Python, this is also versioned and kept backwards compatible.
All else should be considered internal. But this is a good point, this should get documented somewhere.
My biggest concern here is not that we would have to make some changes, but that we break things for users of our software.
Pyblish is built to be built on. If there should ever be a breaking change, file an issue and we’ll get it patched up.