X-Git-Url: http://git.indexdata.com/?p=mkws-moved-to-github.git;a=blobdiff_plain;f=doc%2Fmkws-manual.markdown;fp=doc%2Fmkws-manual.markdown;h=8fd07e36cb48c2ba20ec37e6affb63f66772d140;hp=88738ab8ca9d2c9904ee2993f84c3d99bf3ba0eb;hb=245062e3f211edfde39f3dc3ca026b93f2bc53fb;hpb=c43a5abcebeca92a2c6ec1065b9170d174b40464

diff --git a/doc/mkws-manual.markdown b/doc/mkws-manual.markdown
index 88738ab..8fd07e3 100644
--- a/doc/mkws-manual.markdown
+++ b/doc/mkws-manual.markdown
@@ -1266,18 +1266,26 @@ more instances; a trailing `?` indicates zero or one instance.
 Appendix: compatibility roadmap
 ===============================
 
-FIXME: more to write here.
-
-
-Old and new-style class-names
------------------------------
-
-**NOTE.** Versions of MKWS before v1.0 used camel-case class-names:
-without hyphens and with second and subsequent words capitalised. So
-instead of `mkws-search`, it used to be `mkwsSearch`. And the classes
-used to specify team names used an `mkwsTeam_` prefix (with an
-underscore). So instead of `mkws-team-foo`, it used to be
-`mkwsTeam_foo`.
+Wherever possible, we ensure that all functional changes in MKWS are
+backwards-compatible, so that applications written against old versions of the
+toolkit will continue to work when running against newer versions.
+
+However, a few aspects of functionality unavoidably change in backwards
+incompatible ways. We ensure that **this only happens with new major
+versions** -- so it should _always_ be safe to upgrade to a new minor version.
+As an aid to porting old applications, we here note the specific
+backwards-incompatible changes in the various major releases, and those
+planned for future major releases.
+
+
+Major version 1.x
+-----------------
+
+Versions of MKWS before v1.0 (including the only prior release, v0.9.1) used
+camel-case class-names: without hyphens and with second and subsequent words
+capitalised. So instead of `mkws-search`, it used to be `mkwsSearch`. And the
+classes used to specify team names used an `mkwsTeam_` prefix (with an
+underscore). So instead of `mkws-team-foo`, it used to be `mkwsTeam_foo`.
 
 The 1.x series of MKWS releases recognise these old-style class-names
 as well as the canonical ones, as a facility for backwards