When will emacs 27.1 be officially released?

When will emacs 27.1 be officially released?

[Liwei Ma]

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

We wait for a new version too long this year:)

Liwei

[-- Attachment #2: Type: text/html, Size: 102 bytes --]

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

On June 30, 2020 5:52:21 AM GMT+03:00, Liwei Ma <liwei.ma@gmail.com> wrote:
> We wait for a new version too long this year:)


Indeed, I think the development team should be fired, starting from the head maintainer, who is clearly incompetent.  They cannot even make a simple release on time.

Re: When will emacs 27.1 be officially released?

[tomas]

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

On Tue, Jun 30, 2020 at 06:55:26AM +0300, Eli Zaretskii wrote:
> On June 30, 2020 5:52:21 AM GMT+03:00, Liwei Ma <liwei.ma@gmail.com> wrote:
> > We wait for a new version too long this year:)
> 
> 
> Indeed, I think the development team should be fired,

I object. As a non-shareholder I can :-)

> starting from the head maintainer, who is clearly incompetent.  They cannot even make a simple release on time.

Veto :)

Cheers
-- t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: When will emacs 27.1 be officially released?

[Kévin Le Gouguec]

Eli Zaretskii <eliz@gnu.org> writes:

> Indeed, I think the development team should be fired, starting from
> the head maintainer, who is clearly incompetent.  They cannot even
> make a simple release on time.

This.  I mean, Emacs's roadmap is pretty well-defined; the user stories
are scheduled very precisely, and the develop^Wvalidation team does a
stellar job at finding regressions before features are integrated into
the mainline.  Now if only maintainers would do their job instead of
drowsing off…


More seriously though.

- Does bug#39200 come anywhere close to an exhaustive list of issues to
  address before the 27 branch is considered stable?

  (Also can debbugs.el display the "blocked-by" list in a human-readable
  format?)

- I dimly remember a discussion on bug-gnu-emacs between Eli and Dmitry
  a couple of months back, about how thorough the team should be about
  fixing regressions before releasing x.1.  My 2¢:

As a user, I think I'd find it acceptable to have a slightly less stable
x.1 if I had the promise of more frequent x.(n+1) releases (bugfixes).

See e.g. how many people use MELPA (live untagged commits from master)
vs. MELPA stable (only tagged versions): it seems to me that there are
some people out there who are comfortable living on the /bleeding/ edge,
with all the occasional discomfort that entails.

If we assume x.1 releases will have more exposure than x.0.z (pre-tests,
RCs) by virtue of being packaged by distros, it could help bring issues
to our attention faster, which means regressions could be easier to fix
because we wouldn't have doubled down on problematic design choices
(this is a very abstract observation, I don't have a concrete example of
a recent "problematic design choice" hindering a bugfix).

And it's not like distros packaging "broken" x.1 releases will break
every user's workflow.  Take gcc on Ubuntu for example: the default
"gcc" package on 20.04 is 9.3, but adventurous users can already try out
version 10 by installing "gcc-10", thereby opting in explicitly and
deliberately for new features, and potential breakage.


I hope this doesn't come across as armchair commentary; apologies if it
does.

And many thanks to "the development team" :)

Re: When will emacs 27.1 be officially released?

[Basil L. Contovounesios]

Eli Zaretskii <eliz@gnu.org> writes:

> On June 30, 2020 5:52:21 AM GMT+03:00, Liwei Ma <liwei.ma@gmail.com> wrote:
>> We wait for a new version too long this year:)
>
> Indeed, I think the development team should be fired, starting from the head
> maintainer, who is clearly incompetent.  They cannot even make a simple release
> on time.

Does Emacs have its own trade union yet?

-- 
Basil

Re: When will emacs 27.1 be officially released?

[Stefan Monnier]

>>> We wait for a new version too long this year:)
>> Indeed, I think the development team should be fired, starting from the head
>> maintainer, who is clearly incompetent.  They cannot even make a simple release
>> on time.
> Does Emacs have its own trade union yet?

Of course, but the maintainer is an administrator position.


        Stefan

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: emacs-devel@gnu.org, Liwei Ma <liwei.ma@gmail.com>
> Date: Tue, 30 Jun 2020 14:01:19 +0100
> 
> Does Emacs have its own trade union yet?

No.  Suggestions how to start that might be welcome.

Re: When will emacs 27.1 be officially released?

[Rostislav Svoboda]

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

> We wait for a new version too long this year:)

I have a good experience with compiling and using emacs-NextRelNr branches.
Since at least emacs-25 (~4 years). I made myself a fish-shell script
https://github.com/Bost/dotfiles/blob/master/fish/functions/make-emacs.fish
to compile the code and git-tag it, if there's a change in the code files
since my last compilation. (The script doesn't proceed with compilation if
only documentation changed.) I tag the repo just in case something's
broken, so I can just checkout the previous tag and rerun my script. (The
script is not 100% maintenance-free, but I don't bother editing it now and
then.)

I use spacemacs (daily), mostly for clojure development. And I update
spacemacs, plus installed packages almost daily. Everything works fine and
I don't encounter any problems more than once a year, including problems
with packages.

The only problem I have is with freezes when editing larger files (> ~1MB)
especially with long lines. But that's a general and long standing issue.
In such a case I just `killall emacs` and try to run `emacs
--no-init-file`. It helps in about 50% of the situations.

