Readings for an emacs package maintainer ?

Readings for an emacs package maintainer ?

[Xavier Maillard]

Hi,

I am looking for a good documentation on best practices for an
emacs package maintainer.

I want packages I am maintaining to be still supported for old
emacsen from, say, 19.x to latest possible (including xemacs).

Currently, the big problems for me is to keep on using old
functions or have a common rule to define my macros.

What do you, emacs developers, do in order to have the larger
backward compatibility spectrum ?

I was thinking about a package-compat.el but I do not know how
well it will work with macros defined here at compile time.

Regards,

Xavier

Re: Readings for an emacs package maintainer ?

[Lennart Borgman]

Maybe look in the packages Drew develpe and maintain?


On Mon, Jun 1, 2009 at 9:18 AM, Xavier Maillard <xma@gnu.org> wrote:
> Hi,
>
> I am looking for a good documentation on best practices for an
> emacs package maintainer.
>
> I want packages I am maintaining to be still supported for old
> emacsen from, say, 19.x to latest possible (including xemacs).
>
> Currently, the big problems for me is to keep on using old
> functions or have a common rule to define my macros.
>
> What do you, emacs developers, do in order to have the larger
> backward compatibility spectrum ?
>
> I was thinking about a package-compat.el but I do not know how
> well it will work with macros defined here at compile time.
>
> Regards,
>
> Xavier
>
>
>

RE: Readings for an emacs package maintainer ?

[Drew Adams]

> Maybe look in the packages Drew develpe and maintain?

Please, no (and no flames please). Nothing I do in any libraries is intended as
good practice to follow. But thanks for the compliment. ;-)

One tip that might help, which you are probably already aware of, is that it is
typically better to test for the actual function or variable you need, rather
than to test for a particular feature or `emacs-major-version'. IOW, use
(fboundp 'some-new-fn) rather than (featurep 'some-feature) or (>
(emacs-major-version 21). There are exceptions. In particular, sometimes
`emacs-major-version' is the best you can do.

