How to find when a function/var has been added

How to find when a function/var has been added

[Przemysław Wojnowski]

Hello everybody,

What is the fastest way to find out since when a function/var is available in 
Emacs? Only through NEWS?

It's common case when one writes an elisp package and want to preserve 
compatibility with previous Emacs versions.

In Java it's very common to see in docs on classes/methods/fields "Since: n", 
where "n" is Java version. Wouldn't such information help in core Emacs libs 
too? What do you think?

Thanks,
Przemysław

Re: How to find when a function/var has been added

[David Kastrup]

Przemysław Wojnowski <esperanto@cumego.com> writes:

> Hello everybody,
>
> What is the fastest way to find out since when a function/var is
> available in Emacs? Only through NEWS?
>
> It's common case when one writes an elisp package and want to preserve
> compatibility with previous Emacs versions.
>
> In Java it's very common to see in docs on classes/methods/fields
> "Since: n", where "n" is Java version. Wouldn't such information help
> in core Emacs libs too? What do you think?

customize-changed is an alias for ‘customize-changed-options’.

(customize-changed &optional SINCE-VERSION)

Customize all settings whose meanings have changed in Emacs itself.
This includes new user options and faces, and new customization
groups, as well as older options and faces whose meanings or
default values have changed since the previous major Emacs
release.

With argument SINCE-VERSION (a string), customize all settings
that were added or redefined since that version.

[back]

-- 
David Kastrup

RE: How to find when a function/var has been added

[Drew Adams]

> customize-changed...

Yes, useful, of course.

I think maybe Przemysław is asking for something more, including
changes to the default value or possible values of an option, and
changes to the behavior or at least the calling sequence of an
existing function.

Dunno how much would be feasible or what forms it might take, but
I agree that there is a use case for it.

Re: How to find when a function/var has been added

[Przemysław Wojnowski]

> I think maybe Przemysław is asking for something more, including
> changes to the default value or possible values of an option, and
> changes to the behavior or at least the calling sequence of an
> existing function.
>
> Dunno how much would be feasible or what forms it might take, but
> I agree that there is a use case for it.
>
I was thinking about adding "Since: ${emacs-version}" to docs of functions and 
variables just to make it easier to write backward compatible packages.

If I would like to preserve compatibility with Emacs 24.3.1 I wouldn't use newer 
functions/values. Now it is not that easy (at least for me) to find out since 
when a function/variable/package is in Emacs, which makes programming a bit slower.

Re: How to find when a function/var has been added

[Stephen Leake]

Przemysław Wojnowski <esperanto@cumego.com> writes:

>> I think maybe Przemysław is asking for something more, including
>> changes to the default value or possible values of an option, and
>> changes to the behavior or at least the calling sequence of an
>> existing function.
>>
>> Dunno how much would be feasible or what forms it might take, but
>> I agree that there is a use case for it.
>>
> I was thinking about adding "Since: ${emacs-version}" to docs of
> functions and variables just to make it easier to write backward
> compatible packages.
>
> If I would like to preserve compatibility with Emacs 24.3.1 I wouldn't
> use newer functions/values. Now it is not that easy (at least for me)
> to find out since when a function/variable/package is in Emacs, which
> makes programming a bit slower.

I write and test the code for Emacs 25, then byte-compile in Emacs 24;
that identifies the functions/variables that need attention. Unless
there's some function that changed behavior without any other change; we
usually treat that as a bug, unless the change is actually fixing a bug.

Adding emacs version info to _all_ definitions would be tedious; there
would be a very small chance that any particular bit would be needed.
That's not true for customize, since those are user-visible things.

-- 
-- Stephe

Re: How to find when a function/var has been added

[Przemysław Wojnowski]

> customize-changed is an alias for ‘customize-changed-options’.
This is great. Thanks!

Shouldn't this run by default and automatically update user's settings (after 
confirmation) when a user starts a newer Emacs?

This makes me wonder - why there's no "config-version" or sth similar in .emacs 
file? Having this it would be easier to automatically upgrade config.
My guess is that many users don't even know about "customize-changed".

Re: How to find when a function/var has been added

[Eli Zaretskii]

> Date: Wed, 05 Aug 2015 20:38:44 +0200
> From: Przemysław Wojnowski <esperanto@cumego.com>
> 
> What is the fastest way to find out since when a function/var is available in 
> Emacs?

I use "git annotate".

Re: How to find when a function/var has been added

[Przemysław Wojnowski]

>> What is the fastest way to find out since when a function/var is available in
>> Emacs?
> I use "git annotate".
It may be some solution for core Emacs developers, but you can't expect a 
programmer, that wants to write an Emacs package, to do this.

Adding simple "Since: x" to a doc is not very time consuming, but may make life 
much easier to its users.

