This is pretty exciting. I'll add thoughts inline. On Tue, Feb 21, 2017 at 6:31 PM, Davor Bonaci <da...@apache.org> wrote:
> * Support for all major operating systems. > Do we have a testing plan? * No backward-incompatible API changes within a given major version for the > user-facing APIs across the project. > I think we should use a tool like japicmp to catch errors here for Java. I've never used such a tool in Python; does anyone know of anything? > * Exception: internally-facing APIs, such as APIs between components. > Let's annotate these, too. We'll need to have an annotation for tooling anyhow. I would even be comfortable having this extend @Deprecated, since we should often have a goal of getting rid of them :-) and it will cause a visible warning in an IDE. And I would add "* Exception: X Y Z reflection or reflection-like things" because: Java: reflection is often not considered, since it breaks information hiding. But downcasts and instanceof are a gray area, which depends on the context. We might want to explicitly document where these are supported in a backwards-compatible way and otherwise say that they are not, etc. Python: mechanically-enforced information hiding is rare and unidiomatic so there's a lot more that is *technically* public while conceptually private. I'll defer to contributors to the Python SDK about where they draw the line but it would be nice to be explicit. Kenn