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.