Is there an way to check when an Emacs Lisp function was added to Emacs?

Question

I am the author of an Emacs package, and occasionally when working on my package, I will come across a useful-looking function and use it in my code. Then, shortly after I release, someone using an older Emacs version (but still a version that I want to support) will report that the function is not defined, and I realize that this function has only recently been added in the latest version of Emacs, and am forced to revert the change (example). So, is there any way to check the version of Emacs in which a specific function was first added? Or better yet, a way to read my whole elisp file and report the minimum version of Emacs it would require and why?

I suppose the brute-force solution would be to install every version of Emacs I want to support and test-compile my package with each of them. So I'm asking if there's a better way that.

Answer 1

The file etc/NEWS and its siblings for older versions NEWS.[12]* contains very detailed change history for every Emacs version since the neolithic age. (The oldest ones are -- perhaps predictably -- somewhat less detailed.)

Unfortunately, this information is not in machine readable form; but you could still grep around for the information with some less-than-perfect precision.

Here is a quick and dirty Awk script I cobbled together.

#!/bin/sh

# Path to your emacs etc directory
emacs_etc=$HOME/git/emacs-snapshot/etc

# Reverse the order of the wildcard matches so we search newest to oldest
printf '%s\n' $emacs_etc/NEWS.[12]* $emacs_etc/NEWS |
tac |

xargs awk -v fn="$1" 'BEGIN { regex="^[*]+ New .*" fn }
    /^\*[^*]/ { version=$NF }
    $0~regex { print version ":" $0; exit 0 }
    END { exit 1 }'

This is slightly inexact in that it requires the entry to begin with New (this seems to be somewhat consistent in the newer entries, but less so in the older ones) and it will find a prefix of the search string, not necessarily an exact match.

However, the change you are looking for does not match this expected format. The commit which added set-default-toplevel-value just added a free-form notice to NEWS which does not mention that it introduced a new variable.

To actually find it, I located it in the source tree (src/eval.c) and a straightforward git blame on the line which contains the definition pointed straight to the pertinent commit. (In the general case, you might need to peel off commits in layers; fortunately, Git has fairly good support for this kind of thing.)