bug#63690: 29.0.91; New vc commands missing on vc-menu

bug#63690: 29.0.91; New vc commands missing on vc-menu

[Juri Linkov]

etc/NEWS on emacs-29 contains:

  'vc-print-branch-log' is bound to 'C-x v b l', and new commands are
  'vc-create-branch' ('C-x v b c') and 'vc-switch-branch' ('C-x v b s').

But new commands are not yet added to 'vc-menu-map'.
This patch for emacs-29 fixes this omission:

diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
index 02c4a240c6a..402b918fc7d 100644
--- a/lisp/vc/vc-hooks.el
+++ b/lisp/vc/vc-hooks.el
@@ -898,6 +927,15 @@ vc-menu-map
     (bindings--define-key map [vc-create-tag]
       '(menu-item "Create Tag" vc-create-tag
 		  :help "Create version tag"))
+    (bindings--define-key map [vc-print-branch-log]
+      '(menu-item "Show Branch History" vc-print-branch-log
+		  :help "Show the change log for branch root"))
+    (bindings--define-key map [vc-switch-branch]
+      '(menu-item "Switch Branch" vc-switch-branch
+		  :help "Switch to the branch"))
+    (bindings--define-key map [vc-create-branch]
+      '(menu-item "Create Branch" vc-create-branch
+		  :help "Make a new branch"))
     (bindings--define-key map [separator1] menu-bar-separator)
     (bindings--define-key map [vc-annotate]
       '(menu-item "Annotate" vc-annotate

bug#63690: 29.0.91; New vc commands missing on vc-menu

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Date: Wed, 24 May 2023 19:16:23 +0300
> 
> etc/NEWS on emacs-29 contains:
> 
>   'vc-print-branch-log' is bound to 'C-x v b l', and new commands are
>   'vc-create-branch' ('C-x v b c') and 'vc-switch-branch' ('C-x v b s').
> 
> But new commands are not yet added to 'vc-menu-map'.
> This patch for emacs-29 fixes this omission:

Thanks.  This is okay, but the help-echo text "needs work".

> diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
> index 02c4a240c6a..402b918fc7d 100644
> --- a/lisp/vc/vc-hooks.el
> +++ b/lisp/vc/vc-hooks.el
> @@ -898,6 +927,15 @@ vc-menu-map
>      (bindings--define-key map [vc-create-tag]
>        '(menu-item "Create Tag" vc-create-tag
>  		  :help "Create version tag"))
> +    (bindings--define-key map [vc-print-branch-log]
> +      '(menu-item "Show Branch History" vc-print-branch-log
> +		  :help "Show the change log for branch root"))

What is "branch root"?

> +    (bindings--define-key map [vc-switch-branch]
> +      '(menu-item "Switch Branch" vc-switch-branch
> +		  :help "Switch to the branch"))

"the" branch?

Also, AFAICT these commands are not described in the manual.  If they
are important enough to be on the menu bar, I think we should mention
them in the manual as well, no?

bug#63690: 29.0.91; New vc commands missing on vc-menu

[Juri Linkov]

>> @@ -898,6 +927,15 @@ vc-menu-map
>> +    (bindings--define-key map [vc-print-branch-log]
>> +      '(menu-item "Show Branch History" vc-print-branch-log
>> +		  :help "Show the change log for branch root"))
>
> What is "branch root"?

Probably better to drop the word "root" to e.g.:

  "List the change log for branch"

Then docstring of 'vc-print-branch-log' could be changed too.

>> +    (bindings--define-key map [vc-switch-branch]
>> +      '(menu-item "Switch Branch" vc-switch-branch
>> +		  :help "Switch to the branch"))
>
> "the" branch?

Maybe "the selected branch".  Then it may need an ellipsis:
"Switch Branch..."

> Also, AFAICT these commands are not described in the manual.  If they
> are important enough to be on the menu bar, I think we should mention
> them in the manual as well, no?

