Hi Chris,
you're right. I wasn't aware of the x-internal feature and thought you were referring to naming packages 'internal'. But than one wouldn't be allowed to export them, right?
Although I think it's a reasonable approach for common library-style bundles, I'm not sure if this works that well for Xtext. With Xtext it will always be the case, that you have code in your src-folders which is linked against "non published" API. This is because we generate code which references these things. In addition introducing an annotation for published API, would allow to specify the API life cycle things more fine grained (i.e. on types and methods).
Currently I think the best solution would be to add API-Tooling restrictions to additionally constraint those things which are explicitly marked as published. This would allow using API tooling to make sure that you use the published things in the intended way.
Thanks, Sven
On Feb 11, 2009, at 4:00 PM, Chris Aniszczyk wrote: I'm confused how you would have to change the namespace? Let's pretend we have a package 'org.eclipse.foo'
In the "internal" / "non-stable" version of the package, you simply would have it labeled like this in the MANIFEST.MF
Export-Package: org.eclipse.foo;x-internal:=true
If you decided one day that this package had stable stuff:
Export-Package: org.eclipse.foo
So you have the same namespace, but one is now considered "stable"
We didn't do this in the Eclipse SDK in the past mostly due to legacy reasons so that's why you see 'internal' and 'internal.provisional' in package names. It was more of a lack of tooling that we decided to use different package namespaces to help communicate to people that we have moved something into API.
Does that help a bit?
On Wed, Feb 11, 2009 at 2:15 AM, Sven Efftinge <sven.efftinge@xxxxxxxxx> wrote: Hi Chris, On Feb 10, 2009, at 10:02 PM, Chris Aniszczyk wrote: On Tue, Feb 10, 2009 at 12:51 PM, Sven Efftinge <sven.efftinge@xxxxxxxxx> wrote:
It might make sense in many scenarios.
However, we want to technically allow use of non-public API, therefore we've to export more than just the stable stuff.
We want to mark some of the exported interfaces, classes explicitly as stable, so the user can be sure that we won't do any breaking changes there.
In Eclipse, we accomplish this by exporting every package, whether it is x-internal or not because we find people want to access internal things. The things that are stable are simply the things that aren't x-internal. It's that simple :)
This clearly communicates what's public and what's not. However, we have to change the namespace of an element whenever we'ld decide that it's stable. This will break clients, which presumably have used this. We're avoiding it by using an annotation. But besides how we mark what's public and what's not (package name vs. annotation), we share the same philosophy. That is we want to communicate carefully and clearly what's stable and what's not :-)
Cheers, Sven
--
Cheers,
~ Chris Aniszczyk
|
