Rev 3905: Improved help on storage formats (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Mon Dec 15 05:20:46 GMT 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3905
revision-id: pqm at pqm.ubuntu.com-20081215052042-a9ttz3b70lsuie6q
parent: pqm at pqm.ubuntu.com-20081213000403-r1acnqhux25xhil1
parent: ian.clatworthy at canonical.com-20081215043710-ybhxvqjeir13k5ht
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Mon 2008-12-15 05:20:42 +0000
message:
Improved help on storage formats (Ian Clatworthy)
modified:
Makefile Makefile-20050805140406-d96e3498bb61c5bb
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
bzrlib/tests/test_bzrdir.py test_bzrdir.py-20060131065654-deba40eef51cf220
------------------------------------------------------------
revno: 3904.1.1
revision-id: ian.clatworthy at canonical.com-20081215043710-ybhxvqjeir13k5ht
parent: pqm at pqm.ubuntu.com-20081213000403-r1acnqhux25xhil1
parent: ian.clatworthy at canonical.com-20081215043337-76fij4vq83wiz7bk
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: ianc-integration
timestamp: Mon 2008-12-15 14:37:10 +1000
message:
Improved help on storage formats (Ian Clatworthy)
modified:
Makefile Makefile-20050805140406-d96e3498bb61c5bb
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
bzrlib/tests/test_bzrdir.py test_bzrdir.py-20060131065654-deba40eef51cf220
------------------------------------------------------------
revno: 3892.1.6
revision-id: ian.clatworthy at canonical.com-20081215043337-76fij4vq83wiz7bk
parent: ian.clatworthy at canonical.com-20081212101233-8rhmovlk8lbrkpb2
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.help-formats
timestamp: Mon 2008-12-15 14:33:37 +1000
message:
include feedback from poolie
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
------------------------------------------------------------
revno: 3892.1.5
revision-id: ian.clatworthy at canonical.com-20081212101233-8rhmovlk8lbrkpb2
parent: ian.clatworthy at canonical.com-20081212100907-r8fd2pp0isxwbs3h
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.help-formats
timestamp: Fri 2008-12-12 20:12:33 +1000
message:
minor tweak to rich-root explanation
modified:
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
------------------------------------------------------------
revno: 3892.1.4
revision-id: ian.clatworthy at canonical.com-20081212100907-r8fd2pp0isxwbs3h
parent: ian.clatworthy at canonical.com-20081212092859-ih3z3on0tpa7mvpy
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.help-formats
timestamp: Fri 2008-12-12 20:09:07 +1000
message:
rich-root explanation and improved help for 1.6 and 1.9 formats
modified:
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
------------------------------------------------------------
revno: 3892.1.3
revision-id: ian.clatworthy at canonical.com-20081212092859-ih3z3on0tpa7mvpy
parent: ian.clatworthy at canonical.com-20081212083336-dhlf1z536kdzh6zk
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.help-formats
timestamp: Fri 2008-12-12 19:28:59 +1000
message:
tweak test suite to support the split up formats topic
modified:
bzrlib/tests/test_bzrdir.py test_bzrdir.py-20060131065654-deba40eef51cf220
------------------------------------------------------------
revno: 3892.1.2
revision-id: ian.clatworthy at canonical.com-20081212083336-dhlf1z536kdzh6zk
parent: ian.clatworthy at canonical.com-20081211075601-lzvvi0be70chcudx
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.help-formats
timestamp: Fri 2008-12-12 18:33:36 +1000
message:
split formats topic into multiple topics
modified:
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
------------------------------------------------------------
revno: 3892.1.1
revision-id: ian.clatworthy at canonical.com-20081211075601-lzvvi0be70chcudx
parent: pqm at pqm.ubuntu.com-20081210210638-e569azc2bomqq5qx
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.help-formats
timestamp: Thu 2008-12-11 17:56:01 +1000
message:
improve help on storage formats
modified:
Makefile Makefile-20050805140406-d96e3498bb61c5bb
NEWS NEWS-20050323055033-4e00b5db738777ff
bzrlib/bzrdir.py bzrdir.py-20060131065624-156dfea39c4387cb
=== modified file 'Makefile'
--- a/Makefile 2008-12-12 00:37:26 +0000
+++ b/Makefile 2008-12-15 04:37:10 +0000
@@ -124,6 +124,7 @@
bzrlib/bundle/commands.py \
bzrlib/conflicts.py \
bzrlib/help_topics/__init__.py \
+ bzrlib/bzrdir.py \
bzrlib/sign_my_commits.py \
bzrlib/bugtracker.py \
generate_docs.py \
=== modified file 'NEWS'
--- a/NEWS 2008-12-12 23:27:07 +0000
+++ b/NEWS 2008-12-15 04:37:10 +0000
@@ -10,6 +10,9 @@
CHANGES:
+ * Formats using Knit-based repository formats are now explicitly
+ marked as deprecated. (Ian Clatworthy)
+
* ``LRUCache(after_cleanup_size)`` was renamed to
``after_cleanup_count`` and the old name deprecated. The new name is
used for clarity, and to avoid confusion with
@@ -68,6 +71,11 @@
DOCUMENTATION:
+ * Improved the formats help topic to explain why multiple formats
+ exist and to provide guidelines in selecting one. Introduced
+ two new supporting help topics: current-formats and other-formats.
+ (Ian Clatworthy)
+
API CHANGES:
* ``node_distances`` and ``select_farthest`` can no longer be imported
=== modified file 'bzrlib/bzrdir.py'
--- a/bzrlib/bzrdir.py 2008-12-12 13:09:26 +0000
+++ b/bzrlib/bzrdir.py 2008-12-15 04:37:10 +0000
@@ -2678,6 +2678,7 @@
def __init__(self):
"""Create a BzrDirFormatRegistry."""
self._aliases = set()
+ self._registration_order = list()
super(BzrDirFormatRegistry, self).__init__()
def aliases(self):
@@ -2745,6 +2746,7 @@
BzrDirFormatInfo(native, deprecated, hidden, experimental))
if alias:
self._aliases.add(key)
+ self._registration_order.append(key)
def register_lazy(self, key, module_name, member_name, help, native=True,
deprecated=False, hidden=False, experimental=False, alias=False):
@@ -2752,6 +2754,7 @@
help, BzrDirFormatInfo(native, deprecated, hidden, experimental))
if alias:
self._aliases.add(key)
+ self._registration_order.append(key)
def set_default(self, key):
"""Set the 'default' key to be a clone of the supplied key.
@@ -2777,15 +2780,11 @@
return self.get(key)()
def help_topic(self, topic):
- output = textwrap.dedent("""\
- These formats can be used for creating branches, working trees, and
- repositories.
-
- """)
+ output = ""
default_realkey = None
default_help = self.get_help('default')
help_pairs = []
- for key in self.keys():
+ for key in self._registration_order:
if key == 'default':
continue
help = self.get_help(key)
@@ -2815,18 +2814,31 @@
experimental_pairs.append((key, help))
else:
output += wrapped(key, help, info)
+ output += "\nSee ``bzr help formats`` for more about storage formats."
+ other_output = ""
if len(experimental_pairs) > 0:
- output += "Experimental formats are shown below.\n\n"
+ other_output += "Experimental formats are shown below.\n\n"
for key, help in experimental_pairs:
info = self.get_info(key)
- output += wrapped(key, help, info)
+ other_output += wrapped(key, help, info)
+ else:
+ other_output += \
+ "No experimental formats are available.\n\n"
if len(deprecated_pairs) > 0:
- output += "Deprecated formats are shown below.\n\n"
+ other_output += "\nDeprecated formats are shown below.\n\n"
for key, help in deprecated_pairs:
info = self.get_info(key)
- output += wrapped(key, help, info)
+ other_output += wrapped(key, help, info)
+ else:
+ other_output += \
+ "\nNo deprecated formats are available.\n\n"
+ other_output += \
+ "\nSee ``bzr help formats`` for more about storage formats."
- return output
+ if topic == 'other-formats':
+ return other_output
+ else:
+ return output
class RepositoryAcquisitionPolicy(object):
@@ -2961,22 +2973,26 @@
return self._repository
+# Please register new formats after old formats so that formats
+# appear in chronological order and format descriptions can build
+# on previous ones.
format_registry = BzrDirFormatRegistry()
format_registry.register('weave', BzrDirFormat6,
'Pre-0.8 format. Slower than knit and does not'
' support checkouts or shared repositories.',
deprecated=True)
-format_registry.register_metadir('knit',
- 'bzrlib.repofmt.knitrepo.RepositoryFormatKnit1',
- 'Format using knits. Recommended for interoperation with bzr <= 0.14.',
- branch_format='bzrlib.branch.BzrBranchFormat5',
- tree_format='bzrlib.workingtree.WorkingTreeFormat3')
format_registry.register_metadir('metaweave',
'bzrlib.repofmt.weaverepo.RepositoryFormat7',
'Transitional format in 0.8. Slower than knit.',
branch_format='bzrlib.branch.BzrBranchFormat5',
tree_format='bzrlib.workingtree.WorkingTreeFormat3',
deprecated=True)
+format_registry.register_metadir('knit',
+ 'bzrlib.repofmt.knitrepo.RepositoryFormatKnit1',
+ 'Format using knits. Recommended for interoperation with bzr <= 0.14.',
+ branch_format='bzrlib.branch.BzrBranchFormat5',
+ tree_format='bzrlib.workingtree.WorkingTreeFormat3',
+ deprecated=True)
format_registry.register_metadir('dirstate',
'bzrlib.repofmt.knitrepo.RepositoryFormatKnit1',
help='New in 0.15: Fast local operations. Compatible with bzr 0.8 and '
@@ -2985,7 +3001,7 @@
# this uses bzrlib.workingtree.WorkingTreeFormat4 because importing
# directly from workingtree_4 triggers a circular import.
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
- )
+ deprecated=True)
format_registry.register_metadir('dirstate-tags',
'bzrlib.repofmt.knitrepo.RepositoryFormatKnit1',
help='New in 0.15: Fast local operations and improved scaling for '
@@ -2993,14 +3009,14 @@
' Incompatible with bzr < 0.15.',
branch_format='bzrlib.branch.BzrBranchFormat6',
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
- )
+ deprecated=True)
format_registry.register_metadir('rich-root',
'bzrlib.repofmt.knitrepo.RepositoryFormatKnit4',
help='New in 1.0. Better handling of tree roots. Incompatible with'
- ' bzr < 1.0',
+ ' bzr < 1.0.',
branch_format='bzrlib.branch.BzrBranchFormat6',
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
- )
+ deprecated=True)
format_registry.register_metadir('dirstate-with-subtree',
'bzrlib.repofmt.knitrepo.RepositoryFormatKnit3',
help='New in 0.15: Fast local operations and improved scaling for '
@@ -3037,35 +3053,38 @@
)
format_registry.register_metadir('rich-root-pack',
'bzrlib.repofmt.pack_repo.RepositoryFormatKnitPack4',
- help='New in 1.0: Pack-based format with data compatible with '
- 'rich-root format repositories. Incompatible with'
- ' bzr < 1.0',
+ help='New in 1.0: A variant of pack-0.92 that supports rich-root data '
+ '(needed for bzr-svn).',
branch_format='bzrlib.branch.BzrBranchFormat6',
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
)
format_registry.register_metadir('1.6',
'bzrlib.repofmt.pack_repo.RepositoryFormatKnitPack5',
- help='A branch and pack based repository that supports stacking. ',
+ help='A format that allows a branch to indicate that there is another '
+ '(stacked) repository that should be used to access data that is '
+ 'not present locally.',
branch_format='bzrlib.branch.BzrBranchFormat7',
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
)
format_registry.register_metadir('1.6.1-rich-root',
'bzrlib.repofmt.pack_repo.RepositoryFormatKnitPack5RichRoot',
- help='A branch and pack based repository that supports stacking '
- 'and rich root data (needed for bzr-svn). ',
+ help='A variant of 1.6 that supports rich-root data '
+ '(needed for bzr-svn).',
branch_format='bzrlib.branch.BzrBranchFormat7',
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
)
format_registry.register_metadir('1.9',
'bzrlib.repofmt.pack_repo.RepositoryFormatKnitPack6',
- help='A branch and pack based repository that uses btree indexes. ',
+ help='A repository format using B+tree indexes. These indexes '
+ 'are smaller in size, have smarter caching and provide faster '
+ 'performance for most operations.',
branch_format='bzrlib.branch.BzrBranchFormat7',
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
)
format_registry.register_metadir('1.9-rich-root',
'bzrlib.repofmt.pack_repo.RepositoryFormatKnitPack6RichRoot',
- help='A branch and pack based repository that uses btree indexes '
- 'and rich root data (needed for bzr-svn). ',
+ help='A variant of 1.9 that supports rich-root data '
+ '(needed for bzr-svn).',
branch_format='bzrlib.branch.BzrBranchFormat7',
tree_format='bzrlib.workingtree.WorkingTreeFormat4',
)
=== modified file 'bzrlib/help_topics/__init__.py'
--- a/bzrlib/help_topics/__init__.py 2008-11-25 16:58:29 +0000
+++ b/bzrlib/help_topics/__init__.py 2008-12-15 04:33:37 +0000
@@ -649,15 +649,71 @@
"""
+_storage_formats = \
+"""Storage Formats
+
+To ensure that older clients do not access data incorrectly,
+Bazaar's policy is to introduce a new storage format whenever
+new features requiring new metadata are added. New storage
+formats may also be introduced to improve performance and
+scalability.
+
+Use the following guidelines to select a format (stopping
+as soon as a condition is true):
+
+* If you are working on an existing project, use whatever
+ format that project is using. (Bazaar will do this for you
+ by default).
+
+* If you are using bzr-svn to interoperate with a Subversion
+ repository, use 1.9-rich-root.
+
+* If you are working on a project with big trees (5000+ paths)
+ or deep history (5000+ revisions), use 1.9.
+
+* Otherwise, use the default format - it is good enough for
+ most projects.
+
+If some of your developers are unable to use the most recent
+version of Bazaar (due to distro package availability say), be
+sure to adjust the guidelines above accordingly. For example,
+you may need to select 1.6 instead of 1.9 if your project has
+standardized on Bazaar 1.7.
+
+Note: Many of the currently supported formats have two variants:
+a plain one and a rich-root one. The latter include an additional
+field about the root of the tree. There is no performance cost
+for using a rich-root format but you cannot easily merge changes
+from a rich-root format into a plain format. As a consequence,
+moving a project to a rich-root format takes some co-ordination
+in that all contributors need to upgrade their repositories
+around the same time. (It is for this reason that we have delayed
+making a rich-root format the default so far, though we will do
+so at some appropriate time in the future.)
+
+See ``bzr help current-formats`` for the complete list of
+currently supported formats. See ``bzr help other-formats`` for
+descriptions of any available experimental and deprecated formats.
+"""
+
+
# Register help topics
topic_registry.register("revisionspec", _help_on_revisionspec,
"Explain how to use --revision")
topic_registry.register('basic', _basic_help, "Basic commands", SECT_HIDDEN)
topic_registry.register('topics', _help_on_topics, "Topics list", SECT_HIDDEN)
-def get_format_topic(topic):
- from bzrlib import bzrdir
- return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
-topic_registry.register('formats', get_format_topic, 'Directory formats')
+def get_current_formats_topic(topic):
+ from bzrlib import bzrdir
+ return "Current Storage Formats\n\n" + \
+ bzrdir.format_registry.help_topic(topic)
+def get_other_formats_topic(topic):
+ from bzrlib import bzrdir
+ return "Other Storage Formats\n\n" + \
+ bzrdir.format_registry.help_topic(topic)
+topic_registry.register('current-formats', get_current_formats_topic,
+ 'Current storage formats')
+topic_registry.register('other-formats', get_other_formats_topic,
+ 'Experimental and deprecated storage formats')
topic_registry.register('standard-options', _standard_options,
'Options that can be used with any command')
topic_registry.register('global-options', _global_options,
@@ -695,6 +751,9 @@
'Information on what a branch is', SECT_CONCEPT)
topic_registry.register('checkouts', _checkouts,
'Information on what a checkout is', SECT_CONCEPT)
+topic_registry.register('formats', _storage_formats,
+ 'Information on choosing a storage format',
+ SECT_CONCEPT)
topic_registry.register('patterns', _load_from_file,
'Information on the pattern syntax',
SECT_CONCEPT)
=== modified file 'bzrlib/tests/test_bzrdir.py'
--- a/bzrlib/tests/test_bzrdir.py 2008-12-03 16:40:38 +0000
+++ b/bzrlib/tests/test_bzrdir.py 2008-12-15 04:37:10 +0000
@@ -140,12 +140,15 @@
def test_help_topic(self):
topics = help_topics.HelpTopicRegistry()
- topics.register('formats', self.make_format_registry().help_topic,
- 'Directory formats')
- topic = topics.get_detail('formats')
- new, rest = topic.split('Experimental formats')
+ registry = self.make_format_registry()
+ topics.register('current-formats', registry.help_topic,
+ 'Current formats')
+ topics.register('other-formats', registry.help_topic,
+ 'Other formats')
+ new = topics.get_detail('current-formats')
+ rest = topics.get_detail('other-formats')
experimental, deprecated = rest.split('Deprecated formats')
- self.assertContainsRe(new, 'These formats can be used')
+ self.assertContainsRe(new, 'bzr help formats')
self.assertContainsRe(new,
':knit:\n \(native\) \(default\) Format using knits\n')
self.assertContainsRe(experimental,
More information about the bazaar-commits
mailing list