Re: How to find when a function/var has been added

[Stephen Leake]

Przemysław Wojnowski <esperanto@cumego.com> writes:

>>> What is the fastest way to find out since when a function/var is available in
>>> Emacs?
>> I use "git annotate".
> It may be some solution for core Emacs developers, but you can't
> expect a programmer, that wants to write an Emacs package, to do this.
>
> Adding simple "Since: x" to a doc is not very time consuming, 

Not for one doc, but it adds up _very_ quickly. And it will be very
easy to forget to change it on a later edit; no information is one
thing, wrong information is worse.

> but may
> make life much easier to its users.

I guess we disagree on that.

In particular, it is only useful for a very small subset of
functions/variables. The ones that you happen to need are useful, but
there's no way to know in advance which ones that will be.

I like Eli's 'git annotate' solution;
that's an automated way to get mostly what you are asking for.

It needs another step; relating a git hash to an Emacs version. I hope
there's a git function that takes a hash and two tags and tells you if
the hash occured between them.

-- 
-- Stephe

Re: How to find when a function/var has been added

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Date: Thu, 06 Aug 2015 04:59:51 -0500
> 
> I like Eli's 'git annotate' solution;
> that's an automated way to get mostly what you are asking for.
> 
> It needs another step; relating a git hash to an Emacs version.

"git describe" should do it, if we make sure to tag releases.
Example:

  $ git describe fac8492664246c49ee145802cc124aa9e1636e7b
  emacs-24.5-rc3-fixed-5416-gfac8492

Re: How to find when a function/var has been added

[Przemysław Wojnowski]

>> Adding simple "Since: x" to a doc is not very time consuming,
>
> Not for one doc, but it adds up _very_ quickly.
So it's good that "Since: x" adds up. It only means that number of documented
functions/vars is growing.
Maybe it could be generated and added, at the end of each docstring, by some
script that goes through git history and/or Changelog/NEWS and gets Emacs
version from there.

> And it will be very
> easy to forget to change it on a later edit; no information is one
> thing, wrong information is worse.
I don't get this one. To change "Since: x" on later edit? Why?

>> but may
>> make life much easier to its users.
>
> I guess we disagree on that.
>
> In particular, it is only useful for a very small subset of
> functions/variables. The ones that you happen to need are useful, but
> there's no way to know in advance which ones that will be.
Clearly we disagree here.
IMHO it is useful to any programmer that would like to write an Emacs package 
that works across some emacsen. For such people Emacs is a programming platform 
that can be deployed in different versions (API versions - in case of Emacs 
different libs/functions/vars). Having "Since: x" makes it faster learn and 
hence to write software that works on different versions of the platform.

For example Jira is such a platform. It may be installed in different versions,
and a programmer that writes Jira plugins needs to know which
classes/methods/vars can be used safely for a plugin.
Nobody expects such programmer to grep Jira's git history just to find it out.
It's just counterproductive.
When a company is developing a platform (say Jira) it makes programming on it
as easy as possible. Similar mindset is useful in non-commercial software too.

> I like Eli's 'git annotate' solution;
> that's an automated way to get mostly what you are asking for.
>
> It needs another step; relating a git hash to an Emacs version. I hope
> there's a git function that takes a hash and two tags and tells you if
> the hash occured between them.
You missed the step where a programmer have to download sources of the platform
just to find out whether a function can be used, when targeting some version
of the platform.

Re: How to find when a function/var has been added

[Stephen Leake]

Przemysław Wojnowski <esperanto@cumego.com> writes:

>> And it will be very
>> easy to forget to change it on a later edit; no information is one
>> thing, wrong information is worse.
> I don't get this one. To change "Since: x" on later edit? Why?

If the arg list or semantics of the function changes, the version in
which that happens should be noted.

On the other hand, we really try to avoid such changes in Emacs core, so
this may not be much of a problem. It is more of a problem in ELPA
packages.

>>> but may
>>> make life much easier to its users.
>>
>> I guess we disagree on that.
>>
>> In particular, it is only useful for a very small subset of
>> functions/variables. The ones that you happen to need are useful, but
>> there's no way to know in advance which ones that will be.

> Clearly we disagree here.
> IMHO it is useful to any programmer that would like to write an Emacs
> package that works across some emacsen. For such people Emacs is a
> programming platform that can be deployed in different versions (API
> versions - in case of Emacs different libs/functions/vars). Having
> "Since: x" makes it faster learn and hence to write software that
> works on different versions of the platform.

I misspoke; it would be useful information to have. But the cost of
providing it, at least with the mechanism you propose, is too high, for
a volunteer project like Emacs. Especially since there are other
reasonable ways to get the same information.

