bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Drew Adams]

Consider adding `M-x report-emacs-bug' to the splash page.
(And consider pointing out the Help menu, on the splash page.)

Here is one indication that a new user might not know how to file a
bug report: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20628#284

  This is a bug that had annoyed me 4 or 5 years ago when I first used
  Emacs, but at that time I didn't really know how to report bugs.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Consider adding `M-x report-emacs-bug' to the splash page.
> (And consider pointing out the Help menu, on the splash page.)
>
> Here is one indication that a new user might not know how to file a
> bug report: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20628#284
>
>   This is a bug that had annoyed me 4 or 5 years ago when I first used
>   Emacs, but at that time I didn't really know how to report bugs.

There's already too much verbiage on the splash screen, but perhaps this
would make sense...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 688 bytes --]

tags 20697 + patch
quit

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Drew Adams <drew.adams@oracle.com> writes:
>
>> Consider adding `M-x report-emacs-bug' to the splash page.
>> (And consider pointing out the Help menu, on the splash page.)
>>
>> Here is one indication that a new user might not know how to file a
>> bug report: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20628#284
>>
>>   This is a bug that had annoyed me 4 or 5 years ago when I first used
>>   Emacs, but at that time I didn't really know how to report bugs.
>
> There's already too much verbiage on the splash screen, but perhaps this
> would make sense...

How about the attached patch?

Thanks,
Stefan Kangas

[-- Attachment #2: 0001-Add-Reporting-Bugs-link-to-about-screen.patch --]
[-- Type: text/x-patch, Size: 2038 bytes --]

From dd55db518e27615ef871d19eede9a20cf71832b6 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Wed, 21 Aug 2019 02:37:41 +0200
Subject: [PATCH] Add "Reporting Bugs" link to about screen

* lisp/help.el (view-emacs-howto-report-bugs): New function.
* lisp/startup.el (fancy-about-text, normal-about-screen): Add link
"Reporting Bugs".  (Bug#20697)
---
 lisp/help.el    |  5 +++++
 lisp/startup.el | 10 +++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/lisp/help.el b/lisp/help.el
index e40178de96..1f0d0e8e36 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -438,6 +438,11 @@ view-emacs-FAQ
   (interactive)
   (info "(efaq)"))
 
+(defun view-emacs-howto-report-bugs ()
+  "Display information on how to report bugs in Emacs."
+  (interactive)
+  (info "(emacs)Bugs"))
+
 (defun view-emacs-problems ()
   "Display info on known problems with Emacs and possible workarounds."
   (interactive)
diff --git a/lisp/startup.el b/lisp/startup.el
index 564428580b..c8a651c4aa 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1596,6 +1596,8 @@ fancy-about-text
      :link ("Contributing"
 	    ,(lambda (_button) (info "(emacs)Contributing")))
      "\tHow to contribute improvements to Emacs\n"
+     :link ("Report Bugs" ,(lambda (_button) (view-emacs-howto-report-bugs)))
+     "\tHow to report bugs in Emacs\n"
      "\n"
      :link ("GNU and Freedom" ,(lambda (_button) (describe-gnu-project)))
      "\tWhy we developed GNU Emacs, and the GNU operating system\n"
@@ -2174,7 +2176,13 @@ normal-about-screen
 		 'action
 		 (lambda (_button) (info "(emacs)Contributing"))
 		 'follow-link t)
-  (insert "\tHow to contribute improvements to Emacs\n\n")
+  (insert "\tHow to contribute improvements to Emacs\n")
+
+  (insert-button "Reporting Bugs"
+		 'action
+		 (lambda (_button) (view-emacs-howto-report-bugs))
+		 'follow-link t)
+  (insert "\tHow to report bugs in Emacs\n\n")
 
   (insert-button "GNU and Freedom"
 		 'action (lambda (_button) (describe-gnu-project))
-- 
2.20.1

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Drew Adams]

Thanks for doing this.

The only thing I'd suggest is to maybe have the text say something like this:

"How to report Emacs bugs and enhancement requests"

I think people often don't know that `M-x report-emacs-bug' is also for enhancement requests.

