Add more examples for compatible version string bump

src/migration.rs

@@ -30,13 +30,45 @@ use crate::{Agent, AgentStatus, Giganto, Indexed, IterableMap};
 /// // This should include future patch versions such as 0.4.2, 0.4.3, etc. since they won't
 /// // change the database format.
 /// const COMPATIBLE_VERSION: &str = ">=0.3,<0.5.0-alpha";
-/// ```
 ///
-/// ```rust
-/// // The current version is 0.5.0-alpha.4 and the database format hasn't been changed since
-/// // 0.5.0-alpha.2. This shouldn't include any future version since we cannot guarantee that
-/// // the database format won't be changed in the future alpha or beta versions.
-/// const COMPATIBLE_VERSION: &str = ">=0.5.0-alpha.2,<=0.5.0-alpha.4";
+/// // The current version is 3.4.5 and the database format hasn't been changed since 1.0.0.
+/// // Future patch versions such as 3.4.6 are compatible since they won't change the database format.
+/// const COMPATIBLE_VERSION: &str = ">=1.0.0,<3.5.0-alpha";
+///
+/// // The current version is 3.4.6-alpha.2 and the database format hasn't been changed since 1.0.0.
+/// // Future pre-release versions such as 3.4.6-alpha.3 are compatible since they won't change the database format.
+/// const COMPATIBLE_VERSION: &str = ">=1.0.0,<3.5.0-alpha";
+///
+/// // The current version is 3.4.5 and the database format hasn't been changed since 1.0.0.
+/// // The next version to pre-release is 3.5.0-alpha.1, if no database format change is involved, then
+/// // compatible version should be extended to 3.5.0-alpha.1.
+/// const COMPATIBLE_VERSION: &str = ">=1.0.0,<=3.5.0-alpha.1";
+///
+/// // The current version is 3.4.5 and the database format hasn't been changed since 1.0.0.
+/// // The next version to release is 3.5.0 (stable), if no database format change is involved, then
+/// // migration is not needed, while compatible version should be extended to 3.5.0.,
+/// // including all future patch versions.
+/// const COMPATIBLE_VERSION: &str = ">=1.0.0,<3.6.0-alpha";
+///
+/// // The current version is 3.4.5-alpha.3 and the database format hasn't been changed since 1.0.0.
+/// // The next version to release is 3.5.0 (stable), with compatibility extended to future patch versions.
+/// const COMPATIBLE_VERSION: &str = ">=1.0.0,<3.6.0-alpha";
+///
+/// // The current version is 3.4.5 and the database format is changing in 3.5.0-alpha.1.
+/// // The compatibility is now restricted to 3.5.0-alpha.1, requiring a migration from the 1.0.0 format.
+/// const COMPATIBLE_VERSION: &str = ">=3.5.0-alpha.1,<3.5.0-alpha.2";
+/// // Migration: `migrate_1_0_to_3_5` must handle changes from 1.0.0 to 3.5.0-alpha.1.
+///
+/// // The current version is 3.5.0-alpha.2 and the database format is changing in 3.5.0-alpha.3.
+/// // The compatibility is now restricted to 3.5.0-alpha.3, requiring a migration from the 1.0.0 format.
+/// const COMPATIBLE_VERSION: &str = ">=3.5.0-alpha.3,<3.5.0-alpha.4";
+/// // Migration: `migrate_1_0_to_3_5` must handle changes from 1.0.0 to 3.5.0-alpha.3, including prior alpha changes.
+///
+/// // The current version is 3.5.0-alpha.2 and the database format is finalized in 3.5.0.
+/// // The compatibility is extended to all 3.5.0 versions, requiring a migration from the 1.0.0 format.
+/// const COMPATIBLE_VERSION: &str = ">=3.5.0,<3.6.0-alpha";
+/// // Migration: `migrate_1_0_to_3_5` must handle changes from 1.0.0 (last release that involves database format
+/// // change) to 3.5.0, including all alpha changes finalized in 3.5.0.
 /// ```
 const COMPATIBLE_VERSION_REQ: &str = ">=0.34.0-alpha.1,<0.34.0-alpha.3";