NEWS entries -- user-visible?

NEWS entries -- user-visible?

[Andy Wingo]

Greets,

It seems that some of the NEWS entries that are currently there for the
1.9.0 release reflect awesomeness, but not awesomeness which users can
react to.

Specifically, I am going to remove the following NEWS entries, which are
great stuff but thankfully invisible to the user:

    ** Guile now uses Gnulib as a portability aid

    ** Primitive procedures (aka. "subrs") are now stored in double cells
    This removes the subr table and simplifies the code.

    ** Primitive procedures with more than 3 arguments (aka. "gsubrs") are
    no longer implemented using the "compiled closure" mechanism.  This
    simplifies code and reduces both the storage and run-time overhead.

Let me know any feedback you might have. I'll be working on compiling a
more comprehensive NEWS tonight and in the coming days.

Peace,

Andy
-- 
http://wingolog.org/

Re: NEWS entries -- user-visible?

[Julian Graham]

Hi Andy,

As mentioned on IRC, I bet there are ways to pitch these changes to
make them comprehensible to users.  I think you're right to ditch the
second one, but for the first and third:

>    ** Guile now uses Gnulib as a portability aid

** Guile now uses components from Gnulib for portability to a wider
variety of POSIX and non-POSIX systems.


>    ** Primitive procedures with more than 3 arguments (aka. "gsubrs") are
>    no longer implemented using the "compiled closure" mechanism.  This
>    simplifies code and reduces both the storage and run-time overhead.

** Primitive procedures accepting more than 3 arguments now execute
faster and consume less memory.


Regards,
Julian

Re: NEWS entries -- user-visible?

[Neil Jerram]

Andy Wingo <wingo@pobox.com> writes:

> Greets,
>
> It seems that some of the NEWS entries that are currently there for the
> 1.9.0 release reflect awesomeness, but not awesomeness which users can
> react to.
>
> Specifically, I am going to remove the following NEWS entries, which are
> great stuff but thankfully invisible to the user:
>
>     ** Guile now uses Gnulib as a portability aid
>
>     ** Primitive procedures (aka. "subrs") are now stored in double cells
>     This removes the subr table and simplifies the code.
>
>     ** Primitive procedures with more than 3 arguments (aka. "gsubrs") are
>     no longer implemented using the "compiled closure" mechanism.  This
>     simplifies code and reduces both the storage and run-time overhead.
>
> Let me know any feedback you might have. I'll be working on compiling a
> more comprehensive NEWS tonight and in the coming days.

Hi Andy,

Well, my first reaction was that we would lose something by removing
these.  But on reflection I think you're right.  These entries are
only meaningful to Guile-internal developers (i.e. people developing
Guile itself), and are similar in information content to commit
messages, only at a slightly higher level.  An active developer would
be following the mailing list and git repository, and so couldn't
learn anything new from these.

Also it's a good discipline to make sure that all of our NEWS is
meaningful to users (including application developers, of course), and
leaving in items like these would tend to obscure that overall
picture.

Therefore I'm happy with removing them.

Regards,
        Neil

Re: NEWS entries -- user-visible?

[Neil Jerram]

Julian Graham <joolean@gmail.com> writes:

> Hi Andy,
>
> As mentioned on IRC, I bet there are ways to pitch these changes to
> make them comprehensible to users.  I think you're right to ditch the
> second one, but for the first and third:
>
>>    ** Guile now uses Gnulib as a portability aid
>
> ** Guile now uses components from Gnulib for portability to a wider
> variety of POSIX and non-POSIX systems.

I see where you're heading with this, but for me this NEWS item still
isn't specific enough to mean anything to a user.

It seems we're aiming towards saying:

** Guile now runs correctly on more platforms.  Since the 1.8.x
   series, support for the following platforms has been added: A, B,
   C.

But (1) I'm not sure we have precise information to hand on what A, B
and C are; and there's no value in the NEWS item without the detail.

And (2) to be honest there is no such thing as "runs correctly".  What
we really mean is that we've fixed particular portability-related bugs
on particular platforms by using Gnulib.  And we really ought to have
- and in most cases I think we already do have - specific NEWS items
for each of those bugs.

So, overall, I'm not persuaded that there's any value in this item.

