* 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 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: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 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 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 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: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 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-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
* 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
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 external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.