My point is that there are a _lot_ of functions in Emacs, and any given
project uses a _very_ small subset of them. So the cost/benefit ratio is
inherently skewed towards low benefit.

> For example Jira is such a platform. It may be installed in different
> versions, and a programmer that writes Jira plugins needs to know
> which classes/methods/vars can be used safely for a plugin.

What mechanism do they use to document this information? And how much
money do they spend doing that?

Another example is Google Android; every function has "added in API nn"
annotation in the html docs. I have no idea how they generate that.

But Google has lots of money to pay programmers to produce that info,
and they have a strong compatibility goal; they want people to write
code that can run on many different versions of the Android platform.

Emacs has neither the money, nor the strong compatibility goal (the latter
partly because of the former, of course).

>> I like Eli's 'git annotate' solution;
>> that's an automated way to get mostly what you are asking for.
>>
>> It needs another step; relating a git hash to an Emacs version. I hope
>> there's a git function that takes a hash and two tags and tells you if
>> the hash occured between them.

> You missed the step where a programmer have to download sources of the platform
> just to find out whether a function can be used, when targeting some version
> of the platform.

Yes, But "git clone" is fast enough; that is just part of the cost of
writing multi-version code.

In general, the lack of this kind of detailed documentation is part of
the cost of using open-source software developed by volunteers. 

-- 
-- Stephe

Re: How to find when a function/var has been added

[Przemysław Wojnowski]

W dniu 09.08.2015 o 08:26, Stephen Leake pisze:
> Przemysław Wojnowski <esperanto@cumego.com> writes:
>>> And it will be very
>>> easy to forget to change it on a later edit; no information is one
>>> thing, wrong information is worse.
>> I don't get this one. To change "Since: x" on later edit? Why?
>
> If the arg list or semantics of the function changes, the version in
> which that happens should be noted.
This could be noted in function's docs.

>> Clearly we disagree here.
>> IMHO it is useful to any programmer that would like to write an Emacs
>> package that works across some emacsen. For such people Emacs is a
>> programming platform that can be deployed in different versions (API
>> versions - in case of Emacs different libs/functions/vars). Having
>> "Since: x" makes it faster learn and hence to write software that
>> works on different versions of the platform.
>
> I misspoke; it would be useful information to have. But the cost of
> providing it, at least with the mechanism you propose, is too high, for
> a volunteer project like Emacs. Especially since there are other
> reasonable ways to get the same information.
All I propose is to add such information incrementally. For some libs it's very 
easy to add - for example seq.el has been added in Emacs 25, so it can be added 
right away. And not all the functions has to be documented in such way -  I 
don't expect anyone to add "Since" to, say, car function. ;-)

>> For example Jira is such a platform. It may be installed in different
>> versions, and a programmer that writes Jira plugins needs to know
>> which classes/methods/vars can be used safely for a plugin.
>
> What mechanism do they use to document this information? And how much
> money do they spend doing that?
>
> Another example is Google Android; every function has "added in API nn"
> annotation in the html docs. I have no idea how they generate that.
Another example is Clojure.
I don't thing any of them used some mechanism. AFAIK the standard way is to add 
it manually (and possibly _incrementally_ when added after releasing an API).

> But Google has lots of money to pay programmers to produce that info,
> and they have a strong compatibility goal; they want people to write
> code that can run on many different versions of the Android platform.
What goal does Emacs have? Is there any project vision?

> Emacs has neither the money, nor the strong compatibility goal (the latter
> partly because of the former, of course).
There's no direct relationship between the two. Money != compatibility.
Probably here are more great developers that most companies could afford.

> In general, the lack of this kind of detailed documentation is part of
> the cost of using open-source software developed by volunteers.
No, its just cost of attitude. Adding it incrementally costs close to nothing.

Anyways, this discussion leads nowhere, because either way nothing will happen.

PS Sorry for late reply. I've been busy. :-|

Cheers,
Przemysław

Re: How to find when a function/var has been added

[Stefan Monnier]

> What is the fastest way to find out since when a function/var is available
> in Emacs? Only through NEWS?

I know this is not the answer you're looking for, but back when I was
writing Elisp code that was not part of Emacs, I used the following two
strategies:
1- memory: this is really fast when it works, but obviously that doesn't
   always work so well.
2- use the function(ality) and let your users report when it doesn't
   work in Emacs-NN.MM.  This has the advantage of being lazy, and
   letting you learn indirectly which Emacs versions you need to pay
   attention to.


        Stefan

Re: How to find when a function/var has been added

[Stefan Monnier]

> What is the fastest way to find out since when a function/var is available
> in Emacs? Only through NEWS?

BTW, I'd welcome a little Elisp command that searches for a given
function/variable in NEWS and in ChangeLog to indicate when it
first appeared.


        Stefan