There are other tips in the Elisp manual, node Coding Conventions. These, for
instance:

 If a package needs to define an alias or a new function for
 compatibility with some other version of Emacs, name it with the
 package prefix, not with the raw name with which it occurs in the
 other version.  Here is an example from Gnus, which provides many
 examples of such compatibility issues.

  (defalias 'gnus-point-at-bol
    (if (fboundp 'point-at-bol)
        'point-at-bol
      'line-beginning-position))

 Redefining or advising an Emacs primitive is a bad idea.  It may do
 the right thing for a particular program, but there is no telling
 what other programs might break as a result.

 If a file does replace any of the standard functions or library
 programs of Emacs, prominent comments at the beginning of the file
 should say which functions are replaced, and how the behavior of
 the replacements differs from that of the originals.

Re: Readings for an emacs package maintainer ?

[Reiner Steib]

> There are other tips in the Elisp manual, node Coding
> Conventions. These, for instance:
>
>  If a package needs to define an alias or a new function for
>  compatibility with some other version of Emacs, name it with the
>  package prefix, not with the raw name with which it occurs in the
>  other version.  Here is an example from Gnus, which provides many
>  examples of such compatibility issues.
>
>   (defalias 'gnus-point-at-bol
>     (if (fboundp 'point-at-bol)
>         'point-at-bol
>       'line-beginning-position))
>
>  Redefining or advising an Emacs primitive is a bad idea.  It may do
>  the right thing for a particular program, but there is no telling
>  what other programs might break as a result.

It's funny that I pointed Xavier to this very node in March 2008 when
reporting such a bug in color-theme (see https://gna.org/bugs/?9494)
which overwrites `replace-in-string' in an incompatible way which
breaks Gnus, Muse, emacs-jabber, etc.  Unfortunately Xavier didn't fix
this up to now, AFAIK.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo---  |  PGP key available  |  http://rsteib.home.pages.de/

Re: Readings for an emacs package maintainer ?

[Lennart Borgman]

On Mon, Jun 1, 2009 at 8:56 PM, Reiner Steib <reinersteib+gmane@imap.cc> wrote:
>> There are other tips in the Elisp manual, node Coding
>> Conventions. These, for instance:
>>
>>  If a package needs to define an alias or a new function for
>>  compatibility with some other version of Emacs, name it with the
>>  package prefix, not with the raw name with which it occurs in the
>>  other version.  Here is an example from Gnus, which provides many
>>  examples of such compatibility issues.
>>
>>   (defalias 'gnus-point-at-bol
>>     (if (fboundp 'point-at-bol)
>>         'point-at-bol
>>       'line-beginning-position))
>>
>>  Redefining or advising an Emacs primitive is a bad idea.  It may do
>>  the right thing for a particular program, but there is no telling
>>  what other programs might break as a result.
>
> It's funny that I pointed Xavier to this very node in March 2008 when
> reporting such a bug in color-theme (see https://gna.org/bugs/?9494)
> which overwrites `replace-in-string' in an incompatible way which
> breaks Gnus, Muse, emacs-jabber, etc.  Unfortunately Xavier didn't fix
> this up to now, AFAIK.


Ah, I wondered why a lot of things stopped working when I tested
color-themes. (This is very troublesome with something like mumamo
since debugging fontification errors is hard and time consuming.)

RE: Readings for an emacs package maintainer ?

[Drew Adams]

> > There are other tips in the Elisp manual, node Coding
> > Conventions. These, for instance:
...
> It's funny that I pointed Xavier to this very node in March 2008 when
> reporting such a bug in color-theme (see https://gna.org/bugs/?9494)
> which overwrites `replace-in-string' in an incompatible way which
> breaks Gnus, Muse, emacs-jabber, etc.  Unfortunately Xavier didn't fix
> this up to now, AFAIK.

Dunno about that particular context, but I like to remember that guidelines are,
well just guidelines. They are meant to help, and they help more if reasons are
provide, so people can understand them.

My feeling is that advice should be freely given, with nothing expected in
return. It is unreasonable to expect someone to follow some advice you give, no
matter how well intentioned you are, and no matter how good the advice might be.
If there is such an expectation, then it is not advice that you give, but
something else.

I myself do redefine some Emacs functions, and I occasionally do use `defadvice'
(though I avoid it). I have my reasons. But I have no problem with someone
giving me advice not to do so. And I agree with the manual's guidelines.

They are only guidelines, however, which means (1) They are likely to be helpful
_in general_. (2) Use your own judgment: use them when you want to; ignore them
when you want to.

Re: Readings for an emacs package maintainer ?

[Xavier MAILLARD]

Hi again,

Le Mon, 01 Jun 2009 09:18:35 +0200,
Xavier Maillard <xma@gnu.org> a écrit :

> Hi,
> 
> I am looking for a good documentation on best practices for an
> emacs package maintainer.
> 
> I want packages I am maintaining to be still supported for old
> emacsen from, say, 19.x to latest possible (including xemacs).

A totally fresh example hitted me earlier today: old-style backquotes.
My package contains lots of them, I can easily rewrite them using the
new style but I have to (I want to) be sure it could work with emacs <
19.29 (or so).

Wrapping something like:

(if (and (> emacs-major-version 19)
	 (> emacs-minor-version 29))
   (defmacro my-modern-macro...)
  (defmacro my-old-style-macro))

Is that the best way ?

Regards

Re: Readings for an emacs package maintainer ?

[Miles Bader]

Xavier MAILLARD <xma@gnu.org> writes:
>> I want packages I am maintaining to be still supported for old
>> emacsen from, say, 19.x to latest possible (including xemacs).
>
> A totally fresh example hitted me earlier today: old-style backquotes.
> My package contains lots of them, I can easily rewrite them using the
> new style but I have to (I want to) be sure it could work with emacs <
> 19.29 (or so).

I hope 19.29 is just an arbitrarily-chosen example -- 19.29 was released
14 years ago!  Unless you really have users using older versions, there
seems little reason to go to great lengths to support them.

> (if (and (> emacs-major-version 19)
> 	 (> emacs-minor-version 29))
>    (defmacro my-modern-macro...)
>   (defmacro my-old-style-macro))
>
> Is that the best way ?

I think if you're going to keep the code containing old-style
backquotes, there's no point in duplicating it with new-style
backquotes.  The old-style code is ugly but it will still work in a
modern emacs.

-Miles

-- 
Cannon, n. An instrument employed in the rectification of national boundaries.

Re: Readings for an emacs package maintainer ?

[Stephen J. Turnbull]

Miles Bader writes:

 > I hope 19.29 is just an arbitrarily-chosen example -- 19.29 was released
 > 14 years ago!  Unless you really have users using older versions, there
 > seems little reason to go to great lengths to support them.

A recent (October 2008) survey of a famous 4-letter financial firm
showed that about 5% of the >200 developers who responded were using
Emacs 19 variants (including Lucid Emacs 19.6 and Emacs 19.8 IIRC),
and there were more than 1% using Emacs 18.

I think it's quite possible that he has such users.

Re: Readings for an emacs package maintainer ?

[Miles Bader]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
>  > I hope 19.29 is just an arbitrarily-chosen example -- 19.29 was released
>  > 14 years ago!  Unless you really have users using older versions, there
>  > seems little reason to go to great lengths to support them.
>
> A recent (October 2008) survey of a famous 4-letter financial firm
> showed that about 5% of the >200 developers who responded were using
> Emacs 19 variants (including Lucid Emacs 19.6 and Emacs 19.8 IIRC),
> and there were more than 1% using Emacs 18.
>
> I think it's quite possible that he has such users.

Sure, and if he really does, oh well.

But I think versions < 19.29 are sufficiently ancient that it's ok to
recommend that maintainers not worry about them unless they have a
concrete reason to (for instance a complaint/bug-report/request from a
user running the older version).

Of course, individual circumstance may dictate otherwise, e.g. a package
that caters to older versions (or a site maintainer at a company like
the above...).

-Miles

-- 
[|nurgle|]  ddt- demonic? so quake will have an evil kinda setting? one that
            will  make every christian in the world foamm at the mouth?
[iddt]      nurg, that's the goal

Re: Readings for an emacs package maintainer ?

[Deniz Dogan]

2009/6/2 Stephen J. Turnbull <stephen@xemacs.org>:
> A recent (October 2008) survey of a famous 4-letter financial firm
> showed that about 5% of the >200 developers who responded were using
> Emacs 19 variants (including Lucid Emacs 19.6 and Emacs 19.8 IIRC),
> and there were more than 1% using Emacs 18.

I've heard about this survey, could you provide us with a link to this?

-- 
Deniz Dogan

Re: Readings for an emacs package maintainer ?

[Stephen J. Turnbull]

Deniz Dogan writes:
 > 2009/6/2 Stephen J. Turnbull <stephen@xemacs.org>:
 > > A recent (October 2008) survey of a famous 4-letter financial firm
 > > showed that about 5% of the >200 developers who responded were using
 > > Emacs 19 variants (including Lucid Emacs 19.6 and Emacs 19.8 IIRC),
 > > and there were more than 1% using Emacs 18.
 > 
 > I've heard about this survey, could you provide us with a link to this?

No.  It's internal data from the company.  I can ask my contact if he
minds if I release what he sent me, I guess.

BTW, that's a typo, should be October 2007.  I doubt it's changed much
though; if the guys using Emacs 18.55 have waited 20 years to upgrade,
I guess they aren't in a hurry.

RE: Readings for an emacs package maintainer ?

[Drew Adams]

> > I am looking for a good documentation on best practices for an
> > emacs package maintainer.
> > 
> > I want packages I am maintaining to be still supported for old
> > emacsen from, say, 19.x to latest possible (including xemacs).
> 
> A totally fresh example hitted me earlier today: old-style backquotes.
> My package contains lots of them, I can easily rewrite them using the
> new style but I have to (I want to) be sure it could work with emacs <
> 19.29 (or so).
> 
> Wrapping something like:
> (if (and (> emacs-major-version 19)
> 	 (> emacs-minor-version 29))
>    (defmacro my-modern-macro...)
>   (defmacro my-old-style-macro))
> 
> Is that the best way ?

Dunno what the best way is.

But aren't old-style backquotes still supported? I thought the problem was the
other way around, that new-style backquotes are not supported in older releases.
(That's just what I would have expected - haven't checked anything.)

If I'm right about this, then just keep your old-style backquotes. It just means
a few additional parentheses. ;-)

Re: Readings for an emacs package maintainer ?

[Bastien]

Xavier Maillard <xma@gnu.org> writes:

> What do you, emacs developers, do in order to have the larger
> backward compatibility spectrum ?

I'm under the impression that most developers only worry about backward
compatibility when users complain.  Which is a fairly wise way of being
lazy, no?

-- 
 Bastien

RE: Readings for an emacs package maintainer ?

[Drew Adams]

> > What do you, emacs developers, do in order to have the larger
> > backward compatibility spectrum ?
> 
> I'm under the impression that most developers only worry 
> about backward compatibility when users complain.  Which is
> a fairly wise way of being lazy, no?

Sure, unless you also want to help potential users who might not complain.

It really depends what you're trying to do. I tend to make things work in older
releases when the thing I'm creating is possible (reasonable to implement) in
the older releases also. I don't bother, if it's unreasonable. If something
depends on Unicode support, for instance, then Emacs 23 is a must.

Most of the time, the coding difference is not great, however, so it's no big
deal to also make stuff available to users of old releases. 

It does mean testing in the older releases, so that you will realize it if
function `blah' is not available in an older version and must be worked around.
I implement using Emacs 20 some of the time, then test in recent releases. That
typically means fewer gotchas (functions and features that don't exist) than the
other way around.

Q. Why bother? A. Why do you write your code in the first place? If it's for use
by others in addition to yourself, then why not help more of them use it?

There are *lots* of people who use Emacs versions installed by their IT
department, sometimes on hosts where they cannot install alternative code (at
least not for widespread use). And those IT-installed versions are often quite
old (Emacs 21 at Oracle, for example). 

Two reasons: (1) IT doesn't care whether users have the latest and greatest, and
more frequent updates means more work. (2) IT thinks older means more stable,
which means less work. Unicode will likely be an exception, at least in some
countries, but most new Emacs features are not things that will make IT
departments rush to scoop up the latest. 

I would guess that 99% of the developers at Oracle use Emacs 21 (or vi), simply
because that's what's there. In most cases, they could build Emacs on their
machines, for their own use or shared use by colleagues, but (I assume) they
don't care enough to do that.

There are many actual and potential Emacs users who do not necessarily want to
build Emacs themselves (1+). They use what's already available, and that is
often *not* the latest and greatest.

If you are interested in helping such users take advantage of your code, then
typically the effort needed is no big deal. You will need (and will develop, if
you do this) some awareness of which releases introduce which new functions,
macros, and variables - and change which signatures or behaviors. That's not a
bad thing to be aware of, in any case.

I would _guess_ that the fact that *lots* of Emacs users use older releases is
something underrecognized or underrepresented in the Emacs mailing lists and Web
sites. What proportion? Dunno. Maybe it's the majority - I really have no idea.
Does anyone on emacs-devel have a good idea of the proportion who use something
before Emacs 22? Is it 10%? 80%? Is there a breakdown somewhere of existing
users and their releases?

If Emacs had a Support department or were receiving regular maintenance revenue
from users of old releases, we would have such an idea. ;-)

Re: Readings for an emacs package maintainer ?

[Stefan Monnier]

> I want packages I am maintaining to be still supported for old
> emacsen from, say, 19.x to latest possible (including xemacs).

While it's arguably a desirable goal in itself, it has to be weighed
against the additional maintenance and testing burden.

So, in my case at least, I write&test my Elisp packages using Emacs-CVS,
and try to make it work on the latest released Emacs as well.  Past that
stage, it's the responsibility of the users to complain about problems
with older releases.
a) In most cases, they're pretty happy to fix the problem by upgrading.
b) In many other cases, they don't report the problem.
c) Some others are sufficiently bothered to report the problem.
d) Some report it and help come up with a fix.
I think my time is better spent adding new features than catering to
people in (b) you can't even be bothered to report the problem.
For (c) and (d), if the fix is easy to find or is found by the user,
I might include it in subsequent releases, unless it's too ugly.

I respect's people choice to use an older release, but they should
expect it not to work 100% with programs that aren't from the same era.


        Stefan


PS: In the last few years, I haven't received any report of problems
    linked to the use of an Emacs < 21.1.  So I really wouldn't worry
    about Emacs-19.29.  There might still be some user of Emacs-19.29,
    but they're extremely unlikely to use your new code.

Re: Readings for an emacs package maintainer ?

[Leo]

On 2009-06-01 21:35 +0100, Stefan Monnier wrote:
> I think my time is better spent adding new features than catering to
> people in (b) you can't even be bothered to report the problem.
> For (c) and (d), if the fix is easy to find or is found by the user,
> I might include it in subsequent releases, unless it's too ugly.

And people like me are grateful for the new features that make all of us
more productive with Emacs.

-- 
.:  Leo  :.  [ sdl.web AT gmail.com ]  .: I use Emacs :.