[-- Attachment #2: Type: text/html, Size: 1374 bytes --]

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
> Cc: emacs-devel@gnu.org, Liwei Ma <liwei.ma@gmail.com>
> Date: Tue, 30 Jun 2020 11:51:59 +0200
> 
> More seriously though.
> 
> - Does bug#39200 come anywhere close to an exhaustive list of issues to
>   address before the 27 branch is considered stable?

I tend to treat these "blocking" bug reports as advisory only.  E.g.,
the bugs you see there now (a) don't sound too serious to me, and
(b) don't seem to cause anyone to go out of their way fixing them.

So if you think this is what prevents us from releasing Emacs 27.1,
it's not.

>   (Also can debbugs.el display the "blocked-by" list in a human-readable
>   format?)

What's wrong with the current display?

> As a user, I think I'd find it acceptable to have a slightly less stable
> x.1 if I had the promise of more frequent x.(n+1) releases (bugfixes).

The main problem is how to translate "slightly less stable" and "more
frequent" into actionable procedures that we can support given the
resources.  We all agree with these principles (well, at least I do),
but Life™ is more complex than we'd like it to be.  See below.

> See e.g. how many people use MELPA (live untagged commits from master)
> vs. MELPA stable (only tagged versions): it seems to me that there are
> some people out there who are comfortable living on the /bleeding/ edge,
> with all the occasional discomfort that entails.

MELPA is a collection of Lisp packages.  Lisp packages seldom cause
catastrophic problems in a running session, like crashes, loss of
edits, etc.  Our job is more complex and the dangers from releasing a
less-than-stable Emacs are higher.  That's one reason why we cannot
follow that example.

Another reason is that each MELPA package is quite small and simple,
certainly in comparison with Emacs.  So the time and effort needed for
the maintainer to put out a new version are much smaller than what we
need.  Even the most mundane aspect of an Emacs release, such as
update of the documentation and NEWS, takes orders of magnitude more
time for us than it takes for an elpa package.  Would you agree to
release Emacs with incorrect/inaccurate/outdated manuals?

> If we assume x.1 releases will have more exposure than x.0.z (pre-tests,
> RCs) by virtue of being packaged by distros, it could help bring issues
> to our attention faster, which means regressions could be easier to fix
> because we wouldn't have doubled down on problematic design choices
> (this is a very abstract observation, I don't have a concrete example of
> a recent "problematic design choice" hindering a bugfix).

See, that's another factor that people tend to forget or ignore: it
takes a long time for Emacs problems to be discovered and reported.  A
new Emacs release can take years to reach end users.  We are routinely
receiving bug reports about changes made two or more releases ago.  If
you are looking for a single most important reason why it takes so
long to put out another pretest, it is this one: experience shows that
it takes weeks if not months for enough people to try a pretest and
report the problems they see.  Once a problem is reported, it is
usually fixed very quickly, but how do you know the important problems
were all discovered, except by waiting?

> And it's not like distros packaging "broken" x.1 releases will break
> every user's workflow.

That's true, but Emacs has a reputation of being very stable, even for
the development snapshots.  Breaking the workflow of even a single
user causes that user grief and is not welcome.  Especially since an
emergency bugfix release is also not something we can do quickly
enough, as one or two occurrences in the past have shown.

> Take gcc on Ubuntu for example: the default "gcc" package on 20.04
> is 9.3, but adventurous users can already try out version 10 by
> installing "gcc-10", thereby opting in explicitly and deliberately
> for new features, and potential breakage.

I don't think you can compare breakage of a compiler with breakage of
Emacs.  A broken compiler can fail to build a program, which is not a
catastrophe; losing several hours of editing can well be a
catastrophe.

So once again, the practical issue here is what to do differently to
make the releases more frequent, without losing too much of stability
and other good qualities.  I mean practical measures, not general
considerations with which everyone will agree.  E.g., let's start with
a small step: how do we make the effort of preparing the manuals and
NEWS for a release less time-consuming?

Re: When will emacs 27.1 be officially released?

[Paul Eggert]

On 6/30/20 9:58 AM, Eli Zaretskii wrote:
> A broken compiler can fail to build a program, which is not a
> catastrophe

It can also quietly build the wrong program, which can be catastrophic.

> how do we make the effort of preparing the manuals and
> NEWS for a release less time-consuming?

A method that works reasonably well in other projects is to update manuals and
NEWS as we go, not just before a release. For starters, I suggest removing the
"+++/---" notation in NEWS, which encourages the bad practice of documentation
not matching code.

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> Cc: liwei.ma@gmail.com, emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 30 Jun 2020 11:52:25 -0700
> 
> On 6/30/20 9:58 AM, Eli Zaretskii wrote:
> > A broken compiler can fail to build a program, which is not a
> > catastrophe
> 
> It can also quietly build the wrong program, which can be catastrophic.

I hope that people who build such programs don't play with that
particular kind of fire.

> > how do we make the effort of preparing the manuals and
> > NEWS for a release less time-consuming?
> 
> A method that works reasonably well in other projects is to update manuals and
> NEWS as we go, not just before a release.

I started requesting that some time ago, with limited success.

> For starters, I suggest removing the "+++/---" notation in NEWS,
> which encourages the bad practice of documentation not matching
> code.

Not before we don't need to worry anymore about changes pushed without
documentation.  We aren't there yet.

Re: When will emacs 27.1 be officially released?

[Kévin Le Gouguec]

Thank you for this thoughtful answer.

Eli Zaretskii <eliz@gnu.org> writes:

>> - Does bug#39200 come anywhere close to an exhaustive list of issues to
>>   address before the 27 branch is considered stable?
>
> I tend to treat these "blocking" bug reports as advisory only.  E.g.,
> the bugs you see there now (a) don't sound too serious to me, and
> (b) don't seem to cause anyone to go out of their way fixing them.
>
> So if you think this is what prevents us from releasing Emacs 27.1,
> it's not.

OK.  I'm sure each maintainer has their own ways of prioritizing bugs
and keeping track of those he considers serious; from the POV of curious
users who watch the development process, knowing what's holding the
release is not obvious.

Point (b) taken, though.

>>   (Also can debbugs.el display the "blocked-by" list in a human-readable
>>   format?)
>
> What's wrong with the current display?

Nothing, actually, I hadn't taken the time to check what bindings were
available; now I see that "b" (debbugs-gnu-show-blocked-by-reports) does
exactly what I was looking for (bar hiding resolved issues, but I'm sure
there's a knob somewhere for that).

>        Even the most mundane aspect of an Emacs release, such as
> update of the documentation and NEWS, takes orders of magnitude more
> time for us than it takes for an elpa package.  Would you agree to
> release Emacs with incorrect/inaccurate/outdated manuals?

Mmm, I guess in the specific case of documentation, a very naive answer
would be "let's gate pushes to master until commits/branches include the
documentation for the changes they bring".  That would make the master
branch "always release-ready", as far as documentation is concerned.

No idea how to enforce that of course (more on that below).

> See, that's another factor that people tend to forget or ignore: it
> takes a long time for Emacs problems to be discovered and reported.  A
> new Emacs release can take years to reach end users.  We are routinely
> receiving bug reports about changes made two or more releases ago.  If
> you are looking for a single most important reason why it takes so
> long to put out another pretest, it is this one: experience shows that
> it takes weeks if not months for enough people to try a pretest and
> report the problems they see.  Once a problem is reported, it is
> usually fixed very quickly, but how do you know the important problems
> were all discovered, except by waiting?

It sounds like a vicious cycle; the more we wait for feedback on
pretests, the more disruptive things happen on master, and the more
unstability the next release cycle will face…

I admit I don't see an easy way out of this situation.  I suspect some
users (the kind who use Debian Sid, Ubuntu PPAs, or any rolling release
distro) would flock to "nightly" tarballs and would not get overly
fussed about incomplete documentation, but that's just a guess.

>                                                  Especially since an
> emergency bugfix release is also not something we can do quickly
> enough, as one or two occurrences in the past have shown.

I dimly remember that 25.3 sparked some debate regarding the difficulty
of putting out "targeted bugfix" releases as quickly as we'd like.  I
don't remember the conclusions; is there anything specific to Emacs that
prevents us from getting better?

> So once again, the practical issue here is what to do differently to
> make the releases more frequent, without losing too much of stability
> and other good qualities.  I mean practical measures, not general
> considerations with which everyone will agree.

"One bug ⇒ one test" is a pretty concrete measure.  Although there are a
lot of areas in Emacs where writing automated tests is as daunting as
fixing the bug, if not more…

>                                                 E.g., let's start with
> a small step: how do we make the effort of preparing the manuals and
> NEWS for a release less time-consuming?

Off the top of my head, I don't have a better answer than "restrict
pushes to master to fully documented commits/branches".  I don't expect
this to make editing manuals and NEWS less time-consuming, but it
*should* help ensure that "things landing on master" does not lead to
"slow buildup of undocumented stuff/obsolete documentation to catch up
with on the release branch".

Of course,

(1) I have no idea how this could possibly be enforced.

(2) Assuming it could be enforced, I'm not sure how well-received the
    idea would be: "drive-by" contributors comply when they are told
    that their changes need manual/NEWS updates, but AFAICT the master
    branch is also used for developers with push access to iterate and
    get some feedback on features they are working on; I'm not sure they
    would get as much visibility if they kept to feature branches…

Re: When will emacs 27.1 be officially released?

[Paul Eggert]

On 6/30/20 12:06 PM, Eli Zaretskii wrote:
>> A method that works reasonably well in other projects is to update manuals and
>> NEWS as we go, not just before a release.
> I started requesting that some time ago, with limited success.

Is there some way we could step that up? E.g., perhaps start by reminding people
who commit code changes but not changes to the corresponding documentation that
they need to do the documenation ASAP. Eventually, we could defer or even revert
changes until they're documented. The idea would be to change the culture of
coding-without-documenting.

Re: When will emacs 27.1 be officially released?

[Dmitry Gutov]

On 01.07.2020 01:17, Paul Eggert wrote:
> Is there some way we could step that up? E.g., perhaps start by reminding people
> who commit code changes but not changes to the corresponding documentation that
> they need to do the documenation ASAP. Eventually, we could defer or even revert
> changes until they're documented. The idea would be to change the culture of
> coding-without-documenting.

What will those of us do who find the current way the manual is written 
suboptimal? And who generally don't read it anyway.

I've had multiple discussions with Eli on how things should be described 
and structured, after which my contributions ended us essentially fully 
rewritten. I'm not bitter about those occurrences, but it seems to me 
that adding to the manual wouldn't be very productive for me in many 
cases (unless it's a minor fix of an existing entry) if someone is going 
to rewrite all of it.

Likewise, you yourself didn't accept my version of another change that 
we discussed most recently.

Also, if we're considering patches from minor contributors, this can be 
an extra barrier for entry (make sure to get the commit message right, 
and NEWS, *and* the manual), which is higher than the other two.

Re: When will emacs 27.1 be officially released?

[Paul Eggert]

On 6/30/20 3:31 PM, Dmitry Gutov wrote:
> On 01.07.2020 01:17, Paul Eggert wrote:

> What will those of us do who find the current way the manual is written
> suboptimal? And who generally don't read it anyway.

Well, we could drop the manual entirely :-). But until we do, we should maintain it.

> Likewise, you yourself didn't accept my version of another change that we
> discussed most recently.

Sure, but that's not normally the issue here, as that sort of disagreement
happens with code as well as with documentation. In other words, the issue is
rarely about areas where multiple people might work on documentation and
disagree about what should go into it; it's more commonly about areas where
nobody updated the documentation even though it obviously became out of date.

> this can be an extra
> barrier for entry (make sure to get the commit message right, and NEWS, *and*
> the manual)

Yes, that's a price we'd have to pay. I hope it wouldn't be much of a problem in
practice.

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> Cc: liwei.ma@gmail.com, emacs-devel@gnu.org, kevin.legouguec@gmail.com
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Wed, 1 Jul 2020 01:31:13 +0300
> 
> I've had multiple discussions with Eli on how things should be described 
> and structured, after which my contributions ended us essentially fully 
> rewritten. I'm not bitter about those occurrences, but it seems to me 
> that adding to the manual wouldn't be very productive for me in many 
> cases (unless it's a minor fix of an existing entry) if someone is going 
> to rewrite all of it.

Rephrasing existing documentation is much easier than writing it from
scratch, especially for a feature someone else developed.  So please
don't take those rewordings as a sign that your original documentation
effort is wasted, it definitely isn't.

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> Cc: kevin.legouguec@gmail.com, liwei.ma@gmail.com, emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 30 Jun 2020 15:17:58 -0700
> 
> On 6/30/20 12:06 PM, Eli Zaretskii wrote:
> >> A method that works reasonably well in other projects is to update manuals and
> >> NEWS as we go, not just before a release.
> > I started requesting that some time ago, with limited success.
> 
> Is there some way we could step that up? E.g., perhaps start by reminding people
> who commit code changes but not changes to the corresponding documentation that
> they need to do the documenation ASAP. Eventually, we could defer or even revert
> changes until they're documented. The idea would be to change the culture of
> coding-without-documenting.

I think we are going there, but slowly.  I'm not convinced there is a
faster way that won't lose us some contributors.  Some people just
dislike writing documentation, and there's nothing we can do about it.
As someone wise once told me, each person is a package deal: you get
him or her with all their talents and their idiosyncrasies.

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
> Cc: emacs-devel@gnu.org,  liwei.ma@gmail.com
> Date: Wed, 01 Jul 2020 00:09:30 +0200
> 
> > See, that's another factor that people tend to forget or ignore: it
> > takes a long time for Emacs problems to be discovered and reported.  A
> > new Emacs release can take years to reach end users.  We are routinely
> > receiving bug reports about changes made two or more releases ago.  If
> > you are looking for a single most important reason why it takes so
> > long to put out another pretest, it is this one: experience shows that
> > it takes weeks if not months for enough people to try a pretest and
> > report the problems they see.  Once a problem is reported, it is
> > usually fixed very quickly, but how do you know the important problems
> > were all discovered, except by waiting?
> 
> It sounds like a vicious cycle; the more we wait for feedback on
> pretests, the more disruptive things happen on master, and the more
> unstability the next release cycle will face…

Changes on master aren't supposed to be disruptive.  And those that
come close are left on master enough time for users to find and report
their problems.

But yes, deciding when to cut a release branch is a tight judgment
call that needs to strike a delicate balance between the two dangers.

> I admit I don't see an easy way out of this situation.  I suspect some
> users (the kind who use Debian Sid, Ubuntu PPAs, or any rolling release
> distro) would flock to "nightly" tarballs and would not get overly
> fussed about incomplete documentation, but that's just a guess.

A decision to disregard our documentation is not mine to take
(although I personally do have an opinion, of course).  It is
something the community as a whole needs to decide, and then we will
have to convince the Powers that Be of the GNU project; good luck with
that!

> >                                                  Especially since an
> > emergency bugfix release is also not something we can do quickly
> > enough, as one or two occurrences in the past have shown.
> 
> I dimly remember that 25.3 sparked some debate regarding the difficulty
> of putting out "targeted bugfix" releases as quickly as we'd like.  I
> don't remember the conclusions; is there anything specific to Emacs that
> prevents us from getting better?

I think it was 26.3, and the problem is not the decision, the problem
was how much time it took.  Too much, IMO.

> > So once again, the practical issue here is what to do differently to
> > make the releases more frequent, without losing too much of stability
> > and other good qualities.  I mean practical measures, not general
> > considerations with which everyone will agree.
> 
> "One bug ⇒ one test" is a pretty concrete measure.  Although there are a
> lot of areas in Emacs where writing automated tests is as daunting as
> fixing the bug, if not more…

Adding tests is welcome, but it doesn't help in the issue at hand,
because tests for bugs are added after the bugs are already discovered
and reported.

Re: When will emacs 27.1 be officially released?

[Dmitry Gutov]

On 01.07.2020 17:29, Eli Zaretskii wrote:
> Rephrasing existing documentation is much easier than writing it from
> scratch, especially for a feature someone else developed.  So please
> don't take those rewordings as a sign that your original documentation
> effort is wasted, it definitely isn't.

Please don't take it the wrong way, but we've reached a point in these 
discussion multiple times where I disagree with how information is 
presented, but at the same time I understand that I'm not the target 
audience. Nor are the other users with habits similar to mine.

At the same time, I'm really someone who's not familiar with how our 
manuals are organized. So every time I'd need to make a significant 
addition, I have to research that first. And that's like 3x the work.

Re: When will emacs 27.1 be officially released?

[Paul Eggert]

On 7/1/20 10:47 AM, Dmitry Gutov wrote:
> I'm really someone who's not familiar with how our manuals are
> organized. So every time I'd need to make a significant addition, I have to
> research that first. And that's like 3x the work.

I also find that writing documentation often takes way more work than writing
the corresponding code, partly for the reasons you give. But that's part of the
job. If I invent something but don't communicate it well to other people, I
haven't really finished my invention.

I do understand the frustration, though.

Re: When will emacs 27.1 be officially released?

[Dmitry Gutov]

On 01.07.2020 20:52, Paul Eggert wrote:
> I also find that writing documentation often takes way more work than writing
> the corresponding code, partly for the reasons you give. But that's part of the
> job. If I invent something but don't communicate it well to other people, I
> haven't really finished my invention.

True, but if I have something to say, it's more likely to end up in the 
package Commentary.

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Wed, 1 Jul 2020 20:47:21 +0300
> Cc: eggert@cs.ucla.edu, liwei.ma@gmail.com, kevin.legouguec@gmail.com,
>  emacs-devel@gnu.org
> 
> At the same time, I'm really someone who's not familiar with how our 
> manuals are organized. So every time I'd need to make a significant 
> addition, I have to research that first. And that's like 3x the work.

You could always ask instead, if this part takes a lot of effort.
Please feel free.  Finding a proper place for some piece of
information is very easy for me (and I expect for some others).

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> Cc: liwei.ma@gmail.com, emacs-devel@gnu.org, kevin.legouguec@gmail.com
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Wed, 1 Jul 2020 20:55:31 +0300
> 
> if I have something to say, it's more likely to end up in the
> package Commentary.

If you find that what you write in the commentary is better than what
you write for the documentation, my suggestion is to use the text from
the commentary almost verbatim in the docs.

Re: When will emacs 27.1 be officially released?

[Dmitry Gutov]

On 01.07.2020 21:13, Eli Zaretskii wrote:
> If you find that what you write in the commentary is better than what
> you write for the documentation, my suggestion is to use the text from
> the commentary almost verbatim in the docs.

My ideal workflow in that regard would be you (or someone else 
responsible for the manual) asking questions, me answering them by 
updating the Commentary, and you rephrasing the result in the manual in 
any way you prefer.

Re: When will emacs 27.1 be officially released?

[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. ]]]

  >   Some people just
  > dislike writing documentation, and there's nothing we can do about it.
  > As someone wise once told me, each person is a package deal: you get
  > him or her with all their talents and their idiosyncrasies.

There may be some developers who could write documentation for their
code if they don't have to make it good, readable English.  Maybe we
could pair them with others who could take that text and turn it into
manual-quality English.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: When will emacs 27.1 be officially released?

[Kévin Le Gouguec]

Eli Zaretskii <eliz@gnu.org> writes:

>> I admit I don't see an easy way out of this situation.  I suspect some
>> users (the kind who use Debian Sid, Ubuntu PPAs, or any rolling release
>> distro) would flock to "nightly" tarballs and would not get overly
>> fussed about incomplete documentation, but that's just a guess.
>
> A decision to disregard our documentation is not mine to take
> (although I personally do have an opinion, of course).  It is
> something the community as a whole needs to decide, and then we will
> have to convince the Powers that Be of the GNU project; good luck with
> that!

Mmm.  I see that e.g. GCC[1], GDB[2] and Guix[3][4] put out "development
snapshots" fresh off the master branch (≈weekly, daily, and continuously
respectively).  Are they more diligent with documentation than Emacs is?

