snazy commented on code in PR #1890: URL: https://github.com/apache/polaris/pull/1890#discussion_r2144719410
########## site/content/in-dev/unreleased/evolution.md: ########## @@ -0,0 +1,61 @@ +--- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +title: Polaris Evolution +type: docs +weight: 1000 +--- + +This page discusses what can be expected from Apache Polaris as the project evolves. + +## Polaris as a Catalog + +Polaris is primarily intended to be used as a Catalog of Tables and Views. As such, +it implements the Iceberg REST API, Polaris Management API and the Generic Tables API. + +Revisions of the Iceberg REST API are controlled by the [Apache Iceberg](https://iceberg.apache.org/) +community. Polaris attempts to accurately implement the most recent version of this specification, Review Comment: ```suggestion community. Polaris attempts to accurately implement this specification, ``` I think, "most recent" is a too strong commitment. There might be legit reasons to not implement the "latest greatest". WDYT? ########## site/content/in-dev/unreleased/evolution.md: ########## @@ -0,0 +1,61 @@ +--- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +title: Polaris Evolution +type: docs +weight: 1000 +--- + +This page discusses what can be expected from Apache Polaris as the project evolves. + +## Polaris as a Catalog + +Polaris is primarily intended to be used as a Catalog of Tables and Views. As such, +it implements the Iceberg REST API, Polaris Management API and the Generic Tables API. + +Revisions of the Iceberg REST API are controlled by the [Apache Iceberg](https://iceberg.apache.org/) +community. Polaris attempts to accurately implement the most recent version of this specification, +which is available at the time of Polaris releases. + +The Polaris Management API is maintained as a versioned REST API. New releases of Polaris may +include changes to the current version of the Management API. When that happens those changes +are intended to be compatible with prior versions of Polaris clients. + +In case a major change is required to the Management API that cannot be implemented in a +backward-compatible way, a new version of the API will be introduced. Polaris servers will support +old API version for some transition period to allow clients to migrate. Note that API versions +are not meant to be 1:1 with Polaris releases. + +The Generic Tables API is an experimental API at this time. Refer to its documentation page +for more details about compatibility expectations. + +## Polaris as a Library + +Polaris produces several jars. These jars or custom builds of Polaris code may be used in +downstream projects according to the terms of the license included into Polaris distributions. + +However, Polaris' focus as a project is not on ensuring ideal binary compatibility at the java Review Comment: Nit: "ABI" is the term here. But "binary" is much stronger than "source". ########## site/content/in-dev/unreleased/evolution.md: ########## @@ -0,0 +1,61 @@ +--- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +title: Polaris Evolution +type: docs +weight: 1000 +--- + +This page discusses what can be expected from Apache Polaris as the project evolves. + +## Polaris as a Catalog + +Polaris is primarily intended to be used as a Catalog of Tables and Views. As such, +it implements the Iceberg REST API, Polaris Management API and the Generic Tables API. + +Revisions of the Iceberg REST API are controlled by the [Apache Iceberg](https://iceberg.apache.org/) +community. Polaris attempts to accurately implement the most recent version of this specification, +which is available at the time of Polaris releases. + +The Polaris Management API is maintained as a versioned REST API. New releases of Polaris may +include changes to the current version of the Management API. When that happens those changes +are intended to be compatible with prior versions of Polaris clients. + +In case a major change is required to the Management API that cannot be implemented in a +backward-compatible way, a new version of the API will be introduced. Polaris servers will support +old API version for some transition period to allow clients to migrate. Note that API versions +are not meant to be 1:1 with Polaris releases. + +The Generic Tables API is an experimental API at this time. Refer to its documentation page +for more details about compatibility expectations. + +## Polaris as a Library Review Comment: ```suggestion ## Polaris is not a Library ``` The Polaris project is primarily intended for consumption "as is" by end users, while also allowing people to integrate it into their services. But there are no clear boundaries between API/SPI and implementation. Those could be introduced by having a clear separation of these via specific modules - but that's not the case yet. Binary compatibility (in the sense of "ABI", application binary interface) is a very strong commitment, much stronger than source compatibility (think: rebuild). From experience, we already had quite some changes throughout the (short) history of the project that count as ABI breaking changes, and quite a few exist as PRs (in progress/review) for "1.x". My take on this is that there is strictly speaking neither a binary nor a source level compatibility guarantee. We should however work towards (more or less) strict API/SPI and implementation boundaries and clearly state the intent, scope and compatibility guarantees for each of the APIs and SPIs are. Java visibility modifiers are not a way to "declare" APIs/SPIs and their guarantees. `public`, `protected` et al just define the technical visibility, often a broad(er) visibility is required by pure technical reasons - but those are not (necessarily) "public stable APIs". `@VisibleForTesting` means that the technical visibility for something has been changed for testing purposes - but it says absolutely nothing about the "assumed production visibility" ; it's also just an annotation, nothing that's enforced, similar to other annotations. ########## site/content/in-dev/unreleased/evolution.md: ########## @@ -0,0 +1,61 @@ +--- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +title: Polaris Evolution +type: docs +weight: 1000 +--- + +This page discusses what can be expected from Apache Polaris as the project evolves. + +## Polaris as a Catalog + +Polaris is primarily intended to be used as a Catalog of Tables and Views. As such, +it implements the Iceberg REST API, Polaris Management API and the Generic Tables API. + +Revisions of the Iceberg REST API are controlled by the [Apache Iceberg](https://iceberg.apache.org/) +community. Polaris attempts to accurately implement the most recent version of this specification, +which is available at the time of Polaris releases. + +The Polaris Management API is maintained as a versioned REST API. New releases of Polaris may +include changes to the current version of the Management API. When that happens those changes +are intended to be compatible with prior versions of Polaris clients. Review Comment: > `compatible with prior versions` Worth mentioning deprecation-for-removal? ########## site/content/in-dev/unreleased/evolution.md: ########## @@ -0,0 +1,61 @@ +--- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +title: Polaris Evolution +type: docs +weight: 1000 +--- + +This page discusses what can be expected from Apache Polaris as the project evolves. + +## Polaris as a Catalog + +Polaris is primarily intended to be used as a Catalog of Tables and Views. As such, +it implements the Iceberg REST API, Polaris Management API and the Generic Tables API. + +Revisions of the Iceberg REST API are controlled by the [Apache Iceberg](https://iceberg.apache.org/) +community. Polaris attempts to accurately implement the most recent version of this specification, +which is available at the time of Polaris releases. + +The Polaris Management API is maintained as a versioned REST API. New releases of Polaris may +include changes to the current version of the Management API. When that happens those changes +are intended to be compatible with prior versions of Polaris clients. + +In case a major change is required to the Management API that cannot be implemented in a +backward-compatible way, a new version of the API will be introduced. Polaris servers will support Review Comment: > `a new version of the API will be introduced` It's also a very strong commitment. It _may_ be a new version or a deprecation or addition. "Version" can be ambiguous here IMO. It might be a new version of the spec or a new base path (e.h. `.../api/v42/...`) or both. Mean, it's fine to be vague here, but then it should be clear that it's vague. WDYT? ########## site/content/in-dev/unreleased/evolution.md: ########## @@ -0,0 +1,61 @@ +--- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +title: Polaris Evolution +type: docs +weight: 1000 +--- + +This page discusses what can be expected from Apache Polaris as the project evolves. + +## Polaris as a Catalog + +Polaris is primarily intended to be used as a Catalog of Tables and Views. As such, +it implements the Iceberg REST API, Polaris Management API and the Generic Tables API. + +Revisions of the Iceberg REST API are controlled by the [Apache Iceberg](https://iceberg.apache.org/) +community. Polaris attempts to accurately implement the most recent version of this specification, +which is available at the time of Polaris releases. + +The Polaris Management API is maintained as a versioned REST API. New releases of Polaris may +include changes to the current version of the Management API. When that happens those changes +are intended to be compatible with prior versions of Polaris clients. + +In case a major change is required to the Management API that cannot be implemented in a +backward-compatible way, a new version of the API will be introduced. Polaris servers will support +old API version for some transition period to allow clients to migrate. Note that API versions +are not meant to be 1:1 with Polaris releases. + +The Generic Tables API is an experimental API at this time. Refer to its documentation page +for more details about compatibility expectations. Review Comment: Not sure we should refer to specific APIs from a general doc. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: issues-unsubscr...@polaris.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
