Great to see Beam API becoming stable and Python SDK becoming a part of it.
On Wed, Feb 22, 2017 at 2:57 PM Kenneth Knowles <k...@google.com.invalid> wrote: 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. I think, this point applies to Python SDK as well (though as you mentioned, API hiding in Python is a mere convention (prefix with underscore) not enforced. We already have mechanism for marking APIs as deprecated which might be useful here: https://github.com/apache/beam/blob/master/sdks/python/apache_beam/utils/annotations.py - Cham Kenn