[1] https://gcc.gnu.org/snapshots.html
[2] https://www.gnu.org/software/gdb/current/
[3] https://guix.gnu.org/download/latest/

[4] (Also, that's neither here nor there, but kudos to Guix for
    automating the whole thing; AFAICT from the download URL, thanks to
    their CI system, it takes zero effort for them to (1) build the
    latest commit (2) test the result (3) archive it (4) make it
    available on their website.)

>> >                                                  Especially since an
>> > emergency bugfix release is also not something we can do quickly
>> > enough, as one or two occurrences in the past have shown.
>> 
>> I dimly remember that 25.3 sparked some debate regarding the difficulty
>> of putting out "targeted bugfix" releases as quickly as we'd like.  I
>> don't remember the conclusions; is there anything specific to Emacs that
>> prevents us from getting better?
>
> I think it was 26.3, and the problem is not the decision, the problem
> was how much time it took.  Too much, IMO.

25.3 was the "⚠🚨 Red alert! Enriched Text is insecure! 🚨⚠" release; I
don't see anything in the 26.3 NEWS that suggests "an emergency bugfix
release", though it's entirely possible that this one also took too much
time.

Here are some (lengthy) threads that the 25.3 release process triggered.
Off the top of my head, I don't remember if there were any conclusions
wrt hastening this process…