>>    ** Primitive procedures with more than 3 arguments (aka. "gsubrs") are
>>    no longer implemented using the "compiled closure" mechanism.  This
>>    simplifies code and reduces both the storage and run-time overhead.
>
> ** Primitive procedures accepting more than 3 arguments now execute
> faster and consume less memory.

Here, on the other hand, I now agree with you; this is likely to be
interest to application developers.  It would be even better if it had
a pointer to where to find more details - even a mailing list thread
or a commit, if there's nothing better?

Regards,
        Neil

Re: NEWS entries -- user-visible?

[Ludovic Courtès]

Hello!

Neil Jerram <neil@ossau.uklinux.net> writes:

> Julian Graham <joolean@gmail.com> writes:
>
>>>    ** Guile now uses Gnulib as a portability aid
>>
>> ** Guile now uses components from Gnulib for portability to a wider
>> variety of POSIX and non-POSIX systems.
>
> I see where you're heading with this, but for me this NEWS item still
> isn't specific enough to mean anything to a user.

I think GNU users, especially on non-GNU platforms (proprietary Unices,
etc.), have come to know what Gnulib is, and to appreciate it
(hopefully), which is why I thought it would make sense to mention it.

> It seems we're aiming towards saying:
>
> ** Guile now runs correctly on more platforms.  Since the 1.8.x
>    series, support for the following platforms has been added: A, B,
>    C.
>
> But (1) I'm not sure we have precise information to hand on what A, B
> and C are;

Portability work is endless, we just can't provide this information.

Thanks,
Ludo'.

Re: NEWS entries -- user-visible?

[Ludovic Courtès]

Hello,

Andy Wingo <wingo@pobox.com> writes:

> Specifically, I am going to remove the following NEWS entries, which are
> great stuff but thankfully invisible to the user:
>
>     ** Guile now uses Gnulib as a portability aid
>
>     ** Primitive procedures (aka. "subrs") are now stored in double cells
>     This removes the subr table and simplifies the code.
>
>     ** Primitive procedures with more than 3 arguments (aka. "gsubrs") are
>     no longer implemented using the "compiled closure" mechanism.  This
>     simplifies code and reduces both the storage and run-time overhead.

I agree with removing the two last entries (I had been overzealous ;-)),
but maybe not the first as explained in another message.

Thanks,
Ludo'.

Re: NEWS entries -- user-visible?

[Neil Jerram]

ludo@gnu.org (Ludovic Courtès) writes:

> I think GNU users, especially on non-GNU platforms (proprietary Unices,
> etc.), have come to know what Gnulib is, and to appreciate it
> (hopefully), which is why I thought it would make sense to mention it.

Perhaps it should go in a new section of the NEWS, with title
something like `News about how Guile itself is developed'.  Then we
might also mention using Git, libunistring etc.  But there's a risk
we'd just end up duplicated information in README and HACKING, I
think.

>> It seems we're aiming towards saying:
>>
>> ** Guile now runs correctly on more platforms.  Since the 1.8.x
>>    series, support for the following platforms has been added: A, B,
>>    C.
>>
>> But (1) I'm not sure we have precise information to hand on what A, B
>> and C are;
>
> Portability work is endless, we just can't provide this information.

Agreed.

    Neil

Re: NEWS entries -- user-visible?

[Ludovic Courtès]

Neil Jerram <neil@ossau.uklinux.net> writes:

> ludo@gnu.org (Ludovic Courtès) writes:
>
>> I think GNU users, especially on non-GNU platforms (proprietary Unices,
>> etc.), have come to know what Gnulib is, and to appreciate it
>> (hopefully), which is why I thought it would make sense to mention it.
>
> Perhaps it should go in a new section of the NEWS, with title
> something like `News about how Guile itself is developed'.  Then we
> might also mention using Git, libunistring etc.  But there's a risk
> we'd just end up duplicated information in README and HACKING, I
> think.

I was really thinking of GNU users, not GNU hackers.  I think users, not
just hackers, may be interested in knowing Gnulib is used.

That said, if you feel otherwise, it probably means that things aren't
that clearcut, so I won't insist on keeping this entry.

Thanks,
Ludo'.

Re: NEWS entries -- user-visible?

[Neil Jerram]

ludo@gnu.org (Ludovic Courtès) writes:

> Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> ludo@gnu.org (Ludovic Courtès) writes:
>>
>>> I think GNU users, especially on non-GNU platforms (proprietary Unices,
>>> etc.), have come to know what Gnulib is, and to appreciate it
>>> (hopefully), which is why I thought it would make sense to mention it.
>>
>> Perhaps it should go in a new section of the NEWS, with title
>> something like `News about how Guile itself is developed'.  Then we
>> might also mention using Git, libunistring etc.  But there's a risk
>> we'd just end up duplicated information in README and HACKING, I
>> think.
>
> I was really thinking of GNU users, not GNU hackers.  I think users, not
> just hackers, may be interested in knowing Gnulib is used.
>
> That said, if you feel otherwise, it probably means that things aren't
> that clearcut, so I won't insist on keeping this entry.

I'm really not sure.  It's an interesting idea.  And I think it
touches on the part of GNU philosophy that tries not to draw a firm
line between users and developers.  Do you think it's worth asking
people on gnu-prog-discuss?

Regards,
        Neil

Re: NEWS entries -- user-visible?

[Ludovic Courtès]

Neil Jerram <neil@ossau.uklinux.net> writes:

> I'm really not sure.  It's an interesting idea.  And I think it
> touches on the part of GNU philosophy that tries not to draw a firm
> line between users and developers.  Do you think it's worth asking
> people on gnu-prog-discuss?

Yes, why not.  Would you like to do this?

Thanks,
Ludo'.

Re: NEWS entries -- user-visible?

[Neil Jerram]

ludovic.courtes@inria.fr (Ludovic Courtès) writes:

> Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> I'm really not sure.  It's an interesting idea.  And I think it
>> touches on the part of GNU philosophy that tries not to draw a firm
>> line between users and developers.  Do you think it's worth asking
>> people on gnu-prog-discuss?
>
> Yes, why not.  Would you like to do this?

I just checked standards.texi before going ahead with this, and
actually it seems pretty clear:

"In addition to its manual, the package should have a file named
@file{NEWS} which contains a list of user-visible changes worth
mentioning.  ..."

So I'd say that use of Gnulib (in general) should not be a NEWS item.
I think HACKING would be the right place to mention it - and it would
be just as accessible there (as in NEWS) to blurred users/developers.

Regards,
        Neil

Re: NEWS entries -- user-visible?

[Ludovic Courtès]

Hi!

Neil Jerram <neil@ossau.uklinux.net> writes:

> "In addition to its manual, the package should have a file named
> @file{NEWS} which contains a list of user-visible changes worth
> mentioning.  ..."
>
> So I'd say that use of Gnulib (in general) should not be a NEWS item.
> I think HACKING would be the right place to mention it - and it would
> be just as accessible there (as in NEWS) to blurred users/developers.

Sure, that's a possibility.

(I think we don't disagree on what `NEWS' should contain, but on whether
Gnulib qualifies as "user-visible".)

Thanks,
Ludo'.

Re: NEWS entries -- user-visible?

[Neil Jerram]

ludo@gnu.org (Ludovic Courtès) writes:

> Hi!
>
> Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> "In addition to its manual, the package should have a file named
>> @file{NEWS} which contains a list of user-visible changes worth
>> mentioning.  ..."
>>
>> So I'd say that use of Gnulib (in general) should not be a NEWS item.
>> I think HACKING would be the right place to mention it - and it would
>> be just as accessible there (as in NEWS) to blurred users/developers.
>
> Sure, that's a possibility.
>
> (I think we don't disagree on what `NEWS' should contain, but on whether
> Gnulib qualifies as "user-visible".)

I would certainly agree that individual portability fixes should be in
NEWS.  Is that what you have in mind?

    Neil

Re: NEWS entries -- user-visible?

[Ludovic Courtès]

Hello,

Neil Jerram <neil@ossau.uklinux.net> writes:

> ludo@gnu.org (Ludovic Courtès) writes:

>> (I think we don't disagree on what `NEWS' should contain, but on whether
>> Gnulib qualifies as "user-visible".)
>
> I would certainly agree that individual portability fixes should be in
> NEWS.  Is that what you have in mind?

Hmm, indirectly, yes.  I suspect it wouldn't be easy to list individual
fixes, though we could at least mention those that were reported in the
bug tracker.

Thanks,
Ludo'.