Stability of modules

Author: adamw

build.sbt

@@ -29,7 +29,7 @@ compileDocumentation := {
 lazy val rootProject = (project in file("."))
   .settings(commonSettings)
   .settings(publishArtifact := false, name := "ox")
-  .aggregate(core, kafka, mdcLogback, flowReactiveStreams, cron, otelContext, forkLocal)
+  .aggregate(core, kafka, mdcLogback, flowReactiveStreams, cron, otelContext)
 
 lazy val core: Project = (project in file("core"))
   .settings(commonSettings)
@@ -104,16 +104,6 @@ lazy val otelContext: Project = (project in file("otel-context"))
   )
   .dependsOn(core % "test->test;compile->compile")
 
-lazy val forkLocal: Project = (project in file("fork-local"))
-  .settings(commonSettings)
-  .settings(
-    name := "fork-local",
-    libraryDependencies ++= Seq(
-      scalaTest
-    )
-  )
-  .dependsOn(core % "test->test;compile->compile")
-
 lazy val documentation: Project = (project in file("generated-doc")) // important: it must not be doc/
   .enablePlugins(MdocPlugin)
   .settings(commonSettings)

doc/index.md

@@ -90,6 +90,7 @@ In addition to this documentation, ScalaDocs can be browsed at [https://javadoc.
    :maxdepth: 2
    :caption: Other topics
    
+   other/stability
    other/links
    other/dictionary
    other/best-practices

doc/other/stability.md

@@ -0,0 +1,24 @@
+# Stability of modules
+
+The modules are categorized using the following levels:
+
+* **stable**: binary compatibility is guaranteed within a major version; adheres to semantic versioning
+* **stabilizing**: the API is mostly stable, with rare binary-incompatible changes possible in minor releases (only if necessary)
+* **experimental**: API can change significantly even in patch releases
+
+The major version is increased when there are binary-incompatible changes in **stable** modules.
+
+The minor version is increased when there are significant new features in **stable** modules (keeping compatibility), or binary-incompatible changes in **stabilizing** modules.
+
+The patch version is increased when there are binary-compatible changes in **stable** / **stabilizing** modules, any changes in **exeperimental** modules, or when a new module is added (e.g. a new integration).
+
+## Main modules 
+
+| Module                | Level        |
+|-----------------------|--------------|
+| core                  | stabilizing  |
+| flow-reactive-streams | stabilizing  |
+| kafka                 | experimental |
+| mdc-logback           | experimental |
+| cron                  | experimental |
+| otel-context          | experimental |