https://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00401.html
https://lists.gnu.org/archive/html/emacs-devel/2017-09/msg00211.html

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eggert@cs.ucla.edu, liwei.ma@gmail.com, emacs-devel@gnu.org,
> 	kevin.legouguec@gmail.com
> Date: Wed, 01 Jul 2020 23:49:13 -0400
> 
> There may be some developers who could write documentation for their
> code if they don't have to make it good, readable English.  Maybe we
> could pair them with others who could take that text and turn it into
> manual-quality English.

I actually wrote something like the above several times, urging people
to write documentation even if they don't feel their English is good
enough.  That's not "pairing", but the result should be the same.  It
even happened a few times.

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
> Cc: liwei.ma@gmail.com,  emacs-devel@gnu.org
> Date: Thu, 02 Jul 2020 11:00:26 +0200
> 
> > A decision to disregard our documentation is not mine to take
> > (although I personally do have an opinion, of course).  It is
> > something the community as a whole needs to decide, and then we will
> > have to convince the Powers that Be of the GNU project; good luck with
> > that!
> 
> Mmm.  I see that e.g. GCC[1], GDB[2] and Guix[3][4] put out "development
> snapshots" fresh off the master branch (≈weekly, daily, and continuously
> respectively).  Are they more diligent with documentation than Emacs is?

Development snapshots are just that: snapshots of the current
repository's master branch.  As such, they are irrelevant to the issue
at hand, because we are talking about releases, not snapshots.  (If
someone wants to set up producing daily snapshots for Emacs, I won't
mind, but doing that will not affect the release schedule in any way.)

However, since you asked: at least GDB does require the relevant
documentation changes (NEWS and the manual) with every code change
that has user-visible effect; not sure about the other 2 projects.  Of
course, GDB is a very different project in many aspects.

> > I think it was 26.3, and the problem is not the decision, the problem
> > was how much time it took.  Too much, IMO.
> 
> 25.3 was the "⚠🚨 Red alert! Enriched Text is insecure! 🚨⚠" release

Time flies; sorry for misremembering.

> Here are some (lengthy) threads that the 25.3 release process triggered.
> Off the top of my head, I don't remember if there were any conclusions
> wrt hastening this process…

What else is new?

Re: When will emacs 27.1 be officially released?

[Kévin Le Gouguec]

Eli Zaretskii <eliz@gnu.org> writes:

> Development snapshots are just that: snapshots of the current
> repository's master branch.  As such, they are irrelevant to the issue
> at hand, because we are talking about releases, not snapshots.

My reasoning for suggesting snapshots went something like:

1. A lot of time passes between changes being committed, and users
   reporting regressions caused by these changes.

2. How could we tighten this feedback loop, so that we can spend less
   time gritting our teeth and waiting for bug reports during pretests?

3. If we offered development snapshots, maybe some users would feel
   adventurous enough to try them, and maybe some of them would even
   report bugs.

4. When we cut a release branch, we could feel more confident about the
   lack of regressions, because the most severe ones will have been
   caught thanks to snapshots.

Granted, maybe the intersection between "wants the bleeding edge" and
"won't run git pull" is an empty set, and snapshots would not bring
significantly more exposure to the master branch 🤷

>> > I think it was 26.3, and the problem is not the decision, the problem
>> > was how much time it took.  Too much, IMO.
>> 
>> 25.3 was the "⚠🚨 Red alert! Enriched Text is insecure! 🚨⚠" release
>
> Time flies; sorry for misremembering.

It sure does; I had misremembered too and had to to a double-take :)

Re: When will emacs 27.1 be officially released?

[Tassilo Horn]

Paul Eggert <eggert@cs.ucla.edu> writes:

>>> A method that works reasonably well in other projects is to update
>>> manuals and NEWS as we go, not just before a release.
>> I started requesting that some time ago, with limited success.
>
> Is there some way we could step that up?  E.g., perhaps start by
> reminding people who commit code changes but not changes to the
> corresponding documentation that they need to do the documenation
> ASAP.

It would be awesome if there was an automatic way to check if some code
I have touched is already documented in the manual and might require
adaption, i.e., diff in, links to relevant parts of the manual out.  I
think it occurred to me a few times that I've added another argument to
some function, for example, and didn't even realize that this function
was documented in the manual.

What would also be nice was a way to write something like

  @IncludeEmacsDefunDocs{my-function}{lisp/my.el}

which would be replaced by

  @defun my-function arg
  Docstring of my-function where ARG is replaced with @{arg}.
  @end defun

because at least in the Elisp manual, most function and variable
descriptions are (almost) identical to the corresponding docstrings
anyway.

BTW, I just looked at the docs and it seems that in large parts the
function descriptions in the manual read

  This function takes a @var{coin} and returns a @var{beer}.

(indicative) whereas the docstring reads

  Take a COIN and return a BEER.

(imperative).  I know the latter is our convention for function
docstrings.  Is the former our convention for documenting functions in
the manual?

Bye,
Tassilo

Re: When will emacs 27.1 be officially released?

[Paul Eggert]

On 7/2/20 1:29 PM, Tassilo Horn wrote:
> I just looked at the docs and it seems that in large parts the
> function descriptions in the manual read
> 
>   This function takes a @var{coin} and returns a @var{beer}.
> 
> (indicative) whereas the docstring reads
> 
>   Take a COIN and return a BEER.
> 
> (imperative).  I know the latter is our convention for function
> docstrings.  Is the former our convention for documenting functions in
> the manual?

Yes but I'd rather we switched to imperative, for consistency and brevity.

Re: When will emacs 27.1 be officially released?

[Tassilo Horn]

Paul Eggert <eggert@cs.ucla.edu> writes:

>> I just looked at the docs and it seems that in large parts the
>> function descriptions in the manual read
>> 
>>   This function takes a @var{coin} and returns a @var{beer}.
>> 
>> (indicative) whereas the docstring reads
>> 
>>   Take a COIN and return a BEER.
>> 
>> (imperative).  I know the latter is our convention for function
>> docstrings.  Is the former our convention for documenting functions
>> in the manual?
>
> Yes but I'd rather we switched to imperative, for consistency and
> brevity.

I'm all for consistency though the imperative style feels a bit awkward
to me.  Oftentimes, it's applied only to the first sentence of a
docstring and not completely.  For example, find-file-noselect's
docstring almost gets it right but then has the indicative sentence

  The buffer is not selected, just returned to the caller.

in the middle instead of the proper

  Do not select the buffer, just return it to the caller.

Bye,
Tassilo

Re: Do pretests reach end users? (was: When will emacs 27.1 be officially released?)

[Dmitry Alexandrov]

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

May I chime in?

Eli Zaretskii <eliz@gnu.org> wrote:
> it takes a long time for Emacs problems to be discovered and reported.  A new Emacs release can take years to reach end users.  We are routinely receiving bug reports about changes made two or more releases ago.  If you are looking for a single most important reason why it takes so long to put out another pretest, it is this one: experience shows that it takes weeks if not months for enough people to try a pretest and report the problems they see.

Emacs pretest release?  Is that a thing for systems other than Microsoft Windows and Guix?

— Unstable Debian comes with Emacs 26, Ubuntu gets Emacs from Debian.
— Arch comes with version 26, AURʼs ‘emacs27’ is 27.0.60 — an outdated February snapshot [1].
— Unstable Nix, again, contain 26th Emacs.
— Fedora provides only stable version of Emacs.
— Homebrew — guess what?

And even pretest releases for Windows do not seem to be mentioned in any way on <https://gnu.org/s/emacs>.  How users are supposed to get them?

In other words, I am not much surprised of the lack of early bugreports.

[1] https://aur.archlinux.org/packages/emacs27-git/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

Re: When will emacs 27.1 be officially released?

[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. ]]]

  > I actually wrote something like the above several times, urging people
  > to write documentation even if they don't feel their English is good
  > enough.  That's not "pairing", but the result should be the same.  It
  > even happened a few times.