They are mentioned briefly in

  (info "(emacs) Creating Branches")
  (info "(emacs) Switching Branches")
  (info "(emacs) Editing VC Commands")

bug#63690: 29.0.91; New vc commands missing on vc-menu

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 63690@debbugs.gnu.org
> Date: Wed, 24 May 2023 20:31:21 +0300
> 
> >> @@ -898,6 +927,15 @@ vc-menu-map
> >> +    (bindings--define-key map [vc-print-branch-log]
> >> +      '(menu-item "Show Branch History" vc-print-branch-log
> >> +		  :help "Show the change log for branch root"))
> >
> > What is "branch root"?
> 
> Probably better to drop the word "root" to e.g.:
> 
>   "List the change log for branch"

This prompts for the branch to log, right?  Then the menu item should
ends in a "...", and the help text should be

   "List the change log for a branch"

> Then docstring of 'vc-print-branch-log' could be changed too.

Yes, and it should say that the command prompts for the branch to log.

> >> +    (bindings--define-key map [vc-switch-branch]
> >> +      '(menu-item "Switch Branch" vc-switch-branch
> >> +		  :help "Switch to the branch"))
> >
> > "the" branch?
> 
> Maybe "the selected branch".

I think

  "Switch to another branch"

> Then it may need an ellipsis:
> "Switch Branch..."

Yes.

> > Also, AFAICT these commands are not described in the manual.  If they
> > are important enough to be on the menu bar, I think we should mention
> > them in the manual as well, no?
> 
> They are mentioned briefly in
> 
>   (info "(emacs) Creating Branches")
>   (info "(emacs) Switching Branches")
>   (info "(emacs) Editing VC Commands")

Mentioned, but not indexed.  Please always index every command
described in the manual, both its name and its key binding (if any).
This is necessary to allow users to find the description of each
command quickly and easily.

Also, vc-print-branch-log is not really described, it's just used in
an unrelated example of using a different feature.

bug#63690: 29.0.91; New vc commands missing on vc-menu

[Juri Linkov]

>> > What is "branch root"?
>> 
>> Probably better to drop the word "root" to e.g.:
>> 
>>   "List the change log for branch"
>
> This prompts for the branch to log, right?  Then the menu item should
> ends in a "...", and the help text should be
>
>    "List the change log for a branch"
>
>> Then docstring of 'vc-print-branch-log' could be changed too.
>
> Yes, and it should say that the command prompts for the branch to log.
>
>> >> +    (bindings--define-key map [vc-switch-branch]
>> >> +      '(menu-item "Switch Branch" vc-switch-branch
>> >> +		  :help "Switch to the branch"))
>> >
>> > "the" branch?
>> 
>> Maybe "the selected branch".
>
> I think
>
>   "Switch to another branch"
>
>> Then it may need an ellipsis:
>> "Switch Branch..."
>
> Yes.

These are fixed in the following patch.

>> > Also, AFAICT these commands are not described in the manual.  If they
>> > are important enough to be on the menu bar, I think we should mention
>> > them in the manual as well, no?
>> 
>> They are mentioned briefly in
>> 
>>   (info "(emacs) Creating Branches")
>>   (info "(emacs) Switching Branches")
>>   (info "(emacs) Editing VC Commands")
>
> Mentioned, but not indexed.  Please always index every command
> described in the manual, both its name and its key binding (if any).
> This is necessary to allow users to find the description of each
> command quickly and easily.
>
> Also, vc-print-branch-log is not really described, it's just used in
> an unrelated example of using a different feature.

I can't find an existing Info node to document vc-print-branch-log.
(info "(emacs) Branches") has such submenus:

* Menu:
* Switching Branches::    How to get to another existing branch.
* Pulling / Pushing::     Receiving/sending changes from/to elsewhere.
* Merging::               Transferring changes between branches.
* Creating Branches::     How to start a new branch.

