bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Ulrich Mueller]

In master, the CONTRIBUTE file was recently moved (back) from etc/ to
the top-level dir. This breaks the corresponding button in the about
page. To reproduce, type "M-x about-emacs RET" and then press the
"Contributing" button:

   view-file: /usr/share/emacs/25.0.50/etc/CONTRIBUTE does not exist

From its new location, the file won't even be installed any more.

(Note: The file had been moved from top-level to etc in 2007.)

bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Glenn Morris]

Ulrich Mueller wrote:

> In master, the CONTRIBUTE file was recently moved (back) from etc/ to
> the top-level dir. This breaks the corresponding button in the about
> page. To reproduce, type "M-x about-emacs RET" and then press the
> "Contributing" button:
>
>    view-file: /usr/share/emacs/25.0.50/etc/CONTRIBUTE does not exist
>
>>From its new location, the file won't even be installed any more.
>
> (Note: The file had been moved from top-level to etc in 2007.)

Yes, this file was moved into etc from top-level specifically so it 
would be part of the installed Emacs. Personally I don't think that 
moving it out again makes much sense, but if people really want to do 
that, it needs more work. It needs to be in the installed Emacs, so a
special install rule will need to be written. The doc references that
refer to it being in the etc/ directory (grep will find these) will need
to be rewritten to account for it being in different places in installed
and uninstalled Emacs. Personally I think it would be a lot simpler to
move it back where it was and put a stub CONTRIBUTE at top-level that
just says "see etc/CONTRIBUTE". (But again, personally I don't think
this makes much sense.)

Please also note that ChangeLog entries are written in the present
tense ("deleted", "merged", "renamed", etc), start with capitals, and
end with full-stops.

bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Glenn Morris]

PS perhaps there is some confusion as to the purpose of this file.

The intended audience for etc/CONTRIBUTE is people who are not Emacs
developers and do not have write access to the repo. So it
specifically does not talk about how to commit things to Savannah, etc.
(People may have added bits of such information to the file in error.)
Many people just want to send a patch, not get write access.
That was why CONTRIBUTE needs to be in the installed Emacs.

"What people who commit to Emacs need to know" is a much more lengthy
document, and IMO should be a separate one. (IIRC, Xue Fuqiao wrote a
version of it the last time this came up; see emacs-devel archives.
I have to say that I didn't like that version much.)

Such a document is obviously long overdue.

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Stephen Leake]

This is being discussed on emacs-devel, so I'm copying this there.

Glenn Morris <rgm@gnu.org> writes:

> Ulrich Mueller wrote:
>
>> In master, the CONTRIBUTE file was recently moved (back) from etc/ to
>> the top-level dir. This breaks the corresponding button in the about
>> page. To reproduce, type "M-x about-emacs RET" and then press the
>> "Contributing" button:
>>
>>    view-file: /usr/share/emacs/25.0.50/etc/CONTRIBUTE does not exist
>>
>>>From its new location, the file won't even be installed any more.
>>
>> (Note: The file had been moved from top-level to etc in 2007.)
>
> Yes, this file was moved into etc from top-level specifically so it 
> would be part of the installed Emacs. Personally I don't think that 
> moving it out again makes much sense, but if people really want to do 
> that, it needs more work. It needs to be in the installed Emacs, so a
> special install rule will need to be written. The doc references that
> refer to it being in the etc/ directory (grep will find these) will need
> to be rewritten to account for it being in different places in installed
> and uninstalled Emacs. Personally I think it would be a lot simpler to
> move it back where it was and put a stub CONTRIBUTE at top-level that
> just says "see etc/CONTRIBUTE". (But again, personally I don't think
> this makes much sense.)

I did not realize there was a link to etc/CONTRIBUTE in About.

-- 
-- Stephe

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Stephen Leake]

This is being discussed on emacs-devel, so I'm copying it there.

Glenn Morris <rgm@gnu.org> writes:

> PS perhaps there is some confusion as to the purpose of this file.
>
> The intended audience for etc/CONTRIBUTE is people who are not Emacs
> developers and do not have write access to the repo. So it
> specifically does not talk about how to commit things to Savannah, etc.
> (People may have added bits of such information to the file in error.)
> Many people just want to send a patch, not get write access.
> That was why CONTRIBUTE needs to be in the installed Emacs.

There is now developer stuff in CONTRIBUTE.

I suggest we move the "for non-developers" info into the Emacs manual
Contributing section, and keep CONTRIBUTE for developers.

Hmm; I'm assuming the Emacs manual is always installed with Emacs; is
that true?

> "What people who commit to Emacs need to know" is a much more lengthy
> document, and IMO should be a separate one. (IIRC, Xue Fuqiao wrote a
> version of it the last time this came up; see emacs-devel archives.
> I have to say that I didn't like that version much.)
>
> Such a document is obviously long overdue.

Yes, and the consensus here seemed to be it should be in CONTRIBUTE.
Apparently we forgot the rationale for CONTRIBUTE.

Which is a _very_ good argument for using texinfo for CONTRIBUTE; you can
put rationale in comments.

-- 
-- Stephe

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Alexis]

Stephen Leake writes:

> Hmm; I'm assuming the Emacs manual is always installed with Emacs; is
> that true?

Not on Debian, due to GFDL / DFSG conflicts.


Alexis.

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Glenn Morris]

Alexis wrote:

>> Hmm; I'm assuming the Emacs manual is always installed with Emacs; is
>> that true?
>
> Not on Debian, due to GFDL / DFSG conflicts.

That shouldn't be a factor in our decision.

I'd welcome CONTRIBUTE being Texinfo-erized (probably emacs-xtra rather
than emacs).

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Stephen Leake]

Glenn Morris <rgm@gnu.org> writes:

