Merge lp:~mbp/bzr/doc-cleanup into lp:~bzr/bzr/trunk-old

[Martin Pool]

[Martin Pool (mbp)]

This stops us from building performance.png, which was identified as bloating the binary packages, and it cleans up some old developer documentation. There's more we could do to trim things that may be out of date.

[Robert Collins (lifeless)]

 review +1

review: Approve

[John A Meinel (jameinel)]

Arg... another example of:
https://bugs.edge.launchpad.net/launchpad-code/+bug/338002

Anyway, I approve of not generating the performance.png except on demand. I'll assume that all the other changes are just bug #338002

review: Approve

=== modified file 'Makefile'
--- Makefile	2009-06-10 03:56:49 +0000
+++ Makefile	2009-06-10 09:35:31 +0000
@@ -120,7 +120,6 @@
 	doc/developers/initial-push-pull.txt \
 	doc/developers/merge-scaling.txt \
 	doc/developers/missing.txt \
-	doc/developers/performance-contributing.txt \
 	doc/developers/performance-roadmap-rationale.txt \
 	doc/developers/performance-use-case-analysis.txt \
 	doc/developers/planned-change-integration.txt \
@@ -189,11 +188,13 @@
 	$(PYTHON) generate_docs.py -o $@ man
 
 # build a png of our performance task list
+# 
+# this is no longer built by default; you can build it if you want to look at it
 doc/developers/performance.png: doc/developers/performance.dot
 	@echo Generating $@
 	@dot -Tpng $< -o$@ || echo "Dot not installed; skipping generation of $@"
 
-derived_web_docs = $(htm_files) $(dev_htm_files) doc/developers/performance.png
+derived_web_docs = $(htm_files) $(dev_htm_files) 
 WEB_DOCS = $(derived_web_docs) $(non_txt_files)
 ALL_DOCS = $(derived_web_docs) $(MAN_PAGES)
 

=== removed file 'doc/developers/performance-contributing.txt'
--- doc/developers/performance-contributing.txt	2009-03-25 15:45:02 +0000
+++ doc/developers/performance-contributing.txt	1970-01-01 00:00:00 +0000
@@ -1,60 +0,0 @@
-Contributing to the performance drive
-=====================================
-
-.. contents:: :local:
-
-What needs doing?
------------------
-
-There is plenty of code to write. Testers are always welcome for experimental
-changes. In general, from the `Performance Tasks`_ graph, pick a BLUE node that has nothing
-pointing at it that is also BLUE, and start working on that.
-
-Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
-flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
-to the bzr log file for every method call which triggers a slow or non-scalable
-part of the bzr library. So checking that a given command with ``-Devil`` has
-no backtraces logged to the log file is a good way to find problem function
-calls that might be nested deep in the code base.
-
-Status
-------
-
-The performance drive is well under way. At the moment we are finalising the
-analysis documents from the sprint at London. If you were not at that sprint,
-please read the analysis documents - consider them living documents much like
-code, to be patched and corrected.
-
-If you were at the London performance sprint, please help finish documenting
-the core command analysis work. The core commands that have not been analysed
-are listed in `Performance Tasks`_ as the BLUE nodes. For quick reference:
-
-* status
-* log
-* diff
-* uncommit
-* missing
-* update
-* cbranch
-
-Once a given command has had its analysis created, the bottleneck of 'folk who
-attended London' is removed. The next task is in general the creation of a
-targeted API stack for that command. This API stack is done by starting with
-the cmd object in ``builtins.py`` and cleaning up the code so that the API used
-there is one which allows an implementation matching the analysis document.
-This then gets repeated, iteratively, on each of the called API's, until all
-the current slow code is cleanly abstracted behind the ``Tree``, ``Branch`` and
-``Repository`` API's.
-
-Resources
----------
-
-The usual resources for contributing to bzr - the mailing list, wiki, bug
-tracker and IRC channels are documented in the `Bazaar Developer Guide`_. Additionally
-there are members of the project focusing on performance at the moment who are
-willing to mentor contributors on performance issues. Just send a mail to the
-list asking for mentoring on the step of the performance plan you want to help
-with.
-
-.. _`Bazaar Developer Guide`: ../en/developer-guide/HACKING.html
-.. _`Performance Tasks`: performance.png

=== modified file 'doc/developers/performance-roadmap.txt'
--- doc/developers/performance-roadmap.txt	2007-09-03 09:10:13 +0000
+++ doc/developers/performance-roadmap.txt	2009-06-10 09:35:31 +0000
@@ -18,8 +18,6 @@
 
 .. include:: planned-performance-changes.txt
 
-.. include:: performance-contributing.txt
-
 .. include:: planned-change-integration.txt
 
 Analysis of use cases

=== modified file 'doc/developers/planned-change-integration.txt'
--- doc/developers/planned-change-integration.txt	2009-03-20 02:25:19 +0000
+++ doc/developers/planned-change-integration.txt	2009-06-10 09:35:31 +0000
@@ -11,14 +11,16 @@
 integrate because we will often need to alter apis throughout the code base to
 expose the increased or reduced model of the preferred disk format.
 
-`Performance Tasks`_, which is generated from the Graphviz "dot" file ``performance.dot``, graphs out the dependencies to let us make
-accurate assessments of the changes needed in terms of code and API, hopefully
-minimising the number of different integration steps we have to take, while
-giving us a broad surface area for development. It's based on a summary in the
-next section of this document of the planned changes with their expected
-collaborators and dependencies. Where a command is listed, the expectation is
-that all uses of that command - local, remote, dumb transport and smart
-transport are being addressed together.
+You can generate a graph ``performance.png`` in the source tree from
+Graphviz "dot" file ``performance.dot``.  This graphs out the dependencies
+to let us make accurate assessments of the changes needed in terms of code
+and API, hopefully minimising the number of different integration steps we
+have to take, while giving us a broad surface area for development. It's
+based on a summary in the next section of this document of the planned
+changes with their expected collaborators and dependencies. Where a
+command is listed, the expectation is that all uses of that command -
+local, remote, dumb transport and smart transport are being addressed
+together.
 
 
 The following provides a summary of the planned changes and their expected
@@ -139,5 +141,3 @@
    data, making only explicit uses of it visible, and isolating the impact of
    removing it : allowing us to experiment sensibly. This covers both dropping
    the per-file merge graph and the hash-based-names proposals.
-
-.. _`Performance Tasks`: performance.png

=== modified file 'doc/en/developer-guide/HACKING.txt'
--- doc/en/developer-guide/HACKING.txt	2009-05-05 07:17:43 +0000
+++ doc/en/developer-guide/HACKING.txt	2009-06-10 09:35:31 +0000
@@ -46,6 +46,15 @@
 If nothing else, perhaps you'll find inspiration in how other developers
 have solved their challenges.
 
+Finding Something To Do
+=======================
+
+Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
+flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
+to the bzr log file for every method call which triggers a slow or non-scalable
+part of the bzr library. So checking that a given command with ``-Devil`` has
+no backtraces logged to the log file is a good way to find problem function
+calls that might be nested deep in the code base.
 
 Planning and Discussing Changes
 ===============================