That shows this approach can lead to good documentation.  Those of
you who hesitate for that reason, please give it a try.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Tassilo Horn <tsdh@gnu.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  liwei.ma@gmail.com,  emacs-devel@gnu.org,
>   kevin.legouguec@gmail.com
> Date: Thu, 02 Jul 2020 22:29:13 +0200
> 
> What would also be nice was a way to write something like
> 
>   @IncludeEmacsDefunDocs{my-function}{lisp/my.el}
> 
> which would be replaced by
> 
>   @defun my-function arg
>   Docstring of my-function where ARG is replaced with @{arg}.
>   @end defun
> 
> because at least in the Elisp manual, most function and variable
> descriptions are (almost) identical to the corresponding docstrings
> anyway.

I think "most" and "almost identical" is inaccurate here.  IME, most
of the descriptions in the manual are quite different from the doc
strings.

Doc strings have some limitations you need to observe: the first line
has to be a complete sentence and should mention the arguments; the
text should be short enough; there are some subtle rules for
referencing symbols that shouldn't produce hyperlinks; etc.  Living
with these limitations in the manual as well will produce suboptimal
text, IMO.

The (quite extreme, IMO) result of doing what you propose is the GNU
Guile manual: the Guile build procedure "snarfs" the doc strings from
the source code and produces 90% of the manual's text from them.  The
result is not a very good manual, at least IMO.  Just compare it with
the ELisp manual, and make your own conclusions about quality.

And then there's the user manual, where the doc strings are definitely
not the way to go, I hope you will agree.

> BTW, I just looked at the docs and it seems that in large parts the
> function descriptions in the manual read
> 
>   This function takes a @var{coin} and returns a @var{beer}.
> 
> (indicative) whereas the docstring reads
> 
>   Take a COIN and return a BEER.
> 
> (imperative).  I know the latter is our convention for function
> docstrings.  Is the former our convention for documenting functions in
> the manual?

Yes.  Just one of those minor stylistic differences that make the
manual a good reading, whereas the doc strings are terse and
functional.

Re: Do pretests reach end users? (was: When will emacs 27.1 be officially released?)

[Eli Zaretskii]

> From: Dmitry Alexandrov <dag@gnui.org>
> Cc: Kévin Le Gouguec <kevin.legouguec@gmail.com>,
>   liwei.ma@gmail.com,
>   emacs-devel@gnu.org
> Date: Fri, 03 Jul 2020 03:48:02 +0300
> 
> May I chime in?

Sure.

> Eli Zaretskii <eliz@gnu.org> wrote:
> > it takes a long time for Emacs problems to be discovered and reported.  A new Emacs release can take years to reach end users.  We are routinely receiving bug reports about changes made two or more releases ago.  If you are looking for a single most important reason why it takes so long to put out another pretest, it is this one: experience shows that it takes weeks if not months for enough people to try a pretest and report the problems they see.
> 
> Emacs pretest release?  Is that a thing for systems other than Microsoft Windows and Guix?

First, I didn't say "pretest release": there's no such thing.  A
pretest is not a "release", it's a tarball meant to be tested by
people who track the Emacs development.  Its difference from the
corresponding Git branch is that it is a tarball that builds like a
release would, and thus one of its main purposes is to see that the
tarball itself doesn't miss anything (which would mean we need to fix
our procedure for producing the tarball).  And the other important
purpose is to catch the attention of people here and encourage them to
switch to the pretest version instead of the Git version, so that they
could discover any last-minute problems.

> — Unstable Debian comes with Emacs 26, Ubuntu gets Emacs from Debian.
> — Arch comes with version 26, AURʼs ‘emacs27’ is 27.0.60 — an outdated February snapshot [1].
> — Unstable Nix, again, contain 26th Emacs.
> — Fedora provides only stable version of Emacs.
> — Homebrew — guess what?
> 
> And even pretest releases for Windows do not seem to be mentioned in any way on <https://gnu.org/s/emacs>.  How users are supposed to get them?

They aren't.  We cannot control the policies of the various distros,
and cannot rely on them for being part of the pretest.  Sometimes they
are, nonetheless, presumably because the people who are responsible
for the distros read the announcements about the pretests, and that is
good.  But it isn't the main means for pretesting.

> In other words, I am not much surprised of the lack of early bugreports.

IME, changes to the Git repository also take several weeks to generate
reports about problems.  Severe problems, like crashes upon startup,
are, of course reported much faster, but a pretest version is always
quite stable and devoid of such problems.

So I don't see how all this could help making a release faster.  The
fundamental problem, as I see it, is that Emacs is a very large and
complex package, which can be used for a plethora of different jobs,
and it takes time for some of the features to be actually used by
someone, and yet more time for such usage to bump into some rare bug.
But rare bugs could nevertheless be severe enough for us to avoid.
How to solve this is the important question in this thread, at least
for me.

Re: When will emacs 27.1 be officially released?

[Tassilo Horn]

Eli Zaretskii <eliz@gnu.org> writes:

>> What would also be nice was a way to write something like
>> 
>>   @IncludeEmacsDefunDocs{my-function}{lisp/my.el}
>> 
>> which would be replaced by
>> 
>>   @defun my-function arg
>>   Docstring of my-function where ARG is replaced with @{arg}.
>>   @end defun
>> 
>> because at least in the Elisp manual, most function and variable
>> descriptions are (almost) identical to the corresponding docstrings
>> anyway.
>
> I think "most" and "almost identical" is inaccurate here.  IME, most
> of the descriptions in the manual are quite different from the doc
> strings.

It's an exaggeration for sure.  But I think we can settle on "they carry
the same information using different writing styles."  Well, for
commands the manual is usually much simpler relying on the fact that the
`interactive' spec guides the user through the proper usage.  But I'm
talking more about the technical Elisp manual.

> Doc strings have some limitations you need to observe: the first line
> has to be a complete sentence and should mention the arguments; the
> text should be short enough; there are some subtle rules for
> referencing symbols that shouldn't produce hyperlinks; etc.  Living
> with these limitations in the manual as well will produce suboptimal
> text, IMO.

I think the docstring rules aren't bad for the manual per-se and the
formatting rules can probably be transformed to equivalent texinfo
constructs.

> The (quite extreme, IMO) result of doing what you propose is the GNU
> Guile manual: the Guile build procedure "snarfs" the doc strings from
> the source code and produces 90% of the manual's text from them.  The
> result is not a very good manual, at least IMO.  Just compare it with
> the ELisp manual, and make your own conclusions about quality.

I didn't have a look yet but I didn't want to suggest that our manuals
be only collection of docstrings!  But at least in the more technical
documentation like the Elisp manual I see no big problem in embedding
them _while still_ surrounding them with prose and examples (as we
already do).

> And then there's the user manual, where the doc strings are definitely
> not the way to go, I hope you will agree.

Yes, I do.

>> BTW, I just looked at the docs and it seems that in large parts the
>> function descriptions in the manual read
>> 
>>   This function takes a @var{coin} and returns a @var{beer}.
>> 
>> (indicative) whereas the docstring reads
>> 
>>   Take a COIN and return a BEER.
>> 
>> (imperative).  I know the latter is our convention for function
>> docstrings.  Is the former our convention for documenting functions
>> in the manual?
>
> Yes.  Just one of those minor stylistic differences that make the
> manual a good reading, whereas the doc strings are terse and
> functional.

Agreed, but still work some might find unnecessary or burdensome.  I
mean, we're hackers no English linguists, frequently not even native
speakers. ;-)

And to make it clear: I'm actually in favor of a "no major change
without appropriate documentation" policy.  I'm just looking for
possibilities to make that easier.  For example, such a hypothetical
@IncludeEmacsDefunDocs thingy could also act the same way as a missing
+++ in NEWS where someone else could replace that placeholder later with
stylistically correct manual documentation.

Bye,
Tassilo

Re: Do pretests reach end users?

[Dmitry Gutov]

On 03.07.2020 09:21, Eli Zaretskii wrote:
>> — Unstable Debian comes with Emacs 26, Ubuntu gets Emacs from Debian.
>> — Arch comes with version 26, AURʼs ‘emacs27’ is 27.0.60 — an outdated February snapshot [1].
>> — Unstable Nix, again, contain 26th Emacs.
>> — Fedora provides only stable version of Emacs.
>> — Homebrew — guess what?
>>
>> And even pretest releases for Windows do not seem to be mentioned in any way on<https://gnu.org/s/emacs>.  How users are supposed to get them?
> They aren't.  We cannot control the policies of the various distros,
> and cannot rely on them for being part of the pretest.  Sometimes they
> are, nonetheless, presumably because the people who are responsible
> for the distros read the announcements about the pretests, and that is
> good.  But it isn't the main means for pretesting.

What about the official website, though?

Re: Do pretests reach end users?

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 3 Jul 2020 12:59:31 +0300
> Cc: liwei.ma@gmail.com, kevin.legouguec@gmail.com, emacs-devel@gnu.org
> 
> >> And even pretest releases for Windows do not seem to be mentioned in any way on<https://gnu.org/s/emacs>.  How users are supposed to get them?
> > They aren't.  We cannot control the policies of the various distros,
> > and cannot rely on them for being part of the pretest.  Sometimes they
> > are, nonetheless, presumably because the people who are responsible
> > for the distros read the announcements about the pretests, and that is
> > good.  But it isn't the main means for pretesting.
> 
> What about the official website, though?

What about it?

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Tassilo Horn <tsdh@gnu.org>
> Cc: eggert@cs.ucla.edu,  liwei.ma@gmail.com,  emacs-devel@gnu.org,
>   kevin.legouguec@gmail.com
> Date: Fri, 03 Jul 2020 09:24:43 +0200
> 
> > I think "most" and "almost identical" is inaccurate here.  IME, most
> > of the descriptions in the manual are quite different from the doc
> > strings.
> 
> It's an exaggeration for sure.  But I think we can settle on "they carry
> the same information using different writing styles."  Well, for
> commands the manual is usually much simpler relying on the fact that the
> `interactive' spec guides the user through the proper usage.  But I'm
> talking more about the technical Elisp manual.