> Alexis wrote:
>
>>> Hmm; I'm assuming the Emacs manual is always installed with Emacs; is
>>> that true?
>>
>> Not on Debian, due to GFDL / DFSG conflicts.
>
> That shouldn't be a factor in our decision.
>
> I'd welcome CONTRIBUTE being Texinfo-erized (probably emacs-xtra rather
> than emacs).

There is already (info "(emacs)Contributing"); that's in
doc/emacs/trouble.texi . It's mostly a pointer to etc/CONTRIBUTE.

-- 
-- Stephe

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Mon, 08 Dec 2014 23:43:15 -0500
> Cc: emacs-devel@gnu.org
> 
> Alexis wrote:
> 
> >> Hmm; I'm assuming the Emacs manual is always installed with Emacs; is
> >> that true?
> >
> > Not on Debian, due to GFDL / DFSG conflicts.
> 
> That shouldn't be a factor in our decision.

You mean, we shouldn't be concerned that this information will not be
available to users of a popular platform?

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Glenn Morris]

Eli Zaretskii wrote:

> You mean, we shouldn't be concerned that this information will not be
> available to users of a popular platform?

No, that's neither what I mean nor what the situation would be.
I meant that we should not let how Debian choose to split their packages
(and repositories) influence where we put Emacs information.
(This seems obvious to me.)

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: flexibeast@gmail.com,  emacs-devel@gnu.org
> Date: Tue, 09 Dec 2014 12:55:59 -0500
> 
> Eli Zaretskii wrote:
> 
> > You mean, we shouldn't be concerned that this information will not be
> > available to users of a popular platform?
> 
> No, that's neither what I mean nor what the situation would be.
> I meant that we should not let how Debian choose to split their packages
> (and repositories) influence where we put Emacs information.

Now I'm confused.  If we put this in the manual, then Debian users
will not see it.  If we don't want that to happen, we should keep this
on a separate file, not in the manual.  Suppose we decide the latter:
does this mean our decision was influenced by how Debian split their
packages?

What am I missing?

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Glenn Morris <rgm@gnu.org>
>> Cc: flexibeast@gmail.com,  emacs-devel@gnu.org
>> Date: Tue, 09 Dec 2014 12:55:59 -0500
>> 
>> Eli Zaretskii wrote:
>> 
>> > You mean, we shouldn't be concerned that this information will not be
>> > available to users of a popular platform?
>> 
>> No, that's neither what I mean nor what the situation would be.
>> I meant that we should not let how Debian choose to split their packages
>> (and repositories) influence where we put Emacs information.
>
> Now I'm confused.  If we put this in the manual, then Debian users
> will not see it.  

Unless they take the extra steps of adding 'non-free' to their
distribution list, and installing the Emacs documentation.

I think this is an important issue. Remember, the point of this file is
to encourage Emacs users to contribute bug reports/patches/etc to Emacs;
we want it to be easily available to everyone.

-- 
-- Stephe

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > You mean, we shouldn't be concerned that this information will not be
  > available to users of a popular platform?

I don't know exactly what practical question is at issue here,
but in general we don't want to make concessions to Debian's policy.
Debian should change that policy.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Stephen Leake]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > You mean, we shouldn't be concerned that this information will not be
>   > available to users of a popular platform?
>
> I don't know exactly what practical question is at issue here,

The issue is the "contributing" link from the Emacs Help | About Emacs
buffer.

In 24.4, that link brings up the file etc/CONTRIBUTE, which is installed
by the Emacs binary install.

We've moved .../etc/CONTRIBUTE to .../CONTRIBUTE, on the theory that
this would make it more visible, forgetting about the About page.

We've also put developer information in there, forgetting about the
original intent of the file (which was to encourage users to contribute
bug reports and patches to Emacs).

In order to resolve these issues, I proposed moving the non-developer
information into the Emacs manual (info "(emacs)Contributing"), and
changing the link on the About page to point to that.

I then asked whether we could rely on the Emacs manual being installed,
and someone pointed out that on Debian (and possibly derived
distributions), it takes extra user steps to install the Emacs manual,
due to the free/non-free policy issue. 


However, I now see that one of the other links in About already points
to the manual: Ordering Manuals

So we could just follow that precedent.


-- 
-- Stephe

Re: bug#19299: 25.0.50; "Contributing" button in *About GNU Emacs* no longer works

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > We've moved .../etc/CONTRIBUTE to .../CONTRIBUTE, on the theory that
  > this would make it more visible, forgetting about the About page.

We could put the file in both places, using a symlink or having 'make dist'
copy the master into the secondary copy.

-- 
Dr Richard Stallman
President, Free Software Foundation
51 Franklin St
Boston MA 02110
USA
www.fsf.org  www.gnu.org
Skype: No way! That's nonfree (freedom-denying) software.
  Use Ekiga or an ordinary phone call.

bug#19299: 19299 fixed

[Stephen Leake]

2014-12-19  Stephen Leake  <stephen_leake@stephe-leake.org>

	Move user-level information from CONTRIBUTE to doc/emacs/trouble.texi

	Fixes bug#19299

	* CONTRIBUTE: Move user-level information to doc/emacs/trouble.texi
	  (commit messages): new, gathered from comments on emacs-devel
	  (Changelog notes): add reference to GNU coding standards section 5.2;
	  doc 'present tense', bug fix format
	  (branches): freeze announcements are made on info-gnu-emacs mailing
	  list
	  (git vs rename): new

	* doc/emacs/trouble.texi: Move user-level information from CONTRIBUTE here

	* lisp/startup.el (fancy-about-text): change buttons for etc/CONTRIBUTE
	  to (info "(emacs)Contributing")

-- 
-- Stephe