Rev 51: Clarify the know problems about compatibility. in file:///home/vila/src/bzr/devnotes/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/devnotes/

------------------------------------------------------------
revno: 51
revision-id: v.ladeuil+lp at free.fr-20110513092452-4ettxgxz575cnkfx
parent: v.ladeuil+lp at free.fr-20110512150748-uur855snm98antg2
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: devnotes
timestamp: Fri 2011-05-13 11:24:52 +0200
message:
  Clarify the know problems about compatibility.
-------------- next part --------------
=== modified file 'configuration.txt'
--- a/configuration.txt	2011-05-12 15:07:48 +0000
+++ b/configuration.txt	2011-05-13 09:24:52 +0000
@@ -334,7 +334,7 @@
 * a local path.
 
 Note that for both the provided context and the section names, if an URL uses
-a ``file:///``form, it is converted to a local path.
+a ``file:///`` form, it is converted to a local path.
 
 The sections names can use globs for each path component
 (i.e. ``/dir/*/subdir`` is allowed but ``/dir/\*\*/subdir`` will match
@@ -526,23 +526,59 @@
 Compatibility
 =============
 
-* The ``DEFAULT`` section in bazaar.conf should still be recognized but
-  won't be mandatory anymore.
-
-* Other sections in the ``bazaar.conf`` configuration file are still
-  supported but their use is discouraged and we may deprecate them in the
-  future. Plugin authors are encouraged to migrate to the new name space
-  scheme by prefixing their options with their plugin name.
+There are ways to keep the same files while ensuring compatibility via various
+tricks but there are cases where using new files to replace the old ones is
+definitely easier:
+
+* no need to ensure that the new files are correctly handled by old bzr
+  versions,
+
+* making it clear for users that there is a switch and let them migrate at
+  their own pace.
+
+The known cases so far are described below.
+
+Obvious at this point:
+
+* [DEFAULT] section is replaced by a no-name section. This is trival to
+  automate by copying the section content into the ``defaults`` no-name
+  section. On the other hand, we may want to rename the options too and trying
+  to obey both option names in the same file is harder than accepting one name
+  is the new file while accepting the old name if the old file is still
+  present.
 
 * Option policies should be deprecated:
 
   * The ``norecurse`` policy is useless, all options are recursive by
     default. If specific values are needed for specific paths, they can just
-    be defined as such.
+    be defined as such (in the appropriate sections or files).
 
   * The ``appendpath`` policy should be implemented via interpolation and a
     ``relpath`` option provided by the configuration framework.
 
+* Section order in ``locations.conf`` has issues which make a migration to a
+  different way to organize the sections (hence the file content) far easier
+  with a new file.
+
+* ``locations.conf`` is really for overrides but many users have been using it
+  to provide defaults. There is no way to know if the whole content has been
+  used for defaults or overrides or a mix of both. So there is now way to
+  migrate this automatically.
+
+Unclear at this point:
+
+* [BOOKMARKS] section can be replaced by ``bookmarks.xxx`` options (the
+  bookmarks plugins already uses ``bookmarks_xxx`` in branch.conf since no
+  sections were supported there). This could be automated by creating the
+  corresponding options ?
+
+* [ALIASES] section can be replaced by corresponding bzr.alias.xxx
+  options. This could be automated by creating the corresponding options ?
+
+* I don't know about other sections, feedback welcome. Plugin authors are
+  encouraged to migrate to the new name space scheme by prefixing their
+  options with their plugin name.
+
 Notes
 =====