docs(complete): Specify the compatibility guarentees

clap_complete/src/dynamic/command/mod.rs

@@ -5,6 +5,13 @@
 //!
 //! To source your completions:
 //!
+//! **WARNING:** We recommend re-sourcing your completions on upgrade.
+//! These completions work by generating shell code that calls into `your_program` while completing.
+//! That interface is unstable and a mismatch between the shell code and `your_program` may result
+//! in either invalid completions or no completions being generated.
+//! For this reason, we recommend generating the shell code anew on shell startup so that it is
+//! "self-correcting" on shell launch, rather than writing the generated completions to a file.
+//!
 //! Bash
 //! ```bash
 //! echo "source <(your_program complete bash)" >> ~/.bashrc
@@ -207,6 +214,10 @@ pub trait CommandCompleter {
     ///
     /// Write the `buf` the logic needed for calling into `<cmd> complete`, passing needed
     /// arguments to [`CommandCompleter::write_complete`] through the environment.
+    ///
+    /// **WARNING:** There are no stability guarantees between the call to
+    /// [`CommandCompleter::write_complete`] that this generates and actually calling [`CommandCompleter::write_complete`].
+    /// Caching the results of this call may result in invalid or no completions to be generated.
     fn write_registration(
         &self,
         name: &str,

clap_complete/src/dynamic/env/mod.rs

@@ -18,6 +18,13 @@
 //!
 //! To source your completions:
 //!
+//! **WARNING:** We recommend re-sourcing your completions on upgrade.
+//! These completions work by generating shell code that calls into `your_program` while completing.
+//! That interface is unstable and a mismatch between the shell code and `your_program` may result
+//! in either invalid completions or no completions being generated.
+//! For this reason, we recommend generating the shell code anew on shell startup so that it is
+//! "self-correcting" on shell launch, rather than writing the generated completions to a file.
+//!
 //! Bash
 //! ```bash
 //! echo "source <(COMPLETE=bash your_program)" >> ~/.bashrc
@@ -276,6 +283,10 @@ pub trait EnvCompleter {
     ///
     /// Write the `buf` the logic needed for calling into `<VAR>=<shell> <cmd> --`, passing needed
     /// arguments to [`EnvCompleter::write_complete`] through the environment.
+    ///
+    /// **WARNING:** There are no stability guarantees between the call to
+    /// [`EnvCompleter::write_complete`] that this generates and actually calling [`EnvCompleter::write_complete`].
+    /// Caching the results of this call may result in invalid or no completions to be generated.
     fn write_registration(
         &self,
         var: &str,