Rev 2484: Add the performance roadmap rationale. in file:///home/robertc/source/baz/roadmap/

Robert Collins robertc at robertcollins.net
Mon May 7 18:49:36 BST 2007 

At file:///home/robertc/source/baz/roadmap/

------------------------------------------------------------
revno: 2484
revision-id: robertc at robertcollins.net-20070507174930-gksqv90l5emjrcyq
parent: robertc at robertcollins.net-20070507170412-91hbpdaem8bvel4s
committer: Robert Collins <robertc at robertcollins.net>
branch nick: roadmap
timestamp: Tue 2007-05-08 03:49:30 +1000
message:
  Add the performance roadmap rationale.
added:
  doc/developers/performance-roadmap-rationale.txt performanceroadmapra-20070507174912-mwv3xv517cs4sisd-1
  doc/developers/performance-roadmap.txt performanceroadmap.t-20070507174912-mwv3xv517cs4sisd-2
modified:
  Makefile                       Makefile-20050805140406-d96e3498bb61c5bb
  doc/shared_repository_layouts.txt shared_repository_la-20070502152030-bagewuqs18ns24o7-1
=== added file 'doc/developers/performance-roadmap-rationale.txt'
--- a/doc/developers/performance-roadmap-rationale.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/performance-roadmap-rationale.txt	2007-05-07 17:49:30 +0000
@@ -0,0 +1,116 @@
+What should be in the roadmap?
+------------------------------
+
+A good roadmap provides a place for contributors to look for tasks, it
+provides users with a sense of when we will fix things that are
+affecting them, and it also allows us all to agree about where we are
+headed. So the roadmap should contain enough things to let all this
+happen.
+
+I think that it needs to contain the analysis work which is required, a
+list of the use cases to be optimised, the disk changes required, and
+the broad sense of the api changes required. It also needs to list the
+inter-dependencies between these things: we should aim for a large
+surface area of 'ready to be worked on' items, that makes it easy to
+improve performance without having to work in lockstep with other
+developers.
+
+Clearly the analysis step is an immediate bottleneck - we cannot tell if
+an optimisation for use case A is a pessimism for use case B until we
+have analysed both A and B. I propose that we complete the analysis of
+say a dozen core use cases end to end during the upcoming sprint in
+London. We should then be able to fork() for much of the detailed design
+work and regroup with disk and api changes shortly thereafter.
+
+I suspect that clarity of layering will make a big difference to
+developer parallelism, so another proposal I have is for us to look at
+the APIs for Branch and Repository in London in the light of what we
+have learnt over the last years.
+
+What should the final system look like, how is it different to what we have today?
+----------------------------------------------------------------------------------
+
+One of the things I like the most about bzr is its rich library API, and
+I've heard this from numerous other folk. So anything that will remove
+that should be considered a last resort.
+
+Similarly our relatively excellent cross platform support is critical
+for projects that are themselves cross platform, and thats a
+considerable number these days.
+
+And of course, our focus on doing the right thing is what differentiates
+us from some of the other VCS's, so we should be focusing on doing the
+right thing quickly :).
+
+What we have today though has grown organically in response to us
+identifying bottlenecks over several iterations of back end storage,
+branch metadata and the local tree representation. I think we are
+largely past that and able to describe the ideal characteristics of the
+major actors in the system - primarily Tree, Branch, Repository - based
+on what we have learnt.
+
+What use cases should be covered?
+---------------------------------
+
+My list of use cases is probably not complete - its just the ones I
+happen to see a lot :). I think each should be analysed comprehensively
+so we dont need to say 'push over the network' - its implied in the
+scaling analysis that both semantic and file operation latency will be
+considered.
+
+These use cases are ordered by roughly the ease of benchmarking, and the
+frequency of use. This ordering is so that when people are comparing bzr
+they are going to get use cases we have optimised; and so that as we
+speed things up our existing users will have the things they do the most
+optimised.
+
+ * status tree
+ * status subtree
+ * commit
+ * commit to a bound branch
+ * incremental push/pull
+ * log
+ * log path
+ * add
+ * initial push or pull [both to a new repo and an existing repo with
+   different data in it]
+ * diff tree
+ * diff subtree
+
+ * revert tree
+ * revert subtree
+ * merge from a branch
+ * merge from a bundle
+ * annotate
+ * create a bundle against a branch
+ * uncommit
+ * missing
+ * update
+ * cbranch
+
+how is development on the roadmap coordinated?
+----------------------------------------------
+
+I think we should hold regular get-togethers (on IRC) to coordinate on
+our progress, because this is a big task and its a lot easier to start
+helping out some area which is having trouble if we have kept in contact
+about each areas progress. This might be weekly or fortnightly or some
+such.
+
+we need a shared space to record the results of the analysis and the
+roadmap as we go forward. Given that we'll need to update these as new
+features are considered, I propose that we use doc/design as a working
+space, and as we analyse use cases we include them in there - including
+the normal review process for each patch. We also need documentation
+about doing performance tuning - not the minutiae, though that is
+needed, but about how to effective choose things to optimise which will
+give the best return on time spent - that is what the roadmap should
+help with, but this looks to be a large project and an overview will be
+of great assistance I think. We want to help everyone that wishes to
+contribute to performance to do so effectively.
+
+Finally, its important to note that coding is not the only contribution
+- testing, giving feedback on current performance, helping with the
+analysis are all extremely important tasks too and we probably want to
+have clear markers of where that should be done to encourage such
+contributions.

