Improve squash confirm message and other user-facing info (#1181)

* Improve squash confirm message

* Spelling

* Explain what dev_mode actually does

* +why extract is useful

* + wipe resets schema, but preserves migrations

* Assurance that wipe doesn't touch config

* More detail to help with choices

* Clarify what choices do

* Change tense back

* Update src/migrations/squash.rs

Co-authored-by: Devon Campbell <[email protected]>

---------

Co-authored-by: Devon Campbell <[email protected]>

src/commands/parser.rs

@@ -126,9 +126,11 @@ pub struct Database {
 pub enum DatabaseCmd {
     /// Create a new database
     Create(CreateDatabase),
-    /// Delete database along with its data
+    /// Delete a database along with its data
     Drop(DropDatabase),
-    /// Preserve database while deleting its data
+    /// Delete a database's data and reset its schema while
+    /// preserving the database itself (its cfg::DatabaseConfig) 
+    /// and existing migration scripts
     Wipe(WipeDatabase),
 }
 

src/migrations/create.rs

@@ -216,17 +216,17 @@ async fn choice(prompt: &str) -> anyhow::Result<Choice> {
 
     let mut q = question::Choice::new(prompt.to_string());
     q.option(Yes, &["y", "yes"],
-        "Confirm the prompt, use the DDL statements");
+        r#"Confirm the prompt ("l" to see suggested statements)"#);
     q.option(No, &["n", "no"],
-        "Reject the prompt");
+        "Reject the prompt; server will attempt to generate another suggestion");
     q.option(List, &["l", "list"],
-        "List DDL statements associated with the prompt");
+        "List proposed DDL statements for the current prompt");
     q.option(Confirmed, &["c", "confirmed"],
-        "List already confirmed EdgeQL statements");
+        "List already confirmed EdgeQL statements for the current migration");
     q.option(Back, &["b", "back"],
-        "Revert to previous save point");
+        "Go back a step by reverting latest accepted statements");
     q.option(Split, &["s", "stop"],
-        "Stop and save changes (splits migration into multiple)");
+        "Stop and finalize migration with only current accepted changes");
     q.option(Quit, &["q", "quit"],
         "Quit without saving changes");
     q.async_ask().await
@@ -600,7 +600,7 @@ impl InteractiveMigration<'_> {
                     }
                     Back => {
                         if self.save_point == 0 {
-                            eprintln!("Already at latest savepoint");
+                            eprintln!("No EdgeQL statements confirmed, nothing to move back from");
                             continue;
                         }
                         self.save_point -= 1;

src/migrations/options.rs

@@ -40,7 +40,10 @@ pub enum MigrationCmd {
     /// Check if current schema is compatible with new EdgeDB version
     UpgradeCheck(UpgradeCheck),
     /// Extract migration history from the database and write it to
-    /// <schema-dir>/migrations.
+    /// <schema-dir>/migrations. Useful when a direct DDL command has
+    /// been used to change the schema and now `edgedb migrate` will not
+    /// comply because the database migration history is ahead of the
+    /// migration history inside <schema-dir>/migrations.
     Extract(ExtractMigrations),
 }
 
@@ -102,13 +105,18 @@ pub struct Migrate {
     #[arg(long, conflicts_with="dev_mode")]
     pub to_revision: Option<String>,
 
-    /// Apply current schema changes on top of those found in the migration history
+    /// Dev mode is used to temporarily apply schema on top of those found in
+    /// the migration history. Usually used for testing purposes, as well as
+    /// `edgedb watch` which creates a dev mode migration script each time
+    /// a file is saved by a user.
+    /// 
+    /// Current dev mode migrations can be seen with the following query:
+    /// 
+    /// `select schema::Migration {*} filter .generated_by = schema::MigrationGeneratedBy.DevMode;`
     ///
-    /// This is commonly used to apply schema temporarily before doing
-    /// `migration create` for testing purposes.
-    ///
-    /// This works the same way as `edgedb watch` but without starting
-    /// a long-running watch task.
+    /// `edgedb migration create` followed by `edgedb migrate --dev-mode` will
+    /// then finalize a migration by turning existing dev mode migrations into
+    /// a regular `.edgeql` file, after which the above query will return nothing.
     #[arg(long)]
     pub dev_mode: bool,
 }

src/migrations/squash.rs

@@ -127,16 +127,16 @@ async fn create_revision(cli: &mut Connection, ctx: &Context,
 }
 
 async fn confirm_squashing(db_rev: &str) -> anyhow::Result<()> {
-    echo!("Current database revision is:", db_rev.emphasize());
-    echo!("Squash operation is non-destructive, but may require manual work \
+    echo!("Current database revision:", db_rev.emphasize());
+    echo!("While squashing migrations is non-destructive, it may lead to manual work \
            if done incorrectly.");
     echo!("");
-    echo!("Items to check before doing squash:");
-    echo!("  1. Ensure that `./dbschema` dir is comitted");
-    echo!("  2. Ensure that other users of the database have the revision \
-        above or can create database from scratch.\n     \
-                To check a specific instance, run:");
-    echo!("       edgedb -I <name> migration log --from-db --limit 1"
+    echo!("Items to check before using --squash:");
+    echo!("  1. Ensure that the `./dbschema` dir is committed to version control");
+    echo!("  2. Ensure that other users of the database either have all .edgeql files\n     \
+                up to the revision above or can create the database from scratch.\n \
+                Hint: To see the current revision for a specific instance, run:");
+    echo!("       edgedb -I <name> migration log --from-db --newest-first --limit 1"
           .command_hint());
     echo!("  3. Merge version control branches that contain schema changes \
                 if possible.");