I think we could combine annotation-based stability markers with module/package separation.
One possible example roadmap could look like this: - Polaris 1.2: mark key interfaces as @Evolving. - Polaris 1.3: move them into a polaris-api module and mark the old locations as @Deprecated. - Polaris 1.4: stabilize the SPI surface by promoting selected interfaces to @Stable and remove the deprecated ones. This adds some maintenance overhead, but it also provides clarity about what is changing and allows everyone in the community to participate. Downstream projects will see deprecation warnings and have time to migrate, and over time we can evolve CI tooling around the annotations. On Tue, 19 Aug 2025 at 00:58, Yufei Gu <flyrain...@gmail.com> wrote: > Looks like we got a consensus to confine SPI in certain modules. Here are a > few candidates: > 1. polaris-core > 2. All modules under /api > 3. polaris-runtime-service, this module is a bit controversial, as it holds > a lot of implementation as well as interfaces. Options would be 1. to move > interfaces to the polaris-core, 2. to create a new module to hold these > interfaces. > > Yufei > > > On Mon, Aug 18, 2025 at 3:33 PM Michael Collado <collado.m...@gmail.com> > wrote: > > > > If a downstream project uses CDI and something comes out of alignment, > > that is usually detected at compile time, so it's still as explicit as > > renaming a method IMHO :) > > > > It is certainly obvious to the owners of the downstream project, but in > the > > context of this discussion, it's not visible to PR authors who may not be > > aware of the downstream compilation effects. > > > > I'm fully in favor of an API module that is intended to be consumed by > > outside projects. I kinda thought that's what polaris-core was intended > to > > be. That's where pretty much all of the central Polaris API interfaces > and > > implementations are defined. These were originally scoped to be > accessible > > from even outside of the context of a web service application. > > Additionally, polaris-service-common defines many interface definitions > > that are configurable via the application.properties file. I know there > is > > a lot more defined in that module aside from just the interface > > definitions, so maybe there are steps to take to isolate the intended > > extension points, as you suggest. > > > > On Fri, Aug 15, 2025 at 9:54 PM Dmitri Bourlatchkov <di...@apache.org> > > wrote: > > > > > Hi Michael, > > > > > > I'm not sure I completely understand your point about explicit vs. > > > implicit. > > > > > > From my POV, existing Apache Polaris code is always explicit since it > is > > > available for inspection end-to-end, injection points are annotated and > > > injection behaviour is controlled by explicit configuration. > > > > > > If a downstream project uses CDI and something comes out of alignment, > > > that is usually detected at compile time, so it's still as explicit as > > > renaming > > > a method IMHO :) > > > > > > For downstream projects, even non-CDI usage is always implicit because > > > anything that is callable can be called somewhere and it is impossible > to > > > predict what is used. As Polaris code itself shows, even private fields > > and > > > methods from upstream projects may be used. > > > > > > I fully support establishing a well-defined SPI surface. However, I do > > not > > > think > > > it is quite possible to achieve that without first going through a > phase > > of > > > risky / breaking changes (because of the above). Ideally I think > Polaris > > > should > > > define SPI not only by means of java visibility modifiers or > annotations, > > > but by > > > defining an isolated module (jar) in the codebase. > > > > > > I suppose the transition to such an SPI module is going to be turbulent > > for > > > downstream projects, but the end result should allow better control > over > > > SPI evolution. > > > > > > WDYT? > > > > > > Thanks, > > > Dmitri. > > > > > > On Fri, Aug 15, 2025 at 10:42 AM Michael Collado < > collado.m...@gmail.com > > > > > > wrote: > > > > > > > Possibly a point with mentioning, then, is that dependencies must be > > > > explicit in order to be clear about where there’s an extension > > contract. > > > > Some of the CDI work has led to things being less clear as things > that > > > were > > > > explicitly passed around are now simply @Injected whenever they’re > > > needed. > > > > That makes for tidier method signatures, but also makes it impossible > > to > > > > identify things that are expected to be available for dependents. > > > > Particularly around these SPI types, we should take care when moving > > > things > > > > from being explicit to implicit. > > > > > > > > Mike > > > > > > > > On Thu, Aug 14, 2025 at 9:08 PM Dennis Huo <huoi...@gmail.com> > wrote: > > > > > > > > > Thanks for starting this discussion! Definitely a current gap not > > > having > > > > > well-established SPI delineations. > > > > > > > > > > As a starting point, certainly any of the runtime-configurable > > > > > factory/supplier types demonstrate intent for service-provider > > > > > extensibility achievable without modifying any Polaris code > directly, > > > > (i.e. > > > > > fork-free customizations). Such factories/supplies, the types they > > > > > construct, and the method signatures of those types constitute the > > > > baseline > > > > > core SPI for Polaris. > > > > > > > > > > A cursory search via "@Identifer" yields at least the following > > > > > (non-exhaustive) list of starting points: > > > > > > > > > > ActiveRolesProvider > > > > > CallContextResolver > > > > > FederatedPrincipalProvider > > > > > FederatedRoleProvider > > > > > FileIOFactory > > > > > IcebergRestOAuth2ApiService > > > > > MetaStoreManagerFactory > > > > > OidcTenantResolver > > > > > PrincipalMapper > > > > > PrincipalRolesMapper > > > > > RateLimiter > > > > > RealmContextResolver > > > > > TokenBrokerFactory > > > > > TokenBucketFactory > > > > > UserSecretsManagerFactory > > > > > > > > > > Probably the ones that are most complex in terms of > type-dependencies > > > in > > > > > method signatures are: > > > > > > > > > > CallContextResolver > > > > > MetaStoreManagerFactory > > > > > RealmContextResolver > > > > > > > > > > Corresponding to these constructed types: > > > > > > > > > > PolarisMetaStoreManager > > > > > BasePersistence > > > > > IntegrationPersistence > > > > > TransactionalPersistence > > > > > CallContext > > > > > PolarisCallContext > > > > > RealmContext > > > > > > > > > > This also implies that method arguments provided into instances of > > > those > > > > > types would need to be at least backwards-compatible. > > > > > > > > > > In general, this doesn't mean those interfaces necessarily can't be > > > > > evolved, but at least interface evolution of such SPI classes > should > > be > > > > > discussed and voted on. > > > > > > > > > > On Tue, Aug 12, 2025 at 3:09 AM Robert Stupp <sn...@snazy.de> > wrote: > > > > > > > > > > > Hi all, > > > > > > > > > > > > Recently it became apparent that the community has no single > > opinion > > > > > > about what an integration point that downstream consumers can > rely > > on > > > > > > in terms of availability, stability and most importantly > functional > > > > > > and behavioral contracts is. > > > > > > > > > > > > The Polaris code base itself is still pretty fresh/young, started > > > > > > about one year ago. It is quite natural that things are not yet > > > > > > optimal and evolution and changes happen to meet everybody’s > > > > > > expectations and the project’s needs now and in/for the future. > > > > > > > > > > > > Polaris is an open source project to be used by many users. Many > > run > > > > > > it “as is” (aka as distributed by the Apache Polaris project) and > > > some > > > > > > use it as a foundation to customize it with their own > > > functionalities. > > > > > > > > > > > > The overarching goal of the project is (I think) providing a > stable > > > > > > system (runtime) without neglecting the necessities (like > security) > > > > > > while improving the observed behavior (like performance) and > being > > > > > > open for new features & functionalities and > consistently+constantly > > > > > > removing tech-debt. > > > > > > > > > > > > Two recent PRs simplifying some code complexities in Apache > Polaris > > > > > > and fixing runtime penalties for all Polaris users received > reviews > > > > > > mentioning a “...service provider with a custom persistence > > backend…” > > > > > > [1] and "...production deployment … with custom > implementations..." > > > > > > [2]. > > > > > > > > > > > > As the Apache Polaris project has no clear definition of which > > parts > > > > > > of the code base are extension points (think: SPIs), it is > > impossible > > > > > > for contributors to Apache Polaris to know what a “breaking > change” > > > > > > for “custom implementations” is. > > > > > > > > > > > > I would like to start this discussion and look forward to the > > > > > > community’s opinion, both from users that use Polaris “as is” and > > > > > > those who “extend Polaris”. > > > > > > > > > > > > Robert > > > > > > > > > > > > PS: The contributing guidelines [3] do not define what public > > > > interfaces > > > > > > are. > > > > > > > > > > > > [1] > > > > > > > > > > > > https://github.com/apache/polaris/pull/2262#pullrequestreview-3099480896 > > > > > > [2] > > > > > > > > > > > > https://github.com/apache/polaris/pull/2277#pullrequestreview-3099564976 > > > > > > [3] > https://polaris.apache.org/community/contributing-guidelines/ > > > > > > > > > > > > > > > > > > > > >
