This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/sis-site.git
commit e47deb6691aaa70aa21d052f70a013fff62f570d Author: Martin Desruisseaux <[email protected]> AuthorDate: Fri Aug 14 19:04:35 2026 +0200 Clarify the note about API stability. --- content/_index.md | 15 +++++++++++---- layouts/shortcodes/API.html | 1 + 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/content/_index.md b/content/_index.md index 17124a79..1b1e50c6 100644 --- a/content/_index.md +++ b/content/_index.md @@ -82,11 +82,18 @@ are also provided for allowing users to experiment some SIS functionalities befo ## Backward compatibility policy {#compatibility} -Most of SIS public API is stable. +Most of {{% SIS %}} public {{% API %}} is stable. If an API needs to be changed, the old API is annotated as deprecated and a Javadoc comment explains the replacement. -If the API is deprecated for removal, it is usually kept for only one release and effectively removed in the next one. -Therefore, if an API seems to have disappeared after an Apache SIS upgrade, the migration path can be identified by -incrementing the version one-by-one. The `@version` tag gives the last version when a class got a significant change. +If the API is deprecated for removal, it is usually kept for one SIS release and effectively removed in the next one. +Therefore, if an API seems to have disappeared between two versions of Apache SIS, +the replacement can be found by incrementing the SIS version one-by-one and looking at the compiler warnings. +The versions to test can be bounded by looking at the `@version` tag in the [Javadoc](apidocs/index.html), +which gives the last version when a class, package or module got a significant change. + +In some rare occasions, an incompatible API change may be applied without deprecation cycle. +It may happen when it is difficult to have the old and new API coexisting. +Such cases are documented in an "Incompatible changes" section of the [release notes](release-notes/index.html) +and should not impact the most commonly used APIs. [geoapi]: https://www.geoapi.org/ diff --git a/layouts/shortcodes/API.html b/layouts/shortcodes/API.html new file mode 100644 index 00000000..59b097ff --- /dev/null +++ b/layouts/shortcodes/API.html @@ -0,0 +1 @@ +<abbr title="Application Programming Interface">API</abbr> \ No newline at end of file