The ELisp manual indeed carries the same information as the doc
strings, but it uses a very different style.

For example, the imperative style is IMO inappropriate for the manual
(think about reading the book), while the indicative style of the
manual wastes precious screen space if we'd use it in doc strings.

Moreover, the manual should (and does in many cases) intersperse
documentation with extended explanations of various aspects: the
rationale, the additional details, the relation to other functions or
variables, etc.

> > Doc strings have some limitations you need to observe: the first line
> > has to be a complete sentence and should mention the arguments; the
> > text should be short enough; there are some subtle rules for
> > referencing symbols that shouldn't produce hyperlinks; etc.  Living
> > with these limitations in the manual as well will produce suboptimal
> > text, IMO.
> 
> I think the docstring rules aren't bad for the manual per-se and the
> formatting rules can probably be transformed to equivalent texinfo
> constructs.

I suggest that you take a few doc strings and the corresponding manual
descriptions, and see how well your theory corresponds to practice.
IME, the differences are frequently significant, and cannot be
produced by programmatic text transformations.  But if I'm wrong, and
some significant amount of text can be produced in an automated way,
I'm of course for it.

> And to make it clear: I'm actually in favor of a "no major change
> without appropriate documentation" policy.  I'm just looking for
> possibilities to make that easier.  For example, such a hypothetical
> @IncludeEmacsDefunDocs thingy could also act the same way as a missing
> +++ in NEWS where someone else could replace that placeholder later with
> stylistically correct manual documentation.

If it works and makes the job easier for the contributors while still
keeping the documentation quality high enough, sure.

Re: Do pretests reach end users?

[Dmitry Gutov]

On 03.07.2020 14:43, Eli Zaretskii wrote:
>> From: Dmitry Gutov<dgutov@yandex.ru>
>> Date: Fri, 3 Jul 2020 12:59:31 +0300
>> Cc:liwei.ma@gmail.com,kevin.legouguec@gmail.com,emacs-devel@gnu.org
>>
>>>> And even pretest releases for Windows do not seem to be mentioned in any way on<https://gnu.org/s/emacs>.  How users are supposed to get them?
>>> They aren't.  We cannot control the policies of the various distros,
>>> and cannot rely on them for being part of the pretest.  Sometimes they
>>> are, nonetheless, presumably because the people who are responsible
>>> for the distros read the announcements about the pretests, and that is
>>> good.  But it isn't the main means for pretesting.
>> What about the official website, though?
> What about it?

I can/should contain information on how to try the "next" version.

There are no links to development snapshots and related instructions. No 
quickly available information on how to participate in the project (one 
needs to click on "Documentation & Support" scroll down and then find 
the word "CONTRIBUTE" at the very end of the page).

Improving on any of these can increase the number of users trying out 
our development snapshots and reporting bugs. Which should lead to 
faster stabilization.

Re: Do pretests reach end users?

[Dmitry Alexandrov]

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

Eli Zaretskii <eliz@gnu.org> wrote:
> Dmitry Alexandrov <dag@gnui.org> wrote:
>> Emacs pretest release?  Is that a thing for systems other than Microsoft Windows and Guix?
>
> I didn't say "pretest release": there's no such thing.  A pretest is not a "release"

Okay.  (Though to me ‘pretest’ still looks like an adjective there.)

> it's a tarball [with sources]

https://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-27/emacs-27.0.91-x86_64-installer.exe

> meant to be tested by people who track the Emacs development.

I believe, people who track Emacs development rather build from master.

> Its difference from the corresponding Git branch is that it is a tarball that builds like a release would, and thus one of its main purposes is to see that the tarball itself doesn't miss anything (which would mean we need to fix our procedure for producing the tarball).

Aha.  Thanks for explanation.

Yet, I suppose, only a neglectable minority of bugs can be introduced by release procedure itself.

> And the other important purpose is to catch the attention of people here and encourage them to switch to the pretest version instead of the Git version

That is, it exists to encourage those who track the master branch to downgrade?  o_O

> IME, changes to the Git repository also take several weeks to generate reports about problems.

Well, for me thatʼs easily understandable: I normally use Emacs master, but rebuild it only when its time to restart it for out-of-band reasons, which indeed happens once in a week or even couple of weeks.  I suppose, I am not unique here.


>>  Unstable Debian comes with Emacs 26, Ubuntu gets Emacs from Debian.   Arch comes with version 26, AURʼs ‘emacs27’ is 27.0.60 — an outdated February snapshot [1].   Unstable Nix, again, contain 26th Emacs.   Fedora provides only stable version of Emacs.   Homebrew — guess what?

> We cannot control the policies of the various distros

Of course, you can!

Just declare the next pretest version 27.1 instead — and youʼll see dozens of various distros from unstable Debian to Termux (a distribution of terminal applications for Android-like OSes) obediently picking it up.

Current stable Debian will never pick it up, of course, so its users are safe from any new bugs and features, and testing Debian — only after running it in for a few weeks in unstable.

> and [we] cannot rely on them for being part of the pretest.

Indeed, _now_ you can not.  That looks like a problem to me.

> Sometimes they are, nonetheless, presumably because the people who are responsible for the distros read the announcements about the pretests

Any example?

With your clarification about what pretests are, I have to withdraw Guix from the list of systems where they are available — its ‘emacs-next’ is built from Git.  That is, the _only_ known to me system left, where Emacs pretests are available for installation, is Microsoft Windows.

> But it isn't the main means for pretesting.

Sure.  From all of the above we can surmise that main pretesters are Windows users, who somehow learn (from Reddit-like resources?) about pretests and download them from gnu.org.

Well...  Windows is the most popular desktop system after all, but I would really like to see GNU Emacs better tested on secondary platforms, such as GNU/Linux, too.


And I see two ways to achieve it.

The first one is to contact all distributors one by one, explaining them that they better be reading announcements for Emacs pretests in order to package them in their unstable branches, as Emacs pretest is actually pretty stable for todayʼs standards of development.

If anyone would like to do that, I have a suggestion, where to start from — nixpkg-unstable:

| Maintainers:
|    Jason O'Conal <jason@oconal.id.au>,
|    Peter Simons <simons@cryp.to>,
|    John Wiegley <johnw@newartisans.com>,   <----
|    Adam Hose <adis@blad.is>
— https://nixos.org/nixos/packages.html?channel=nixpkgs-unstable&query=emacs

;-)

And the second one is already mentioned  — just declare what would be a pretest a release.

> Severe problems, like crashes upon startup, are, of course reported much faster, but a pretest version is always quite stable and devoid of such problems.
>
> So I don't see how all this could help making a release faster.

It can help persuade people in charge (such as you :-) to take advantage of the control over GNU distributors they have — and shorten the release cycle.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

Re: When will emacs 27.1 be officially released?

[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. ]]]

  > For example, the imperative style is IMO inappropriate for the manual
  > (think about reading the book), while the indicative style of the
  > manual wastes precious screen space if we'd use it in doc strings.

That is one of many big differences.  Manual text and doc string text
are different at every level.  Everyone, please read the node Doc
Strings and Manuals in the GNU Coding Standards before posting about
this topic.

Each doc string is meant to be read by itself, so it must explain
the necessary background that we cannot assume the user knows.