But if the text mentions it then maybe so should node (emacs) `Bugs'.

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

>       "\tHow to contribute improvements to Emacs\n"
> +     :link ("Report Bugs" ,(lambda (_button) (view-emacs-howto-report-bugs)))
> +     "\tHow to report bugs in Emacs\n"
>       "\n"

So this basically adds another line and links directly to the Bugs info
page.  Hm.  Would it be possible to instead just change the line

Contributing	How to contribute improvements to Emacs

to something like the following?  That link already links to the bug
reporting page...

Contributing	How to report bugs and contribute improvements

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Stefan Kangas <stefan@marxist.se> writes:
>
> >       "\tHow to contribute improvements to Emacs\n"
> > +     :link ("Report Bugs" ,(lambda (_button) (view-emacs-howto-report-bugs)))
> > +     "\tHow to report bugs in Emacs\n"
> >       "\n"
>
> So this basically adds another line and links directly to the Bugs info
> page.  Hm.  Would it be possible to instead just change the line
>
> Contributing    How to contribute improvements to Emacs
>
> to something like the following?  That link already links to the bug
> reporting page...
>
> Contributing    How to report bugs and contribute improvements

I had missed that, but you're absolutely correct and I agree that its
a better solution.

There was also a suggestion by Drew in the original post to mention
the Help menu as well.  Is that something we want to do?  But then,
wouldn't we also want to suggest C-h C-h, C-h C-i, etc.?  Maybe a
better alternative would be to add the Emacs Manual at the bottom,
after the link to the guided tour?  (And, but maybe that's just me, to
move all the help topics ("Emacs Tutorial", "Emacs Guided Tour") to
the top?)

Thanks,
Stefan Kangas

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Drew Adams]

> > So this basically adds another line and links directly to the Bugs
> info
> > page.  Hm.  Would it be possible to instead just change the line
> >
> > Contributing    How to contribute improvements to Emacs
> >
> > to something like the following?  That link already links to the bug
> > reporting page...
> >
> > Contributing    How to report bugs and contribute improvements
> 
> I had missed that, but you're absolutely correct and I agree that its
> a better solution.
> 
> There was also a suggestion by Drew in the original post to mention
> the Help menu as well.  Is that something we want to do?  But then,
> wouldn't we also want to suggest C-h C-h, C-h C-i, etc.?  Maybe a
> better alternative would be to add the Emacs Manual at the bottom,
> after the link to the guided tour?  (And, but maybe that's just me, to
> move all the help topics ("Emacs Tutorial", "Emacs Guided Tour") to
> the top?)

I saw that "How to contribute..." but I thought/think
its destination is to the doc section about contributing.

If so, that's not quite the same thing.

It would be OK to have a single link that points to
something that covered both (1) `report-emacs-bug',
mentioning that that's also for enhancement requests,
and (2) how to contribute in a deeper way: GIT, patches
etc.

[Mentioning also enhancement requests was my input
for this bug thread.]

But in that case, the more lightweight feedback, #1,
should be separated and up front, so users wanting
to report a bug or suggest an enhancement need not
find themselves immediately in the depths of how to
contribute in a deeper way.

We want (IMO) to encourage lots of users to provide
relatively easy feedback, beyond also wanting some
users to get more deeply involved.  We don't want
people to get the impression that lightweight
suggestions are not possible or encouraged, and that
a heavy commitment is the only encouraged participation.

Just one opinion.

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> There was also a suggestion by Drew in the original post to mention
> the Help menu as well.  Is that something we want to do?  But then,
> wouldn't we also want to suggest C-h C-h, C-h C-i, etc.?

Hm...  The "About" screen already has too much text, in my opinion --
and adding more will only discourage reading what's already there.

Perhaps the "Absence of Warranty" and "Copying Conditions" could be
merged into one line?

> Maybe a better alternative would be to add the Emacs Manual at the
> bottom, after the link to the guided tour?  (And, but maybe that's
> just me, to move all the help topics ("Emacs Tutorial", "Emacs Guided
> Tour") to the top?)

Yes, it is kinda odd that there's no links to the manual on that page.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 674 bytes --]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Perhaps the "Absence of Warranty" and "Copying Conditions" could be
> merged into one line?

Are there any legal implications here?  Otherwise, I agree that it
would be a good change.

> > Maybe a better alternative would be to add the Emacs Manual at the
> > bottom, after the link to the guided tour?  (And, but maybe that's
> > just me, to move all the help topics ("Emacs Tutorial", "Emacs Guided
> > Tour") to the top?)
>
> Yes, it is kinda odd that there's no links to the manual on that page.

Please see the attached patch.  I've incorporated your suggestion and
added a link to the manual.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Add-bug-reporting-info-and-link-the-manual-on-the-ab.patch --]
[-- Type: text/x-patch, Size: 2367 bytes --]

From 7bf8666856fcfdc34823b59150eb6394896b2987 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 13 Sep 2019 21:23:24 +0200
Subject: [PATCH] Add bug reporting info and link the manual on the about
 screen

* lisp/startup.el (fancy-about-text, normal-about-screen): Clarify
that "Contribute" also describes how to report bugs.  Add new link
"Emacs Manual".  (Bug#20697)
---
 lisp/startup.el | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/lisp/startup.el b/lisp/startup.el
index ef6234128a..243eb8c34a 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1632,7 +1632,7 @@ fancy-about-text
      "\tMany people have contributed code included in GNU Emacs\n"
      :link ("Contributing"
 	    ,(lambda (_button) (info "(emacs)Contributing")))
-     "\tHow to contribute improvements to Emacs\n"
+     "\tHow to report bugs and contribute improvements to Emacs\n"
      "\n"
      :link ("GNU and Freedom" ,(lambda (_button) (describe-gnu-project)))
      "\tWhy we developed GNU Emacs, and the GNU operating system\n"
@@ -1648,6 +1648,8 @@ fancy-about-text
      :link ("Ordering Manuals" ,(lambda (_button) (view-order-manuals)))
      "\tBuying printed manuals from the FSF\n"
      "\n"
+     :link ("Emacs Manual" ,(lambda (_button) (info-emacs-manual)))
+     "\tDisplay the Emacs manual in Info mode\n"
      :link ("Emacs Tutorial" ,(lambda (_button) (help-with-tutorial)))
      "\tLearn basic Emacs keystroke commands"
      ,(lambda ()
@@ -1674,7 +1676,7 @@ fancy-about-text
 	    ,(lambda (_button)
                (browse-url "https://www.gnu.org/software/emacs/tour/"))
 	    "Browse https://www.gnu.org/software/emacs/tour/")
-     "\tSee an overview of Emacs features at gnu.org"))
+     "\tSee an overview of Emacs features at gnu.org\n"))
   "A list of texts to show in the middle part of the About screen.
 Each element in the list should be a list of strings or pairs
 `:face FACE', like `fancy-splash-insert' accepts them.")