=== added file 'doc/developers/performance-roadmap.txt'
--- a/doc/developers/performance-roadmap.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/performance-roadmap.txt	2007-05-07 17:49:30 +0000
@@ -0,0 +1,10 @@
+==========================
+Bazaar Performance Roadmap
+==========================
+
+About the performance roadmap
+#############################
+
+.. include:: performance-roadmap-rationale.txt
+
+

=== modified file 'Makefile'
--- a/Makefile	2007-05-07 16:48:14 +0000
+++ b/Makefile	2007-05-07 17:49:30 +0000
@@ -75,6 +75,8 @@
 doc_dir := doc 
 txt_files := $(wildcard $(addsuffix /*.txt, $(doc_dir))) doc/bzr_man.txt
 htm_files := $(patsubst %.txt, %.htm, $(txt_files)) 
+dev_txt_files := $(wildcard $(addsuffix /*.txt, doc/developers))
+dev_htm_files := $(patsubst %.txt, %.htm, $(dev_txt_files)) 
 
 pretty-html-docs: pretty_files
 
@@ -86,8 +88,8 @@
 doc/developers/HACKING.htm: doc/developers/HACKING
 	python tools/rst2html.py --link-stylesheet --stylesheet=default.css $< $@
 
-doc/%.htm: doc/%.txt 
-	python tools/rst2html.py --link-stylesheet --stylesheet=default.css doc/$*.txt doc/$*.htm
+%.htm: %.txt
+	python tools/rst2html.py --link-stylesheet --stylesheet=default.css $< $@
 
 $(PRETTYDIR)/%.htm: pretty_docs doc/%.txt
 	python tools/rst2prettyhtml.py doc/bazaar-vcs.org.kid doc/$*.txt \
@@ -108,7 +110,7 @@
 man1/bzr.1: $(MAN_DEPENDENCIES)
 	python generate_docs.py -o $@ man
 
-ALL_DOCS = $(htm_files) $(MAN_PAGES) doc/developers/HACKING.htm
+ALL_DOCS = $(htm_files) $(MAN_PAGES) doc/developers/HACKING.htm $(dev_htm_files)
 docs: $(ALL_DOCS)
 
 copy-docs: docs

=== modified file 'doc/shared_repository_layouts.txt'
--- a/doc/shared_repository_layouts.txt	2007-05-02 15:21:16 +0000
+++ b/doc/shared_repository_layouts.txt	2007-05-07 17:49:30 +0000
@@ -126,6 +126,7 @@
     Letting you ``bzr checkout`` one project, and have it grab all the necessary
     sub-projects.
 
+.. _NestedTreeSupport: http://bazaar-vcs.org/NestedTrees
 
 
 Nested Style (``project/branch/sub-branch/``)

More information about the bazaar-commits mailing list