Maybe vc-print-branch-log could be mentioned
directly in (info "(emacs) Branches")?

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 7d49e28d11f..2a81b9b6cc6 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1523,6 +1523,8 @@ Switching Branches
 Mercurial, command @kbd{hg update} is used to switch to another
 branch.
 
+@kindex C-x v b s
+@findex vc-switch-branch
   The VC command to switch to another branch in the current directory
 is @kbd{C-x v b s @var{branch-name} @key{RET}} (@code{vc-switch-branch}).
 
@@ -1673,6 +1675,8 @@ Creating Branches
 if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
 and so on, depending on the number of existing branches at that point.
 
+@kindex C-x v b c
+@findex vc-create-branch
   This procedure will not work for distributed version control systems
 like git or Mercurial.  For those systems you should use the command
 @code{vc-create-branch} (@kbd{C-x v b c}) instead.
diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
index e242d1e48e2..05ad45d93e8 100644
--- a/lisp/vc/vc-hooks.el
+++ b/lisp/vc/vc-hooks.el
@@ -897,6 +927,15 @@ vc-menu-map
     (bindings--define-key map [vc-create-tag]
       '(menu-item "Create Tag" vc-create-tag
 		  :help "Create version tag"))
+    (bindings--define-key map [vc-print-branch-log]
+      '(menu-item "Show Branch History..." vc-print-branch-log
+		  :help "List the change log for a branch"))
+    (bindings--define-key map [vc-switch-branch]
+      '(menu-item "Switch Branch..." vc-switch-branch
+		  :help "Switch to another branch"))
+    (bindings--define-key map [vc-create-branch]
+      '(menu-item "Create Branch..." vc-create-branch
+		  :help "Make a new branch"))
     (bindings--define-key map [separator1] menu-bar-separator)
     (bindings--define-key map [vc-annotate]
       '(menu-item "Annotate" vc-annotate
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index 91d3f6f70d3..915ba1bad7a 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -2851,7 +2851,8 @@ vc-print-root-log
 
 ;;;###autoload
 (defun vc-print-branch-log (branch)
-  "Show the change log for BRANCH root in a window."
+  "Show the change log for BRANCH in a window.
+The command prompts for the branch to log."
   (interactive
    (let* ((backend (vc-responsible-backend default-directory))
           (rootdir (vc-call-backend backend 'root default-directory)))

bug#63690: 29.0.91; New vc commands missing on vc-menu

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: 63690@debbugs.gnu.org
> Date: Thu, 25 May 2023 09:43:58 +0300
> 
> These are fixed in the following patch.

Thanks, LGTM.  Please install on the release branch.

> >>   (info "(emacs) Creating Branches")
> >>   (info "(emacs) Switching Branches")
> >>   (info "(emacs) Editing VC Commands")
> >
> > Mentioned, but not indexed.  Please always index every command
> > described in the manual, both its name and its key binding (if any).
> > This is necessary to allow users to find the description of each
> > command quickly and easily.
> >
> > Also, vc-print-branch-log is not really described, it's just used in
> > an unrelated example of using a different feature.
> 
> I can't find an existing Info node to document vc-print-branch-log.
> (info "(emacs) Branches") has such submenus:
> 
> * Menu:
> * Switching Branches::    How to get to another existing branch.
> * Pulling / Pushing::     Receiving/sending changes from/to elsewhere.
> * Merging::               Transferring changes between branches.
> * Creating Branches::     How to start a new branch.
> 
> Maybe vc-print-branch-log could be mentioned
> directly in (info "(emacs) Branches")?

Mentioned there, yes.  But maybe it should be described in full in "VC
Change Log"?

bug#63690: 29.0.91; New vc commands missing on vc-menu

[Juri Linkov]

close 63690 29.0.60
thanks

>> These are fixed in the following patch.
>
> Thanks, LGTM.  Please install on the release branch.
>
>> Maybe vc-print-branch-log could be mentioned
>> directly in (info "(emacs) Branches")?
>
> Mentioned there, yes.  But maybe it should be described in full in "VC
> Change Log"?

Now installed on the release branch.