@@ -2211,7 +2213,7 @@ normal-about-screen
 		 'action
 		 (lambda (_button) (info "(emacs)Contributing"))
 		 'follow-link t)
-  (insert "\tHow to contribute improvements to Emacs\n\n")
+  (insert "\tHow to report bugs and contribute improvements to Emacs\n")
 
   (insert-button "GNU and Freedom"
 		 'action (lambda (_button) (describe-gnu-project))
-- 
2.20.1

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

> > > So this basically adds another line and links directly to the Bugs
> > info
> > > page.  Hm.  Would it be possible to instead just change the line
> > >
> > > Contributing    How to contribute improvements to Emacs
> > >
> > > to something like the following?  That link already links to the bug
> > > reporting page...
> > >
> > > Contributing    How to report bugs and contribute improvements
> >
> > I had missed that, but you're absolutely correct and I agree that its
> > a better solution.
>
> I saw that "How to contribute..." but I thought/think
> its destination is to the doc section about contributing.
>
> If so, that's not quite the same thing.
>
> It would be OK to have a single link that points to
> something that covered both (1) `report-emacs-bug',
> mentioning that that's also for enhancement requests,
> and (2) how to contribute in a deeper way: GIT, patches
> etc.

(info "(emacs) Contributing") already says on the top of the page:

   There are many ways to contribute to Emacs:

   • find and report bugs; *Note Bugs::.

So I think this is already a good landing page for both bugs and contributions.

> [Mentioning also enhancement requests was my input
> for this bug thread.]

Do you have any ideas for how to better emphasize enhancement
requests?  Should it be a separate bullet point on the "Contribute"
page perhaps?

> But in that case, the more lightweight feedback, #1,
> should be separated and up front, so users wanting
> to report a bug or suggest an enhancement need not
> find themselves immediately in the depths of how to
> contribute in a deeper way.

I think that it's fine that users can click the link on the top of the
page to reach (info "(emacs) Bugs").  It's separate enough, and early
enough, that users can easily click on it and ignore the rest of the
page, in my opinion.

> We want (IMO) to encourage lots of users to provide
> relatively easy feedback, beyond also wanting some
> users to get more deeply involved.  We don't want
> people to get the impression that lightweight
> suggestions are not possible or encouraged, and that
> a heavy commitment is the only encouraged participation.

I absolutely agree.

Best regards,
Stefan Kangas

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Drew Adams]

>    There are many ways to contribute to Emacs:
>    • find and report bugs; *Note Bugs::.
> 
> So I think this is already a good landing page for both bugs and
> contributions.

Yes.

> > [Mentioning also enhancement requests was my input
> > for this bug thread.]
> 
> Do you have any ideas for how to better emphasize enhancement
> requests?  Should it be a separate bullet point on the "Contribute"
> page perhaps?

My suggestion is to put it explicitly in the text/link
that then leads you to the doc section that covers all
of this.

Although "contribute improvements" covers suggesting
enhancements, I think the former suggests more
substantial contribution than just asking for or
suggesting a possible enhancement - something wished.

I think it's important for users to see, up front,
an invitation to make even minor or undeveloped, even
possibly infeasible or not-well-thought-through
suggestions.

If that invitation is found only after following some
"contribute" link to doc that covers everything,
including full-blown patches, then its effect on
inviting superficial suggestions can be lost.

So I'd "waste" a few extra chars to spell out that
invitation explicitly.  Something like this:

 "How to report bugs and suggest or contribute possible improvements"

> > But in that case, the more lightweight feedback, #1,
> > should be separated and up front, so users wanting
> > to report a bug or suggest an enhancement need not
> > find themselves immediately in the depths of how to
> > contribute in a deeper way.
> 
> I think that it's fine that users can click the link on the top of the
> page to reach (info "(emacs) Bugs").  It's separate enough, and early
> enough, that users can easily click on it and ignore the rest of the
> page, in my opinion.

See above.  Separate enough and early enough, perhaps.
But it doesn't explicitly invite suggestions, even
blue-sky suggestions.  That invitation is what I think
is missing up front.

> > We want (IMO) to encourage lots of users to provide
> > relatively easy feedback, beyond also wanting some
> > users to get more deeply involved.  We don't want
> > people to get the impression that lightweight
> > suggestions are not possible or encouraged, and that
> > a heavy commitment is the only encouraged participation.
> 
> I absolutely agree.

Thanks for working on this.  The patch looks good to
me, though I'd prefer to also see what I mention above.

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 13 Sep 2019 21:29:25 +0200
> Cc: 20697@debbugs.gnu.org
> 
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> 
> > Perhaps the "Absence of Warranty" and "Copying Conditions" could be
> > merged into one line?
> 
> Are there any legal implications here?  Otherwise, I agree that it
> would be a good change.

I'd rather we didn't merge them, they are quite different issues.

> @@ -1648,6 +1648,8 @@ fancy-about-text
>       :link ("Ordering Manuals" ,(lambda (_button) (view-order-manuals)))
>       "\tBuying printed manuals from the FSF\n"
>       "\n"
> +     :link ("Emacs Manual" ,(lambda (_button) (info-emacs-manual)))
> +     "\tDisplay the Emacs manual in Info mode\n"

This should come after the Overview, IMO.

> -     "\tSee an overview of Emacs features at gnu.org"))
> +     "\tSee an overview of Emacs features at gnu.org\n"))

Why do we need this extra newline?

Thanks.

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 2660 bytes --]

Drew Adams <drew.adams@oracle.com> writes:

> > Do you have any ideas for how to better emphasize enhancement
> > requests?  Should it be a separate bullet point on the "Contribute"
> > page perhaps?
>
> My suggestion is to put it explicitly in the text/link
> that then leads you to the doc section that covers all
> of this.
>
> Although "contribute improvements" covers suggesting
> enhancements, I think the former suggests more
> substantial contribution than just asking for or
> suggesting a possible enhancement - something wished.
>
> I think it's important for users to see, up front,
> an invitation to make even minor or undeveloped, even
> possibly infeasible or not-well-thought-through
> suggestions.
>
> If that invitation is found only after following some
> "contribute" link to doc that covers everything,
> including full-blown patches, then its effect on
> inviting superficial suggestions can be lost.
>
> So I'd "waste" a few extra chars to spell out that
> invitation explicitly.  Something like this:
>
>  "How to report bugs and suggest or contribute possible improvements"

I find that line a bit too packed with information to be easily
parsed.  I think that the concern Lars has pointed out is valid here:
the about screen is already very dense.

I came up with the attached tentative patch that adds a paragraph to
"Contributing" manual page, attached here for discussion.

But thinking about this a bit more, I can't decide if it's a good idea
to encourage this or not.  There is a risk that we get too many low
quality suggestions that we will waste a lot of time handling.  But
perhaps that's an unwarranted fear, and the biggest problem in the
long run might be users that feel distant and disengaged from Emacs
development.  Encouraging feature suggestions might help draw in new
developers.

On the other hand, what we need more than suggestions would be patches
to fix what is already in the bug tracker, and this doesn't do much to
help that.  There are already many worthy and good projects in the bug
tracker, suitable for everything from beginners to experts.  More low
quality feature requests would make it harder to find these requests
in the bug tracker, thus raising the barrier for new developers.

So I see both arguments as valid here, and I'm conflicted between
them.  Since it's a social issue more than a technical one, I'm not
sure there is one correct answer.

Perhaps the question is simply if this is subjectively desirable from
the point of view of the leading Emacs developers?  After all, they
are the ones who will do the majority of the work handling these
suggestions.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Document-feature-requests-in-the-Emacs-manual.patch --]
[-- Type: text/x-patch, Size: 1341 bytes --]

From 009c01d9df3103d0e0828dfb6a5fa8dcd5aca2ba Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 14 Sep 2019 13:27:10 +0200
Subject: [PATCH] Document feature requests in the Emacs manual

* doc/emacs/trouble.texi (Contributing): Document feature
requests.  (Bug20697)
---
 doc/emacs/trouble.texi | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 13d3e8475c..17de6edec8 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1299,6 +1299,19 @@ Contributing
 @end ifhtml
 You can ask for suggested projects or suggest your own ideas.
 
+If you have a feature request or a suggestion for how to improve
+Emacs, the best place to send it is to
+@ifnothtml
+@email{bug-gnu-emacs.org}
+@end ifnothtml
+@ifhtml
+@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}
+@end ifhtml
+.  Please explain in clear language exactly what change you would like
+to see, and why and how you think it would improve Emacs.  If your
+suggestion is accepted, this will allow it to stand a better chance of
+attracting interest from one of many volunteer Emacs developers.
+
 If you have already written an improvement, please tell us about it.  If
 you have not yet started work, it is useful to contact
 @ifnothtml
-- 
2.20.1

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 1035 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> > > Perhaps the "Absence of Warranty" and "Copying Conditions" could be
> > > merged into one line?
> >
> > Are there any legal implications here?  Otherwise, I agree that it
> > would be a good change.
>
> I'd rather we didn't merge them, they are quite different issues.

Fine by me.

> > @@ -1648,6 +1648,8 @@ fancy-about-text
> >       :link ("Ordering Manuals" ,(lambda (_button) (view-order-manuals)))
> >       "\tBuying printed manuals from the FSF\n"
> >       "\n"
> > +     :link ("Emacs Manual" ,(lambda (_button) (info-emacs-manual)))
> > +     "\tDisplay the Emacs manual in Info mode\n"
>
> This should come after the Overview, IMO.

Fixed.

> > -     "\tSee an overview of Emacs features at gnu.org"))
> > +     "\tSee an overview of Emacs features at gnu.org\n"))
>
> Why do we need this extra newline?

That was included by mistake, but is necessary if the manual is the
last entry.  So I'm keeping it here.

Please find attached an updated patch.

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Add-bug-reporting-and-link-the-manual-on-the-about-s.patch --]
[-- Type: text/x-patch, Size: 2052 bytes --]

From 7eeedc47e183dc7937b73183bd546a86deacc910 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 13 Sep 2019 21:23:24 +0200
Subject: [PATCH] Add bug reporting and link the manual on the about screen

* lisp/startup.el (fancy-about-text, normal-about-screen): Clarify
that "Contribute" also describes how to report bugs.  Add new link
"Emacs Manual".  (Bug#20697)
---
 lisp/startup.el | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/lisp/startup.el b/lisp/startup.el
index ef6234128a..6e569168e2 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1632,7 +1632,7 @@ fancy-about-text
      "\tMany people have contributed code included in GNU Emacs\n"
      :link ("Contributing"
 	    ,(lambda (_button) (info "(emacs)Contributing")))
-     "\tHow to contribute improvements to Emacs\n"
+     "\tHow to report bugs and contribute improvements to Emacs\n"
      "\n"
      :link ("GNU and Freedom" ,(lambda (_button) (describe-gnu-project)))
      "\tWhy we developed GNU Emacs, and the GNU operating system\n"
@@ -1674,7 +1674,9 @@ fancy-about-text
 	    ,(lambda (_button)
                (browse-url "https://www.gnu.org/software/emacs/tour/"))
 	    "Browse https://www.gnu.org/software/emacs/tour/")
-     "\tSee an overview of Emacs features at gnu.org"))
+     "\tSee an overview of Emacs features at gnu.org\n"
+     :link ("Emacs Manual" ,(lambda (_button) (info-emacs-manual)))
+     "\tDisplay the Emacs manual in Info mode"))
   "A list of texts to show in the middle part of the About screen.
 Each element in the list should be a list of strings or pairs
 `:face FACE', like `fancy-splash-insert' accepts them.")
@@ -2211,7 +2213,7 @@ normal-about-screen
 		 'action
 		 (lambda (_button) (info "(emacs)Contributing"))
 		 'follow-link t)
-  (insert "\tHow to contribute improvements to Emacs\n\n")
+  (insert "\tHow to report bugs and contribute improvements to Emacs\n\n")
 
   (insert-button "GNU and Freedom"
 		 'action (lambda (_button) (describe-gnu-project))
-- 
2.20.1

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Please see the attached patch.  I've incorporated your suggestion and
> added a link to the manual.

Thanks; looks good to me (after Eli's comments).

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Drew Adams]

> > > Do you have any ideas for how to better emphasize enhancement
> > > requests?  Should it be a separate bullet point on the "Contribute"
> > > page perhaps?
> >
> > My suggestion is to put it explicitly in the text/link
> > that then leads you to the doc section that covers all
> > of this.
> >
> > Although "contribute improvements" covers suggesting
> > enhancements, I think the former suggests more
> > substantial contribution than just asking for or
> > suggesting a possible enhancement - something wished.
> >
> > I think it's important for users to see, up front,
> > an invitation to make even minor or undeveloped, even
> > possibly infeasible or not-well-thought-through
> > suggestions.
> >
> > If that invitation is found only after following some
> > "contribute" link to doc that covers everything,
> > including full-blown patches, then its effect on
> > inviting superficial suggestions can be lost.
> >
> > So I'd "waste" a few extra chars to spell out that
> > invitation explicitly.  Something like this:
> >
> >  "How to report bugs and suggest or contribute possible improvements"
> 
> I find that line a bit too packed with information to be easily
> parsed.  I think that the concern Lars has pointed out is valid here:
> the about screen is already very dense.

Then get rid of some other parts of the link text or
other parts of the too-dense screen.  Don't get rid
of the part about suggesting improvements.

This bug report is especially about explicitly
inviting enhancement suggestions/wishes.  That needs
to be on top, up-front, in link text - not relegated
to some text at the link target.

IMO, this is important.  Users who really want to
contribute heavily will inevitably find the info
about how to do so.  That's not a problem now.

What's missing, IMO, is a general, well-advertised,
make-it-obvious-that-it's-easy-to-do invitation for
any and all (whatever their Emacs level) to pass
along their suggestions, however blue-sky or half-baked.

That should be one of the _main_ things visible and
obvious on the splash page etc.  It should be one
of our main messages.

Emacs users should learn right off-the-bat that
_they_ are the focus of Emacs: its purpose.
Emacs is developed by its users for its users -
from core, steady, heavy lifters to newbie ride-by
tourists.

> I came up with the attached tentative patch that adds a paragraph to
> "Contributing" manual page, attached here for discussion.
> 
> But thinking about this a bit more, I can't decide if it's a good idea
> to encourage this or not.  There is a risk that we get too many low
> quality suggestions that we will waste a lot of time handling.

I couldn't disagree more with such fear/hesitation.

Nothing requires particular action on any
suggestion.  Nothing even requires consideration
of any given suggestion.

It's important to get Emacs users involved with
their own ideas.  Get them thinking about their
experiences using Emacs and expressing those
thoughts.  All ideas, good as well as not-so-good,
start out raw or at best half-baked.

The emphasis has too long been on setting a high
bar - a premature gate to receiving user input.
Just adding a friendly encouragement to speak up
will help Emacs, not hurt it.

> But perhaps that's an unwarranted fear,

It's not only an unwarranted fear, IMO.  It's
restrictive for no reason.  Far from discouraging,
we should be encouraging suggestions of all sorts.

There's plenty of time after receiving a suggestion
to consider whether it is "low quality".  Prejudging
by discouraging, essentially hiding/suppressing the
invitation, is backward.

> and the biggest problem in the
> long run might be users that feel distant and disengaged from Emacs
> development.  Encouraging feature suggestions might help draw in new
> developers.

Yes, it might draw in new developers.
But Emacs doesn't just need more developers.

It will also put existing developers more in
touch with more user thoughts and experiences -
and provide them with much more food for thought.

Emacs features have often come from beyond its
"core developers", though some such outsiders
later became active developers.  That's just the
way it works.

Even stuff that has become part of distributed
(i.e. vanilla) Emacs started as 3rd-party code -
see `(emacs)Acknowledgments'.  And some features
that many users make heavy use of are still
outside vanilla Emacs.

And plenty of developments have resulted from
suggestions by users who never helped develop
those features.  Any developer of a 3rd-party
library knows how helpful user input is - as food
for thought as well as pointing out problems.

> On the other hand, what we need more than suggestions would be patches
> to fix

It's not one or the other, or one more than the
other.  Those are different things.  But they're
related in the sense that someone encouraged to
contribute a suggestion might later contribute a
bug fix.

> what is already in the bug tracker, and this doesn't do much to
> help that.

That's not its (direct) aim.  (But see previous.)

> There are already many worthy and good projects in the bug
> tracker, suitable for everything from beginners to experts.

Again, that's something else.  As Eli is wont to
say, correctly, things in Emacs get added/changed
because someone had an itch and scratched it.

That someone doesn't want to or doesn't have the
time to work on a particular bug fix or feature
suggestion doesn't mean someone won't work on
another suggestion.

> More low quality feature requests would make it harder
> to find these requests in the bug tracker, thus raising
> the barrier for new developers.

I don't buy that.  But if it's true then that
in itself calls for another new feature: better
bug-tracker search/organization, ways to lower
the barrier for new developers.

> So I see both arguments as valid here, and I'm conflicted between
> them.

They aren't contradictory needs - at least not
in the sense of being mutually exclusive.  Their
contradiction is dialectical.

Inviting users to suggest things does not impede
bug fixing or other Emacs development.  That's a
false binary choice.

That's essentially saying, "We don't want to hear
more suggestions, especially from newbies or
half-baked suggestions, because we already have
a lot of more important work to do."

> Since it's a social issue more than a technical one, I'm not
> sure there is one correct answer.
> 
> Perhaps the question is simply if this is subjectively desirable from
> the point of view of the leading Emacs developers?  After all, they
> are the ones who will do the majority of the work handling these
> suggestions.

Not necessarily.  See above.  Someone feels an
itch - maybe suggested by someone else, and
works on it - a little bit or a lot.  Someone
else picks up on that work and fixes/improves
it.

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:
>
> Stefan Kangas <stefan@marxist.se> writes:
>
> > Please see the attached patch.  I've incorporated your suggestion and
> > added a link to the manual.
>
> Thanks; looks good to me (after Eli's comments).

Thanks, I've now pushed this as commit 3026af7744.

Best regards,
Stefan Kangas

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 1629 bytes --]

Drew Adams <drew.adams@oracle.com> writes:

> > > So I'd "waste" a few extra chars to spell out that
> > > invitation explicitly.  Something like this:
> > >
> > >  "How to report bugs and suggest or contribute possible improvements"
> >
> > I find that line a bit too packed with information to be easily
> > parsed.  I think that the concern Lars has pointed out is valid here:
> > the about screen is already very dense.
>
> Then get rid of some other parts of the link text or
> other parts of the too-dense screen.  Don't get rid
> of the part about suggesting improvements.
>
> This bug report is especially about explicitly
> inviting enhancement suggestions/wishes.  That needs
> to be on top, up-front, in link text - not relegated
> to some text at the link target.
[...]
> > I came up with the attached tentative patch that adds a paragraph to
> > "Contributing" manual page, attached here for discussion.
> >
> > But thinking about this a bit more, I can't decide if it's a good idea
> > to encourage this or not.  There is a risk that we get too many low
> > quality suggestions that we will waste a lot of time handling.
>
> I couldn't disagree more with such fear/hesitation.

I largely agree with what you're saying; thanks for spelling it out.

I see two options to move forward here:

1. Add a new item (or reformulate an old one) on the splash screen.
2. Add something to the "Contributing" page about feature suggestions.

I'm not too enthusiastic about option 1, but I've re-attached my patch
which tries to do 2.  (They are not mutually exclusive.)

Any other opinions, please?

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Document-feature-requests-in-the-Emacs-manual.patch --]
[-- Type: text/x-patch, Size: 1328 bytes --]

From 1a445133c47c2fa596fa5bdebe150991fde9ee6f Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 14 Sep 2019 13:27:10 +0200
Subject: [PATCH] Document feature requests in the Emacs manual

* doc/emacs/trouble.texi (Contributing): Document feature
requests.  (Bug20697)
---
 doc/emacs/trouble.texi | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 13d3e8475c..f0f9af20b8 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1299,6 +1299,19 @@ Contributing
 @end ifhtml
 You can ask for suggested projects or suggest your own ideas.
 
+If you have a feature request or a suggestion for how to improve
+Emacs, the best place to send it is to
+@ifnothtml
+@email{bug-gnu-emacs.org}
+@end ifnothtml
+@ifhtml
+@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}
+@end ifhtml
+.  Please explain in clear language exactly what change you would like
+to see, and why and how you think it would improve Emacs.  If your
+suggestion is accepted, this will increase its chances of attracting
+interest from one of many volunteer Emacs developers.
+
 If you have already written an improvement, please tell us about it.  If
 you have not yet started work, it is useful to contact
 @ifnothtml
-- 
2.20.1

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 236 bytes --]

Stefan Kangas <stefan@marxist.se> writes:

> I'm not too enthusiastic about option 1, but I've re-attached my patch
> which tries to do 2.  (They are not mutually exclusive.)

Sent it too fast.  I've fixed a typo in the attached patch.

[-- Attachment #2: 0001-Document-feature-requests-in-the-Emacs-manual.patch --]
[-- Type: text/x-patch, Size: 1333 bytes --]

From 2c2ed0e929caf50d02c890293a94da5863cf838b Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 14 Sep 2019 13:27:10 +0200
Subject: [PATCH] Document feature requests in the Emacs manual

* doc/emacs/trouble.texi (Contributing): Document feature
requests.  (Bug20697)
---
 doc/emacs/trouble.texi | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 13d3e8475c..3805cf14ae 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1299,6 +1299,19 @@ Contributing
 @end ifhtml
 You can ask for suggested projects or suggest your own ideas.
 
+If you have a feature request or a suggestion for how to improve
+Emacs, the best place to send it is to
+@ifnothtml
+@email{bug-gnu-emacs@@gnu.org}
+@end ifnothtml
+@ifhtml
+@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}
+@end ifhtml
+.  Please explain in clear language exactly what change you would like
+to see, and why and how you think it would improve Emacs.  If your
+suggestion is accepted, this will increase its chances of attracting
+interest from one of many volunteer Emacs developers.
+
 If you have already written an improvement, please tell us about it.  If
 you have not yet started work, it is useful to contact
 @ifnothtml
-- 
2.20.1

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Drew Adams]

> I largely agree with what you're saying; thanks for spelling it out.
> 
> I see two options to move forward here:
> 
> 1. Add a new item (or reformulate an old one) on the splash screen.
> 2. Add something to the "Contributing" page about feature suggestions.
> 
> I'm not too enthusiastic about option 1, but I've re-attached my patch
> which tries to do 2.  (They are not mutually exclusive.)
> 
> Any other opinions, please?

Thanks for reconsidering, and for working on this.

Wrt #1 & #2: Neither is perfect:

#1: People breeze past the splash screen.
    (But see below.)
#2: A user needs to have somehow found node
    (emacs) `Contributing'.  Not obvious for a
    newbie (but see below).

Wrt your patch (#2): +1 in favor of it.

You might want to say "attracting interest from 
volunteer Emacs developers", instead of "from
one of many" (why one?).

Or maybe - why mention two separate hurdles:
getting your suggestion "accepted" and getting
someone to work on it?  Consider just removing
that whole sentence, keeping only the first one,
which invites suggestions that are clear and
that provide a "why".

Wrt #1: People might not notice a mention on
the splash screen, and even if they do they
might not have a clue how to show it again,
apart from restarting Emacs.

But they might well look into the `Help' menu.

The `Help' menu is the most likely place a new
user will look for info about how to contribute
or contact Emacs developers.  Even if they know
nothing about Info or how to get to the splash
screen, they will find the `Help' menu.

On the `Help' menu we have `How to Report a
Bug' and `Send Bug Report...'.  That's 2 menu
items to help users report bugs.

The `Help' menu also has an `About Emacs' item
that, lo and behold, displays the splash screen,
with its link to node `Contributing'. So for
both contributing and reporting bugs the `Help'
menu is pretty good.

Consider one or both of these possibilities,
in addition to adding your suggested text to
node `Contributing':

* Change `Help' > `Send Bug Report' to `Help'
  > `Report Bug or Suggestion'
* Add a `Report Bug or Suggestion' link to
  the splash screen

The menu item `Send Bug Report' invokes
`send-emacs-bug-report'.  But that's the
same command you use to send an enhancement
request.  It would help if the menu item
expressed that.  (It would even help if the
command name did so.)

---

BTW, I don't know why the _first_ of the
list of links on the splash page is `Authors'.
I'd suggest moving it later or (better, I
think) just removing it.  It would be good to
have `Contributing' as the first link of the
list.

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 782 bytes --]

Stefan Kangas <stefan@marxist.se> writes:

> I see two options to move forward here:
>
> 1. Add a new item (or reformulate an old one) on the splash screen.
> 2. Add something to the "Contributing" page about feature suggestions.
>
> I'm not too enthusiastic about option 1, but I've re-attached my patch
> which tries to do 2.  (They are not mutually exclusive.)
>
> Any other opinions, please?

No one besides me and Drew has commented so far, and we both seem to
be in favour of the above patch.  Drew had some suggestions for
improvements which I've incorporated into the below patch.  I also
took the time to just make it much shorter and simpler (down to two
sentences now).

Are there any objections to pushing this patch to the release branch?

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-feature-requests-in-the-Emacs-manual.patch --]
[-- Type: text/x-diff, Size: 1206 bytes --]

From 0fdbf284a97f31147c8d081536d6b57784d93a5b Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Sat, 14 Sep 2019 13:27:10 +0200
Subject: [PATCH] Document feature requests in the Emacs manual

* doc/emacs/trouble.texi (Contributing): Document how to send feature
requests.  (Bug20697)
---
 doc/emacs/trouble.texi | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 9cbcf20610..33f67f2b44 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1299,6 +1299,17 @@ Contributing
 @end ifhtml
 You can ask for suggested projects or suggest your own ideas.
 
+If you have a feature request or a suggestion for how to improve
+Emacs, the best place to send it is to
+@ifnothtml
+@email{bug-gnu-emacs@@gnu.org}
+@end ifnothtml
+@ifhtml
+@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, bug-gnu-emacs}
+@end ifhtml
+.  Please explain as clearly as possible what change you would like to
+see, and why and how you think it would improve Emacs.
+
 If you have already written an improvement, please tell us about it.  If
 you have not yet started work, it is useful to contact
 @ifnothtml
-- 
2.20.1

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 16 Jan 2020 03:06:30 +0100
> Cc: Lars Ingebrigtsen <larsi@gnus.org>, 20697@debbugs.gnu.org
> 
> > I see two options to move forward here:
> >
> > 1. Add a new item (or reformulate an old one) on the splash screen.
> > 2. Add something to the "Contributing" page about feature suggestions.
> >
> > I'm not too enthusiastic about option 1, but I've re-attached my patch
> > which tries to do 2.  (They are not mutually exclusive.)
> >
> > Any other opinions, please?
> 
> No one besides me and Drew has commented so far, and we both seem to
> be in favour of the above patch.  Drew had some suggestions for
> improvements which I've incorporated into the below patch.  I also
> took the time to just make it much shorter and simpler (down to two
> sentences now).
> 
> Are there any objections to pushing this patch to the release branch?

I'm confused: what is "the above patch", and how is it different from
the change in trouble.texi you posted now?

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

>> Are there any objections to pushing this patch to the release branch?
>
> I'm confused: what is "the above patch", and how is it different from
> the change in trouble.texi you posted now?

Sorry, I was being unclear.  The patch in question is the one attached
to the message you were replying too, with the change to trouble.texi.

Best regards,
Stefan Kangas

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: larsi@gnus.org,  drew.adams@oracle.com,  20697@debbugs.gnu.org
> Date: Thu, 16 Jan 2020 15:55:16 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Are there any objections to pushing this patch to the release branch?
> >
> > I'm confused: what is "the above patch", and how is it different from
> > the change in trouble.texi you posted now?
> 
> Sorry, I was being unclear.  The patch in question is the one attached
> to the message you were replying too, with the change to trouble.texi.

Then the patch is fine with me, thanks.

bug#20697: 25.0.50; Mention `M-x report-emacs-bug' on splash screen

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Then the patch is fine with me, thanks.

Thanks.  Pushed to emacs-27 as 778923afe5.

Best regards,
Stefan Kangas