doc: document r3_core's stability

yvt · yvt · commit e15141882f16 · 2022-03-05T01:57:00.000+09:00
diff --git a/src/r3/src/lib.md b/src/r3/src/lib.md
@@ -18,59 +18,78 @@ body.theme-ayu h1 img:nth-of-type(1) { filter: brightness(8) hue-rotate(-120deg)
 
 See [`r3_core`]'s crate-level documentation for a general description of kernel features and concepts used in R3.
 
+<!-- Display a "some Cargo features are disabled" warning in the documentation so that the user can know some items are missing for that reason. But we don't want this message to be displayed when someone is viewing `lib.md` directly, so the actual message is rendered by CSS. -->
+<div class="admonition-follows"></div>
+<blockquote class="disabled-feature-warning"><p><span></span><code></code></p></blockquote>
+
 # Package Ecosystem
 
-The `r3` package is built on top on [`r3_core`] and provides useful abstractions. A kernel, which is chosen by application code, is implemented for a specific major version of `r3_core` and not others. Separating the fast-changing part into `r3` prevents ecosystem split and maximizes code reuse.
-
-<table class="package-ecosystem-table" align="center">
-    <tr>
-        <th>Application code</th>
-        <td colspan="2">Application</td>
-        <td colspan="2">Library</td>
-        <td colspan="2">Library</td>
-        <td class="noborder">...</td>
-    </tr>
-    <tr>
-        <th>Façade API</th>
-        <td colspan="3"><code>r3 1.0¹</code></td>
-        <td colspan="3"><code>r3 2.0</code></td>
-        <td class="noborder">...</td>
-    </tr>
-    <tr>
-        <th>Core API definition</th>
-        <td colspan="7"><code>r3_core 1.0</code></td>
-    </tr>
-    <tr>
-        <th>Kernel (API implementor)²</th>
-        <td colspan="7"><code>r3_kernel</code></td>
-    </tr>
-    <tr>
-        <th>Ports²</th>
-        <td colspan="2"><code>r3_port_std</code></td>
-        <td colspan="2"><code>r3_port_arm</code></td>
-        <td colspan="2"><code>r3_port_arm_m</code></td>
-        <td><code>r3_port_riscv</code></td>
-    </tr>
-</table>
+The R3 ecosystem revolves around the [`r3_core`][] package. Applications and libraries, including this `r3` package, are built on top of `r3_core`'s application-side API. This is in contrast with the kernel-side API, which intentionally has a weaker [stability guarantee] for continuous optimization and improvement.
+
+The following diagram shows a possible package configuration of an R3 application.
+
+<div class="package-ecosystem-table-wrap">
+    <table class="package-ecosystem-table" align="center">
+        <tr>
+            <th>Application code</th>
+            <td colspan="2">Application</td>
+            <td colspan="2">Library</td>
+            <td colspan="2">Library</td>
+            <td class="noborder">...</td>
+        </tr>
+        <tr>
+            <th>Façade API</th>
+            <td colspan="3"><code>r3 1.0¹</code></td>
+            <td colspan="3"><code>r3 2.0</code></td>
+            <td class="noborder">...</td>
+        </tr>
+        <tr>
+            <th>Core API definition</th>
+            <td colspan="7"><code>r3_core 1.0</code></td>
+        </tr>
+        <tr>
+            <th>Kernel (API implementor)²</th>
+            <td colspan="7"><code>r3_kernel</code></td>
+        </tr>
+        <tr>
+            <th>Ports²</th>
+            <td colspan="7"><code>r3_port_std</code> || <code>_arm</code> || <code>_arm_m</code> || <code>_riscv</code></td>
+        </tr>
+    </table>
+</div>
 
 <sub>¹ Version numbers shown here are illustrative.</sub>
 
 <sub>² Application code chooses kernel and port implementations.</sub>
 
 <style type="text/css">
-.package-ecosystem-table { border-collapse: separate; border-spacing: 5px !important; }
+.package-ecosystem-table-wrap { text-align: center; }
+.package-ecosystem-table {
+    border-collapse: separate; border-spacing: 5px !important;
+    margin: 0.5em auto !important; width: auto !important; display: inline-block !important;
+    padding-right: 0.5em;
+}
 .package-ecosystem-table td { border: 0.5px currentColor solid !important; text-align: center; vertical-align: middle }
 .package-ecosystem-table td.noborder,
-.package-ecosystem-table th { border: none !important; }
+.package-ecosystem-table th { border: none !important; font-weight: normal; }
 </style>
 
 <div class="admonition-follows"></div>
 
 > **Notes:** Many items of this crate are re-exported from [`r3_core`][], and consequently their example code refers to them through paths starting with `r3_core::`. You can replace them with `r3::` in your application code.
 
-<!-- Display a "some Cargo features are disabled" warning in the documentation so that the user can know some items are missing for that reason. But we don't want this message to be displayed when someone is viewing `lib.md` directly, so the actual message is rendered by CSS. -->
-<div class="admonition-follows"></div>
-<blockquote class="disabled-feature-warning"><p><span></span><code></code></p></blockquote>
+[stability guarantee]: r3_core#stability
+
+
+# Stability
+
+This package is versioned in accordance with [the Semantic Versioning 2.0.0][]. Requiring a newer version of [`r3_core`][] that breaks [the application-side API stability guarantee][] is considered a breaking change.
+
+Increasing the minimum supported Rust version (MSRV) is not considered a breaking change.
+
+[the Semantic Versioning 2.0.0]: https://semver.org/
+[the application-side API stability guarantee]: r3_core#stability
+
 
 # Cargo Features
 
diff --git a/src/r3/src/lib.rs b/src/r3/src/lib.rs
@@ -62,7 +62,9 @@ mod tests;
 pub use r3_core::{bag, hunk, kernel, time};
 
 /// Utilities. This module re-exports items from [`r3_core::utils`] that are
-/// subject to the application-side API stability guarantee.
+/// subject to [the application-side API stability guarantee][1].
+///
+/// [1]: r3_core#stability
 pub mod utils {
     pub use r3_core::utils::{Init, ZeroInit};
 }
diff --git a/src/r3_core/src/kernel/raw_cfg.rs b/src/r3_core/src/kernel/raw_cfg.rs
@@ -29,14 +29,15 @@
 //!
 //! # Stability
 //!
-//! This module is covered by the kernel-side API stability guarantee.
+//! This module is covered by [the kernel-side API stability guarantee][2].
 //!
 //! The trait paths in this module are covered by the application-side API
 //! stability guarantee. Application code should only use these traits in trait
 //! bounds and, to access the provided functionalities, should use the the
 //! stable wrapper [outside this module](../index.html) instead.
 //!
 //! [1]: crate::kernel::cfg::KernelStatic
+//! [2]: crate#stability
 use crate::{bag::Bag, closure::Closure, kernel::raw, time::Duration, utils::PhantomInvariant};
 
 /// The trait for all kernel-specific low-level configurator types, used by
diff --git a/src/r3_core/src/lib.md b/src/r3_core/src/lib.md
@@ -24,6 +24,7 @@ The core API represents the low-level interface between kernel and application c
 - [Interrupt Handling Framework](#interrupt-handling-framework)
 - [Kernel Timing](#kernel-timing)
 - [Introspection](#introspection)
+- [Stability](#stability)
 - [Cargo Features](#cargo-features)
 - [Modules](#modules)  <!-- this section is generated by rustdoc -->
 - [Macros](#macros)  <!-- this section is generated by rustdoc -->
@@ -641,6 +642,24 @@ Kernel {
 
 </details>
 
+
+# Stability
+
+`r3_core` defines two levels of API stability:
+
+ - **The application-side API stability** applies to the API used by application code.
+
+ - **The kernel-side API stability** applies to the API used by a kernel implementation. The API coverage is strictly larger because a kernel implementation may use the application-side API as well, e.g., to install an interrupt handler for its own kernel timing mechanism.
+
+All public and documented items are covered under the application-side API stability unless noted otherwise.
+
+This release of R3-OS is considered a preview version. During the preview period, `r3_core` follows [the Semantic Versioning 2.0.0][] and considers breaking either level of stability as a breaking change. It's being planned to introduce a versioning scheme that maps each stability level to a distinct version component so that the kernel-side API can be extended substantially while maintaining compatibility with existing application and library code.
+
+Increasing the minimum supported Rust version (MSRV) is not considered a breaking change.
+
+[the Semantic Versioning 2.0.0]: https://semver.org/
+
+
 # Cargo Features
 
 - **`chrono_0p4`**: Enables conversion between our [duration] and [timetamp] types and `chrono ^0.4`'s types.
diff --git a/src/r3_core/src/utils/alloc.rs b/src/r3_core/src/utils/alloc.rs
@@ -16,7 +16,9 @@ macro_rules! const_try_result {
 ///
 /// # Stability
 ///
-/// This type is subject to the kernel-side API stability guarantee.
+/// This type is subject to [the kernel-side API stability guarantee][1].
+///
+/// [1]: crate#stability
 pub struct ConstAllocator {
     // We very much want to put these in `core::cell::*`, but they aren't very
     // useful in `const fn`, unfortunately.
@@ -210,7 +212,9 @@ impl const Drop for ConstAllocator {
 ///
 /// # Stability
 ///
-/// This trait is subject to the kernel-side API stability guarantee.
+/// This trait is subject to [the kernel-side API stability guarantee][1].
+///
+/// [1]: crate#stability
 #[derive(Clone, Copy)]
 pub struct AllocError;
 
@@ -222,7 +226,9 @@ pub struct AllocError;
 ///
 /// # Stability
 ///
-/// This trait is subject to the kernel-side API stability guarantee.
+/// This trait is subject to [the kernel-side API stability guarantee][1].
+///
+/// [1]: crate#stability
 pub unsafe trait Allocator {
     fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>;
 
diff --git a/src/r3_core/src/utils/init.rs b/src/r3_core/src/utils/init.rs
@@ -9,7 +9,9 @@ use core::{
 /// Trait for types having a constant default value. This is essentially a
 /// constant version of `Default`.
 ///
-/// This trait is subject to the API stability guarantee.
+/// This trait is subject to [the application-side API stability guarantee][1].
+///
+/// [1]: crate#stability
 pub trait Init {
     /// The default value.
     const INIT: Self;
diff --git a/src/r3_core/src/utils/mod.rs b/src/r3_core/src/utils/mod.rs
@@ -1,7 +1,9 @@
 //! Utility
 //!
-//! **This module is exempt from the API stability guarantee** unless specified
-//! otherwise. It's exposed mostly because it's needed by macros.
+//! **This module is exempt from [the API stability guarantee][1]** unless
+//! specified otherwise. It's exposed mostly because it's needed by macros.
+//!
+//! [1]: crate#stability
 use core::marker::PhantomData;
 
 /// Conditional type
diff --git a/src/r3_core/src/utils/zeroinit.rs b/src/r3_core/src/utils/zeroinit.rs
@@ -2,12 +2,14 @@ use core::{cell::UnsafeCell, mem, sync::atomic};
 
 /// Trait for zero-initializable types.
 ///
-/// This trait is subject to the API stability guarantee.
+/// This trait is subject to [the application-side API stability guarantee][1].
 ///
 /// # Safety
 ///
 /// Zero-initialization is not safe for all types. For example, references
 /// (`&_`)
+///
+/// [1]: crate#stability
 pub unsafe trait ZeroInit {}
 
 unsafe impl<T> ZeroInit for atomic::AtomicPtr<T> {}
