anton-vinogradov commented on code in PR #13759: URL: https://github.com/apache/ignite/pull/13759#discussion_r4393459171
########## rfcs/IGNITE-29219-public-api-and-compatibility.md: ########## @@ -0,0 +1,77 @@ +<!-- +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. +--> + +# Public API, public behavior, and compatibility contracts + +Ticket: [IGNITE-29219](https://issues.apache.org/jira/browse/IGNITE-29219) + +## Public behavior + +A compatible change preserves supported functionality and its guarantees. This applies to external interfaces, stored data, and supported build and deployment setups: + +- **Results and effects:** accepted inputs, guarantees about results, and side effects. +- **Operations:** guarantees about transactions, ordering, retries, and cancellation. +- **Errors:** errors, including error codes and SQLState values. +- **Extensions:** guarantees about calls to overridden methods and callbacks. + +When documentation is incomplete, use tests and existing usage to clarify public behavior. + +## External interfaces + +These interfaces are designed and supported for external use: + +- **Programming APIs:** language and client APIs, plugins, and SPIs. +- **SQL:** syntax, types, and functions. +- **REST and CLI:** endpoints, commands, options, exit codes, and supported machine-readable output. +- **Configuration:** user settings and their defaults, including system properties, environment variables, and distributed properties. +- **Monitoring:** supported metrics, JMX interfaces, system views, and documented structured events. +- **Client protocols:** client protocols and external serialization formats. + +A compatible change keeps existing supported calls, queries, commands, configurations, and integrations valid. Their names, signatures, and schemas stay compatible. + +- **Source compatibility:** existing application and plugin source code still compiles. +- **Binary compatibility:** compiled applications and plugins still work without rebuilding. +- **Client/server compatibility:** supported combinations of client and server versions keep working. + +An interface remains public even if its documentation is missing or we know of no external users. + +A class in an internal package can still be part of the public API. Public methods or public error codes alone do not make a class part of the public API. + +Experimental public interfaces follow their stated stability limits. + +## Stored data + +This covers data, metadata, WAL, and snapshot formats used during supported upgrades and recovery. + +A compatible change preserves the ability to read and recover existing data with the same meaning and durability guarantees. The physical format may change through a documented migration. + +## Distribution and runtime + +This covers published artifact names and coordinates, and supported JDK and operating system versions. + +A compatible change keeps supported build and deployment setups working. + +## Supported versions + +Document supported client/server version combinations, data upgrade paths, and JDK and operating system versions in the relevant user documentation. If this information is incomplete, clarify it in the RFC. Missing documentation does not remove existing guarantees. + +## Outside the contract + +- **Implementation details:** classes outside the public API and internal algorithms. +- **Node-to-node protocols:** internal communication and discovery protocols. Review Comment: RU, is out of scope for the moment. Let's discuss it separately. > Not sure right now, but what if we divide api in two ways: public/private and stable/unstable? Good point, but I propose another approach. Just to make all "de facto API" into "de jure" (change the package). But this is out of the RFC scope too. > Probably, my question is how often do we plan to change node-to-node protocol and is it comfortable to write iep for every change of protocol? Until RU RFC discussion and approval :) ########## rfcs/IGNITE-29219-public-api-and-compatibility.md: ########## @@ -0,0 +1,77 @@ +<!-- +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. +--> + +# Public API, public behavior, and compatibility contracts + +Ticket: [IGNITE-29219](https://issues.apache.org/jira/browse/IGNITE-29219) + +## Public behavior + +A compatible change preserves supported functionality and its guarantees. This applies to external interfaces, stored data, and supported build and deployment setups: + +- **Results and effects:** accepted inputs, guarantees about results, and side effects. +- **Operations:** guarantees about transactions, ordering, retries, and cancellation. +- **Errors:** errors, including error codes and SQLState values. +- **Extensions:** guarantees about calls to overridden methods and callbacks. + +When documentation is incomplete, use tests and existing usage to clarify public behavior. + +## External interfaces + +These interfaces are designed and supported for external use: + +- **Programming APIs:** language and client APIs, plugins, and SPIs. +- **SQL:** syntax, types, and functions. +- **REST and CLI:** endpoints, commands, options, exit codes, and supported machine-readable output. +- **Configuration:** user settings and their defaults, including system properties, environment variables, and distributed properties. +- **Monitoring:** supported metrics, JMX interfaces, system views, and documented structured events. +- **Client protocols:** client protocols and external serialization formats. + +A compatible change keeps existing supported calls, queries, commands, configurations, and integrations valid. Their names, signatures, and schemas stay compatible. + +- **Source compatibility:** existing application and plugin source code still compiles. +- **Binary compatibility:** compiled applications and plugins still work without rebuilding. +- **Client/server compatibility:** supported combinations of client and server versions keep working. + +An interface remains public even if its documentation is missing or we know of no external users. + +A class in an internal package can still be part of the public API. Public methods or public error codes alone do not make a class part of the public API. + +Experimental public interfaces follow their stated stability limits. + +## Stored data + +This covers data, metadata, WAL, and snapshot formats used during supported upgrades and recovery. + +A compatible change preserves the ability to read and recover existing data with the same meaning and durability guarantees. The physical format may change through a documented migration. + +## Distribution and runtime + +This covers published artifact names and coordinates, and supported JDK and operating system versions. + +A compatible change keeps supported build and deployment setups working. + +## Supported versions + +Document supported client/server version combinations, data upgrade paths, and JDK and operating system versions in the relevant user documentation. If this information is incomplete, clarify it in the RFC. Missing documentation does not remove existing guarantees. + +## Outside the contract + +- **Implementation details:** classes outside the public API and internal algorithms. +- **Node-to-node protocols:** internal communication and discovery protocols. Review Comment: RU, is out of scope for the moment. Let's discuss it separately. > Not sure right now, but what if we divide api in two ways: public/private and stable/unstable? Good point, but I propose another approach. Just to make all "de facto API" into "de jure" (change the package). But this is out of the RFC scope too. > Probably, my question is how often do we plan to change node-to-node protocol and is it comfortable to write iep for every change of protocol? Until RU RFC discussion and approval :) -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
