Make backwards compatibility explicit

README.md

@@ -27,6 +27,8 @@ Regardless of the inclusion strategies discussed above, my current scheme has a
 
 This means that when I break compatibility in the miscellaneous scripts, I have to make sure to merge the changes into all of my plug-ins. Even then, if a user has more than one of my plug-ins installed but updates only one of them, the other plug-ins (that are not yet up to date) can break (because of the backwards incompatible change).
 
+The `xolox#misc#compat#check()` function makes sure that incompatibilities are detected early so that the user knows which plug-in to update if incompatibilities arise.
+
 ## Contact
 
 If you have questions, bug reports, suggestions, etc. the author can be contacted at <peter@peterodding.com>. The latest version is available at <http://peterodding.com/code/vim/misc> and <http://github.com/xolox/vim-misc>.

compat.vim

@@ -0,0 +1,23 @@
+" Vim auto-load script
+" Author: Peter Odding <peter@peterodding.com>
+" Last Change: April 20, 2013
+" URL: http://peterodding.com/code/vim/misc/
+
+" The following integer will be bumped whenever a change in the miscellaneous
+" scripts breaks backwards compatibility. This enables my Vim plug-ins to fail
+" early when they detect an incompatible version, instead of breaking at the
+" worst possible moments :-).
+let g:xolox#misc#compat#version = 1
+
+" Remember the directory where the miscellaneous scripts are loaded from
+" so the user knows which plug-in to update if incompatibilities arise.
+let s:misc_directory = fnamemodify(expand('<sfile>'), ':p:h')
+
+function! xolox#misc#compat#check(plugin_name, required_version)
+  if a:required_version != g:xolox#misc#compat#version
+    let msg = "The %s plug-in requires version %i of the miscellaneous scripts, however version %i was loaded from %s!"
+    throw printf(msg, a:plugin_name, a:required_version, g:xolox#misc#compat#version, s:misc_directory)
+  endif
+endfunction
+
+" vim: ts=2 sw=2 et