By contrast, the manual consists of sections, each of which usually
describes several functions.  When writing the descriptions of those
functions, we avoid duplication.  Often the section states some background
outside the definitions of individual functions.

In this section, the function definitions don't say that TABLE is a
hash table.  They don't need to.  The title and introduction show
that.

BTW, do you see the style error in the definition of gethash?


8.2 Hash Table Access
=====================

This section describes the functions for accessing and storing
associations in a hash table.  In general, any Lisp object can be used
as a hash key, unless the comparison method imposes limits.  Any Lisp
object can also be used as the value.

 -- Function: gethash key table &optional default
     This function looks up KEY in TABLE, and returns its associated
     VALUE—or DEFAULT, if KEY has no association in TABLE.

 -- Function: puthash key value table
     This function enters an association for KEY in TABLE, with value
     VALUE.  If KEY already has an association in TABLE, VALUE replaces
     the old associated value.

 -- Function: remhash key table
     This function removes the association for KEY from TABLE, if there
     is one.  If KEY has no association, ‘remhash’ does nothing.

     Common Lisp note: In Common Lisp, ‘remhash’ returns non-‘nil’ if it
     actually removed an association and ‘nil’ otherwise.  In Emacs
     Lisp, ‘remhash’ always returns ‘nil’.

 -- Function: clrhash table
     This function removes all the associations from hash table TABLE,
     so that it becomes empty.  This is also called “clearing” the hash
     table.

     Common Lisp note: In Common Lisp, ‘clrhash’ returns the empty
     TABLE.  In Emacs Lisp, it returns ‘nil’.

 -- Function: maphash function table
     This function calls FUNCTION once for each of the associations in
     TABLE.  The function FUNCTION should accept two arguments—a KEY
     listed in TABLE, and its associated VALUE.  ‘maphash’ returns
     ‘nil’.



-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: When will emacs 27.1 be officially released?

[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. ]]]

On 7/2/20 1:29 PM, Tassilo Horn wrote:
> I just looked at the docs and it seems that in large parts the
> function descriptions in the manual read
> 
>   This function takes a @var{coin} and returns a @var{beer}.

That is incorrect style for @var.  @var{coin} refers to the value of
the argument named 'coin', as a proper name.  It does not mean a
_type_ of value, it means _the value_.

It is incorrect style to use an article before @var.

Here's the start of the definition of 'nth':

    @defun nth n list
    @anchor{Definition of nth}
    This function returns the @var{n}th element of @var{list}.  Elements
    are numbered starting with zero, so the @sc{car} of @var{list} is
    element number zero.  If the length of @var{list} is @var{n} or less,
    the value is @code{nil}.

If you want to describe the type of something, to say that it is a list,
write "list" with NO markup.

Ironically, this is one style point on which we treat doc strings the same
as manuals.  Here's the doc string of nth:

    Return the Nth element of LIST.
    N counts from zero.  If LIST is not that long, nil is returned.

Once again, no article before an argument name.

When the argument name is a data type name, you can take that
to mean that the value should have that type.  Thus, LIST should be a list.

Does the Texinfo manual explain these conventions?  ISTR it does.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Do pretests reach end users?

[Eli Zaretskii]

> Cc: dag@gnui.org, liwei.ma@gmail.com, kevin.legouguec@gmail.com,
>  emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 3 Jul 2020 23:23:16 +0300
> 
> >> What about the official website, though?
> > What about it?
> 
> I can/should contain information on how to try the "next" version.
> 
> There are no links to development snapshots and related instructions. No 
> quickly available information on how to participate in the project (one 
> needs to click on "Documentation & Support" scroll down and then find 
> the word "CONTRIBUTE" at the very end of the page).
> 
> Improving on any of these can increase the number of users trying out 
> our development snapshots and reporting bugs. Which should lead to 
> faster stabilization.

I agree that the site should have this information.  In general, the
site should be maintained more actively, IMO; volunteers are welcome.

Re: Do pretests reach end users?

[Eli Zaretskii]

> From: Dmitry Alexandrov <dag@gnui.org>
> Cc: liwei.ma@gmail.com,  kevin.legouguec@gmail.com, emacs-devel@gnu.org
> Date: Sat, 04 Jul 2020 04:31:50 +0300
> 
> https://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-27/emacs-27.0.91-x86_64-installer.exe

Wrong URL.  The important one is this:

  https://alpha.gnu.org/gnu/emacs/pretest/emacs-27.0.91.tar.xz

> > meant to be tested by people who track the Emacs development.
> 
> I believe, people who track Emacs development rather build from master.

Mostly, yes.  Which is why, when the release branch is cut, we ask
them to switch to the release branch instead.

> > Its difference from the corresponding Git branch is that it is a tarball that builds like a release would, and thus one of its main purposes is to see that the tarball itself doesn't miss anything (which would mean we need to fix our procedure for producing the tarball).
> 
> Aha.  Thanks for explanation.
> 
> Yet, I suppose, only a neglectable minority of bugs can be introduced by release procedure itself.

Perhaps; but there's no way of finding them except by producing a
tarball.

> > And the other important purpose is to catch the attention of people here and encourage them to switch to the pretest version instead of the Git version
> 
> That is, it exists to encourage those who track the master branch to downgrade?  o_O

Yes.

> > We cannot control the policies of the various distros
> 
> Of course, you can!
> 
> Just declare the next pretest version 27.1 instead

Why not declare the Git version 27.1 (or, rather, 28.1 instead; 27.1
is passé), then?

There are many absurd suggestions that could be made, but only a small
number of useful ones.  For some strange reason, I tend not to pay
attention to the former kind.

> > Sometimes they are, nonetheless, presumably because the people who are responsible for the distros read the announcements about the pretests
> 
> Any example?

I sometimes see versions like XX.YY.90 with telltale signs that they
were not the pretest.  Search the bug list if you are interested.

> That is, the _only_ known to me system left, where Emacs pretests are available for installation, is Microsoft Windows.

I believe you drew this conclusion because someone pointed you to the
wrong URL of the pretest; see above.

> Well...  Windows is the most popular desktop system after all, but I would really like to see GNU Emacs better tested on secondary platforms, such as GNU/Linux, too.

Actually, my hidden agenda is to deprecate the support for GNU/Linux
and other Posix platforms, and leave MS-Windows as the only system
Emacs supports.  To wit: my main development machine runs MS-Windows,
as the first step in that direction.  And, of course, the pretest
installer that you just told about, is only for Windows, for the same
reason.  But please don't tell anyone about this plan, not yet: they
won't understand.

> And I see two ways to achieve it.
> 
> The first one is to contact all distributors one by one, explaining them that they better be reading announcements for Emacs pretests in order to package them in their unstable branches, as Emacs pretest is actually pretty stable for todayʼs standards of development.

Doing that is obviously fine with me.  It can only benefit Emacs
development if the pretests are used and tested by more users.

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, liwei.ma@gmail.com, emacs-devel@gnu.org,
> 	kevin.legouguec@gmail.com
> Date: Fri, 03 Jul 2020 22:53:54 -0400
> 
>     Return the Nth element of LIST.
>     N counts from zero.  If LIST is not that long, nil is returned.
> 
> Once again, no article before an argument name.
> 
> When the argument name is a data type name, you can take that
> to mean that the value should have that type.  Thus, LIST should be a list.
> 
> Does the Texinfo manual explain these conventions?  ISTR it does.

If it does, I couldn't find it.  The word "article" is not used
anywhere in that manual, and the node that describes the @def*
commands doesn't seem to say that, either.  Where else to look for
that?

Re: Do pretests reach end users?

[Phillip Lord]

Dmitry Alexandrov <dag@gnui.org> writes:

> Eli Zaretskii <eliz@gnu.org> wrote:
>> Dmitry Alexandrov <dag@gnui.org> wrote:
>>> Emacs pretest release?  Is that a thing for systems other than
>>> Microsoft Windows and Guix?
>>
>> I didn't say "pretest release": there's no such thing.  A pretest is
>> not a "release"
>
> Okay.  (Though to me ‘pretest’ still looks like an adjective there.)
>
>> it's a tarball [with sources]
>
> https://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-27/emacs-27.0.91-x86_64-installer.exe


Yes, I release this (in a rather erratic fashion) as well as Emacs-28
snapshots, to make the pretests (and head) more accessible to people. I
think it would be good to do this a bit more widely, either with a
deb/rpm/snap/flatpack/etc.



>> But it isn't the main means for pretesting.
>
> Sure.  From all of the above we can surmise that main pretesters are
> Windows users, who somehow learn (from Reddit-like resources?) about
> pretests and download them from gnu.org.
>
> Well...  Windows is the most popular desktop system after all, but I
> would really like to see GNU Emacs better tested on secondary
> platforms, such as GNU/Linux, too.



