Update help message of jj edit, add FAQ on idiomatic change switching

cli/src/commands/edit.rs

@@ -21,10 +21,12 @@ use crate::cli_util::{CommandHelper, RevisionArg};
 use crate::command_error::CommandError;
 use crate::ui::Ui;
 
-/// Edit a commit in the working copy
+/// Sets the specified revision as the working-copy revision
 ///
-/// Puts the contents of a commit in the working copy for editing. Any changes
-/// you make in the working copy will update (amend) the commit.
+/// Note: it is generally recommended to instead use `jj new` and `jj
+/// squash`.
+///
+/// For more information, see https://martinvonz.github.io/jj/latest/FAQ#how-do-i-resume-working-on-an-existing-change
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct EditArgs {
     /// The commit to edit

cli/tests/cli-reference@.md.snap

@@ -113,7 +113,7 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
 * `diff` — Compare file contents between two revisions
 * `diffedit` — Touch up the content changes in a revision with a diff editor
 * `duplicate` — Create a new change with the same content as an existing one
-* `edit` — Edit a commit in the working copy
+* `edit` — Sets the specified revision as the working-copy revision
 * `files` — List files in a revision
 * `git` — Commands for working with the underlying Git repo
 * `init` — Create a new repo in the given directory
@@ -707,9 +707,11 @@ Create a new change with the same content as an existing one
 
 ## `jj edit`
 
-Edit a commit in the working copy
+Sets the specified revision as the working-copy revision
 
-Puts the contents of a commit in the working copy for editing. Any changes you make in the working copy will update (amend) the commit.
+Note: it is generally recommended to instead use `jj new` and `jj squash`.
+
+For more information, see https://martinvonz.github.io/jj/latest/FAQ#how-do-i-resume-working-on-an-existing-change
 
 **Usage:** `jj edit <REVISION>`
 

docs/FAQ.md

@@ -137,6 +137,20 @@ commit, then run `jj restore --from Y --to @-` to restore the parent commit
 to the old state, and `jj restore --from X` to restore the new working-copy
 commit to the new state.
 
+### How do I resume working on an existing change?
+
+There are two ways to resume working on an earlier change: `jj new` then `jj squash`,
+and `jj edit`. The first is generally recommended, but `jj edit` can be useful. When 
+you use `jj edit`, the revision is directly amended with your new changes, making it
+difficult to tell what exactly you change. You should avoid using `jj edit` when the
+revision has a conflict, as you may accidentally break the plain-text annotations on
+your state without realising.
+
+To start, use `jj new <rev>` to create a change based on that earlier revision. Make
+your edits, then use `jj squash` to update the earlier revision with those edits.
+For when you would use git stashing, use `jj edit <rev>` for expected behaviour. 
+Other workflows may prefer `jj edit` as well.
+
 ### How do I deal with divergent changes ('??' after the [change ID])?
 
 A [divergent change][glossary_divergent_change] represents a change that has two