From 7a0e029d6a3286463916ef4f2459915070d8841c Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 24 Feb 2025 13:17:20 +0100 Subject: [PATCH 1/4] docs: Explain that struct describes latest version --- crates/stackable-versioned-macros/src/lib.rs | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/crates/stackable-versioned-macros/src/lib.rs b/crates/stackable-versioned-macros/src/lib.rs index edce3290d..adb1f9c85 100644 --- a/crates/stackable-versioned-macros/src/lib.rs +++ b/crates/stackable-versioned-macros/src/lib.rs @@ -29,7 +29,7 @@ mod utils; /// example, `#[automatically_derived]` and `#[allow(deprecated)]` are removed /// in most examples to reduce visual clutter. /// -/// ## Declaring Versions +///
/// /// It is **important** to note that this macro must be placed before any other /// (derive) macros and attributes. Macros supplied before the versioned macro @@ -38,16 +38,29 @@ mod utils; /// attributes are applied to the generated versioned instances of the /// container. /// +///
+/// +/// ## Declaring Versions +/// /// Before any of the fields or variants can be versioned, versions need to be /// declared at the container level. Each version currently supports two /// parameters: `name` and the `deprecated` flag. The `name` must be a valid /// (and supported) format. /// ///
+/// /// Currently, only Kubernetes API versions are supported. The macro checks each /// declared version and reports any error encountered during parsing. +/// ///
/// +/// It should be noted that the defined struct always represents the **latest** +/// version, eg: when defining three versions `v1alpha1`, `v1beta1`, and `v1`, +/// the struct will describe the structure of the data in `v1`. This behaviour +/// is especially noticeable in the [`changed()`](#changed-action) action which +/// works "backwards" by describing how a field looked before the current +/// (latest) version. +/// /// ``` /// # use stackable_versioned_macros::versioned; /// #[versioned(version(name = "v1alpha1"))] From ba7db9e6437c72d76bc92a177fdf0927b861f261 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 24 Feb 2025 13:18:21 +0100 Subject: [PATCH 2/4] docs: Explain merged_crd method --- crates/stackable-versioned-macros/src/lib.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/crates/stackable-versioned-macros/src/lib.rs b/crates/stackable-versioned-macros/src/lib.rs index adb1f9c85..7e43d9c93 100644 --- a/crates/stackable-versioned-macros/src/lib.rs +++ b/crates/stackable-versioned-macros/src/lib.rs @@ -614,6 +614,11 @@ println!("{}", serde_yaml::to_string(&merged_crd).unwrap()); # } ``` +The generated `merged_crd` method is a wrapper around [kube's `merge_crds`][1] +function. It automatically calls the `crd` methods of the CRD in all of its +versions and additionally provides a strongly typed selector for the stored +API version. + Currently, the following arguments are supported: - `group`: Set the group of the CR object, usually the domain of the company. From d9437edab02418d1d758306f31414a73bb7f335d Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 24 Feb 2025 13:19:10 +0100 Subject: [PATCH 3/4] docs: Remove outdated warning about preserve_module --- crates/stackable-versioned-macros/src/lib.rs | 6 ------ 1 file changed, 6 deletions(-) diff --git a/crates/stackable-versioned-macros/src/lib.rs b/crates/stackable-versioned-macros/src/lib.rs index 7e43d9c93..a3f04118b 100644 --- a/crates/stackable-versioned-macros/src/lib.rs +++ b/crates/stackable-versioned-macros/src/lib.rs @@ -265,12 +265,6 @@ mod utils; /// } /// ``` /// -///
-/// It is planned to move the preserve_module flag into the -/// options() argument list, but currently seems tricky to -/// implement. -///
-/// /// ## Item Actions /// /// This crate currently supports three different item actions. Items can From 607027a49454930cfccae8506ac60163005fa74a Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 24 Feb 2025 13:19:49 +0100 Subject: [PATCH 4/4] chore: Update example in README --- crates/stackable-versioned/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/stackable-versioned/README.md b/crates/stackable-versioned/README.md index f603d335a..c59960d00 100644 --- a/crates/stackable-versioned/README.md +++ b/crates/stackable-versioned/README.md @@ -30,7 +30,7 @@ struct Foo { /// My docs #[versioned( added(since = "v1alpha1"), - renamed(since = "v1beta1", from = "gau"), + changed(since = "v1beta1", from_name = "gau"), deprecated(since = "v2", note = "not required anymore") )] deprecated_bar: usize,