unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* How to find when a function/var has been added
@ 2015-08-05 18:38 Przemysław Wojnowski
  2015-08-05 19:06 ` David Kastrup
                   ` (3 more replies)
  0 siblings, 4 replies; 15+ messages in thread
From: Przemysław Wojnowski @ 2015-08-05 18:38 UTC (permalink / raw)
  To: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 18:38 How to find when a function/var has been added Przemysław Wojnowski
@ 2015-08-05 19:06 ` David Kastrup
  2015-08-05 19:32   ` Drew Adams
  2015-08-05 20:46   ` Przemysław Wojnowski
  2015-08-05 19:25 ` Eli Zaretskii
                   ` (2 subsequent siblings)
  3 siblings, 2 replies; 15+ messages in thread
From: David Kastrup @ 2015-08-05 19:06 UTC (permalink / raw)
  To: Przemysław Wojnowski; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 18:38 How to find when a function/var has been added Przemysław Wojnowski
  2015-08-05 19:06 ` David Kastrup
@ 2015-08-05 19:25 ` Eli Zaretskii
  2015-08-05 21:01   ` Przemysław Wojnowski
  2015-08-07 15:57 ` Stefan Monnier
  2015-08-07 15:58 ` Stefan Monnier
  3 siblings, 1 reply; 15+ messages in thread
From: Eli Zaretskii @ 2015-08-05 19:25 UTC (permalink / raw)
  To: Przemysław Wojnowski; +Cc: emacs-devel

> 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".




^ permalink raw reply	[flat|nested] 15+ messages in thread

* RE: How to find when a function/var has been added
  2015-08-05 19:06 ` David Kastrup
@ 2015-08-05 19:32   ` Drew Adams
  2015-08-05 20:53     ` Przemysław Wojnowski
  2015-08-05 20:46   ` Przemysław Wojnowski
  1 sibling, 1 reply; 15+ messages in thread
From: Drew Adams @ 2015-08-05 19:32 UTC (permalink / raw)
  To: David Kastrup, Przemysław Wojnowski; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 19:06 ` David Kastrup
  2015-08-05 19:32   ` Drew Adams
@ 2015-08-05 20:46   ` Przemysław Wojnowski
  1 sibling, 0 replies; 15+ messages in thread
From: Przemysław Wojnowski @ 2015-08-05 20:46 UTC (permalink / raw)
  To: David Kastrup; +Cc: emacs-devel

> 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".



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 19:32   ` Drew Adams
@ 2015-08-05 20:53     ` Przemysław Wojnowski
  2015-08-06  9:54       ` Stephen Leake
  0 siblings, 1 reply; 15+ messages in thread
From: Przemysław Wojnowski @ 2015-08-05 20:53 UTC (permalink / raw)
  To: Drew Adams, David Kastrup; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 19:25 ` Eli Zaretskii
@ 2015-08-05 21:01   ` Przemysław Wojnowski
  2015-08-06  9:59     ` Stephen Leake
  0 siblings, 1 reply; 15+ messages in thread
From: Przemysław Wojnowski @ 2015-08-05 21:01 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 20:53     ` Przemysław Wojnowski
@ 2015-08-06  9:54       ` Stephen Leake
  0 siblings, 0 replies; 15+ messages in thread
From: Stephen Leake @ 2015-08-06  9:54 UTC (permalink / raw)
  To: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 21:01   ` Przemysław Wojnowski
@ 2015-08-06  9:59     ` Stephen Leake
  2015-08-06 14:37       ` Eli Zaretskii
  2015-08-08  7:37       ` Przemysław Wojnowski
  0 siblings, 2 replies; 15+ messages in thread
From: Stephen Leake @ 2015-08-06  9:59 UTC (permalink / raw)
  To: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-06  9:59     ` Stephen Leake
@ 2015-08-06 14:37       ` Eli Zaretskii
  2015-08-08  7:37       ` Przemysław Wojnowski
  1 sibling, 0 replies; 15+ messages in thread
From: Eli Zaretskii @ 2015-08-06 14:37 UTC (permalink / raw)
  To: Stephen Leake; +Cc: emacs-devel

> 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





^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 18:38 How to find when a function/var has been added Przemysław Wojnowski
  2015-08-05 19:06 ` David Kastrup
  2015-08-05 19:25 ` Eli Zaretskii
@ 2015-08-07 15:57 ` Stefan Monnier
  2015-08-07 15:58 ` Stefan Monnier
  3 siblings, 0 replies; 15+ messages in thread
From: Stefan Monnier @ 2015-08-07 15:57 UTC (permalink / raw)
  To: Przemysław Wojnowski; +Cc: emacs-devel

> 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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-05 18:38 How to find when a function/var has been added Przemysław Wojnowski
                   ` (2 preceding siblings ...)
  2015-08-07 15:57 ` Stefan Monnier
@ 2015-08-07 15:58 ` Stefan Monnier
  3 siblings, 0 replies; 15+ messages in thread
From: Stefan Monnier @ 2015-08-07 15:58 UTC (permalink / raw)
  To: Przemysław Wojnowski; +Cc: emacs-devel

> 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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-06  9:59     ` Stephen Leake
  2015-08-06 14:37       ` Eli Zaretskii
@ 2015-08-08  7:37       ` Przemysław Wojnowski
  2015-08-09  6:26         ` Stephen Leake
  1 sibling, 1 reply; 15+ messages in thread
From: Przemysław Wojnowski @ 2015-08-08  7:37 UTC (permalink / raw)
  To: Stephen Leake, emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-08  7:37       ` Przemysław Wojnowski
@ 2015-08-09  6:26         ` Stephen Leake
  2015-08-12 20:39           ` Przemysław Wojnowski
  0 siblings, 1 reply; 15+ messages in thread
From: Stephen Leake @ 2015-08-09  6:26 UTC (permalink / raw)
  To: emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

* Re: How to find when a function/var has been added
  2015-08-09  6:26         ` Stephen Leake
@ 2015-08-12 20:39           ` Przemysław Wojnowski
  0 siblings, 0 replies; 15+ messages in thread
From: Przemysław Wojnowski @ 2015-08-12 20:39 UTC (permalink / raw)
  To: Stephen Leake, emacs-devel

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



^ permalink raw reply	[flat|nested] 15+ messages in thread

end of thread, other threads:[~2015-08-12 20:39 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2015-08-05 18:38 How to find when a function/var has been added Przemysław Wojnowski
2015-08-05 19:06 ` David Kastrup
2015-08-05 19:32   ` Drew Adams
2015-08-05 20:53     ` Przemysław Wojnowski
2015-08-06  9:54       ` Stephen Leake
2015-08-05 20:46   ` Przemysław Wojnowski
2015-08-05 19:25 ` Eli Zaretskii
2015-08-05 21:01   ` Przemysław Wojnowski
2015-08-06  9:59     ` Stephen Leake
2015-08-06 14:37       ` Eli Zaretskii
2015-08-08  7:37       ` Przemysław Wojnowski
2015-08-09  6:26         ` Stephen Leake
2015-08-12 20:39           ` Przemysław Wojnowski
2015-08-07 15:57 ` Stefan Monnier
2015-08-07 15:58 ` Stefan Monnier

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).