To be honest, I suspect GNU/Linux gets more people testing it, because
the users of that platform are more likely to test things. It's also
relatively easy to build there -- once you have it set up "git pull;make
-j", and run from in source rather than installing and you are done.


>>
>> So I don't see how all this could help making a release faster.
>
> It can help persuade people in charge (such as you :-) to take
> advantage of the control over GNU distributors they have — and shorten
> the release cycle.

I think this is a secondary argument. It would be good to have
pre-releases (and snapshots) available to install because it is a good
thing in itself. If it shortens the release cycle that is a bonus.

Phil

Re: When will emacs 27.1 be officially released?

[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. ]]]

  > > Does the Texinfo manual explain these conventions?  ISTR it does.

  > If it does, I couldn't find it.  The word "article" is not used
  > anywhere in that manual, and the node that describes the @def*
  > commands doesn't seem to say that, either.  Where else to look for
  > that?

Maybe in Emacs Lisp ref?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Do pretests reach end users?

[Dmitry Alexandrov]

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

Eli Zaretskii <eliz@gnu.org> wrote:
>> https://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-27/emacs-27.0.91-x86_64-installer.exe
>
> Wrong URL.  The important one is this:
>
>   https://alpha.gnu.org/gnu/emacs/pretest/emacs-27.0.91.tar.xz

Is there a download counter on alpha.gnu.org to estimate how important it really is, I wonder?

>>> We cannot control the policies of the various distros
>>
>> Of course, you can!  Just declare the next pretest version 27.1 instead — and youʼll see dozens of various distros ‹…› obediently picking it up.
>
> Why not declare the Git version 27.1 (‹…›), then?

Because you are not a maintainer of the Git, perhaps?

>>> Sometimes [GNU distributions do partincipate in Emacs pretesting], nonetheless, presumably because the people who are responsible for the distros read the announcements about the pretests
>>
>> Any example?
>
> I sometimes see versions like XX.YY.90 with telltale signs that they were not the pretest.

???

Never mind, though.  There might be some examples, of course.  However, no _major_ GNU distribution does that — thatʼs the problem.

>> That is, the _only_ known to me system left, where Emacs pretests are available for installation, is Microsoft Windows.
>
> I believe you drew this conclusion because someone pointed you to the wrong URL of the pretest; see above.

Thankfully, no one came up with idea to disable listing on alpha.gnu.org so far, so there is no need to be pointed to exact URL, anyone can see what packages are present there.

Not to say, there is something unusual there, no.  GNU users indeed tend to rely on some more automated means to install software.  Preferably, on those preconfigured in their distribution.  Just uploading, say, debs there would hardly help, imho.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

Re: Do pretests reach end users?

[Dmitry Alexandrov]

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

Phillip Lord <phillip.lord@russet.org.uk> wrote:
> Dmitry Alexandrov <dag@gnui.org> writes:
>> Eli Zaretskii <eliz@gnu.org> wrote:
>>> Dmitry Alexandrov <dag@gnui.org> wrote:
>>>> Emacs pretest release?  Is that a thing for systems other than Microsoft Windows and Guix?
>>>
>>> it's a tarball [with sources]
>>
>> https://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-27/emacs-27.0.91-x86_64-installer.exe
>
> Yes, I release this (in a rather erratic fashion) as well as Emacs-28 snapshots

My gratitude for that (though I never happened to use them).

>> From all of the above we can surmise that main pretesters are Windows users, who somehow learn (from Reddit-like resources?) about pretests and download them from gnu.org.

> To be honest, I suspect GNU/Linux gets more people testing it, because the users of that platform are more likely to test things. It's also relatively easy to build there -- once you have it set up "git pull;make -j" and run from in source rather than installing and you are done.

Sure.  Thatʼs exactly why I supposed, that hardly anyone use the pretests as @eliz@gnu.org explained them: people are either on whatever their distro ships or build from master.

>>> So I don't see how all this could help making a release faster.
>>
>> It can help persuade people in charge (such as you :-) to take advantage of the control over GNU distributors they have — and shorten the release cycle.
>
> I think this is a secondary argument. It would be good to have pre-releases (and snapshots) available to install because it is a good thing in itself.

Indeed.  There is zero hope for major distros to ships nightly snapshots, though.  So until Emacs cycle is completely revamped only pretests and release candidates are in question.

> If it shortens the release cycle that is a bonus.

Shorting the release cycle is a _mean_ to achieve that — that was my point.

To recap: maintainers are unanimously unwilling to package a piece of software labelled ‘pretest’, that should be downloaded from a server named ‘alpha’.  You can either (a) persuade all of them, that this is not what it means, but actually a pretty stable thing for the year 2020, or (b) simply stop calling it ‘pretest’: the final result is identical.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

Re: When will emacs 27.1 be officially released?

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eggert@cs.ucla.edu, liwei.ma@gmail.com, kevin.legouguec@gmail.com,
> 	emacs-devel@gnu.org
> Date: Sat, 04 Jul 2020 22:35:33 -0400
> 
>   > > Does the Texinfo manual explain these conventions?  ISTR it does.
> 
>   > If it does, I couldn't find it.  The word "article" is not used
>   > anywhere in that manual, and the node that describes the @def*
>   > commands doesn't seem to say that, either.  Where else to look for
>   > that?
> 
> Maybe in Emacs Lisp ref?

Looked there now, couldn't find it.

Re: Do pretests reach end users?

[Sean Whitton]

Hello,

On Sat 04 Jul 2020 at 04:31AM +03, Dmitry Alexandrov wrote:

> Just declare the next pretest version 27.1 instead — and youʼll see dozens of various distros from unstable Debian to Termux (a distribution of terminal applications for Android-like OSes) obediently picking it up.
>
> Current stable Debian will never pick it up, of course, so its users are safe from any new bugs and features, and testing Debian — only after running it in for a few weeks in unstable.

Debian would probably not pick it up unless we didn't realise it was a
pretest, because except for our 'experimental' repository, we don't
upload things we wouldn't be happy to end up in a stable release.

-- 
Sean Whitton

Re: Do pretests reach end users?

[Phillip Lord]

Dmitry Alexandrov <dag@gnui.org> writes:

> Phillip Lord <phillip.lord@russet.org.uk> wrote:
>>> https://alpha.gnu.org/gnu/emacs/pretest/windows/emacs-27/emacs-27.0.91-x86_64-installer.exe
>>
>> Yes, I release this (in a rather erratic fashion) as well as Emacs-28 snapshots
>
> My gratitude for that (though I never happened to use them).

No worries. I don't happen to use them either!


>> To be honest, I suspect GNU/Linux gets more people testing it,
>> because the users of that platform are more likely to test
>> things. It's also relatively easy to build there -- once you have it
>> set up "git pull;make -j" and run from in source rather than
>> installing and you are done.
>
> Sure.  Thatʼs exactly why I supposed, that hardly anyone use the
> pretests as @eliz@gnu.org explained them: people are either on
> whatever their distro ships or build from master.


I wouldn't be so sure about that actually. I build form the release
branch most of the time; I am currently using a Emacs-27 build as my
main one. I'll move to Emacs-28 at some point during the Emacs-27
release cycle.




>>>> So I don't see how all this could help making a release faster.
>>>
>>> It can help persuade people in charge (such as you :-) to take
>>> advantage of the control over GNU distributors they have — and
>>> shorten the release cycle.
>>
>> I think this is a secondary argument. It would be good to have
>> pre-releases (and snapshots) available to install because it is a
>> good thing in itself.
>
> Indeed.  There is zero hope for major distros to ships nightly
> snapshots, though.  So until Emacs cycle is completely revamped only
> pretests and release candidates are in question.

Over all, I think that this would not be a good thing. You want Emacs to
be relatively stable out there, and only people with an interest to
install the pre-release or snapshots. Ubuntu has PPAs for exactly this
purpose.

The counter argument is MELPA, of course. The statistics show that most
MELPA users are quite happy and don't both with MELPA stable, but move
along on the bleeding edge of what ever packages they are using.



>> If it shortens the release cycle that is a bonus.
>
> Shorting the release cycle is a _mean_ to achieve that — that was my point.
>
> To recap: maintainers are unanimously unwilling to package a piece of
> software labelled ‘pretest’, that should be downloaded from a server
> named ‘alpha’.  You can either (a) persuade all of them, that this is
> not what it means, but actually a pretty stable thing for the year
> 2020, or (b) simply stop calling it ‘pretest’: the final result is
> identical.


I can see this. If we just had a shorter release cycle (especially a
minor release cycle), then a less stable Emacs might be less a worry,
since a new release would be just around the corner. Emacs bugs can be
annoying, but they generally do not break other things.

Phil