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

Proposed by Martin Pool on 2009-06-10
Status: Merged
Merged at revision: not available
Proposed branch: lp:~mbp/bzr/doc-cleanup
Merge into: lp:~bzr/bzr/trunk-old
Diff against target: 159 lines
To merge this branch: bzr merge lp:~mbp/bzr/doc-cleanup
Reviewer Review Type Date Requested Status
John A Meinel Approve on 2009-06-10
Robert Collins (community) 2009-06-10 Approve on 2009-06-10
Review via email: mp+7265@code.launchpad.net
To post a comment you must log in.
Martin Pool (mbp) wrote :

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) wrote :

 review +1

review: Approve
lp:~mbp/bzr/doc-cleanup updated on 2009-06-10
4425. By Canonical.com Patch Queue Manager <email address hidden> on 2009-06-10

(tanner) Merge release 1.15.1 back to trunk

4426. By Canonical.com Patch Queue Manager <email address hidden> on 2009-06-10

(mbp) Trim some outdated performance drive documentation,
 and the performance.png graph

John A Meinel (jameinel) wrote :

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
lp:~mbp/bzr/doc-cleanup updated on 2009-06-10
4427. By Canonical.com Patch Queue Manager <email address hidden> on 2009-06-10

(bialix) Start Russian translation

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'Makefile'
2--- Makefile 2009-06-10 03:56:49 +0000
3+++ Makefile 2009-06-10 09:35:31 +0000
4@@ -120,7 +120,6 @@
5 doc/developers/initial-push-pull.txt \
6 doc/developers/merge-scaling.txt \
7 doc/developers/missing.txt \
8- doc/developers/performance-contributing.txt \
9 doc/developers/performance-roadmap-rationale.txt \
10 doc/developers/performance-use-case-analysis.txt \
11 doc/developers/planned-change-integration.txt \
12@@ -189,11 +188,13 @@
13 $(PYTHON) generate_docs.py -o $@ man
14
15 # build a png of our performance task list
16+#
17+# this is no longer built by default; you can build it if you want to look at it
18 doc/developers/performance.png: doc/developers/performance.dot
19 @echo Generating $@
20 @dot -Tpng $< -o$@ || echo "Dot not installed; skipping generation of $@"
21
22-derived_web_docs = $(htm_files) $(dev_htm_files) doc/developers/performance.png
23+derived_web_docs = $(htm_files) $(dev_htm_files)
24 WEB_DOCS = $(derived_web_docs) $(non_txt_files)
25 ALL_DOCS = $(derived_web_docs) $(MAN_PAGES)
26
27
28=== removed file 'doc/developers/performance-contributing.txt'
29--- doc/developers/performance-contributing.txt 2009-03-25 15:45:02 +0000
30+++ doc/developers/performance-contributing.txt 1970-01-01 00:00:00 +0000
31@@ -1,60 +0,0 @@
32-Contributing to the performance drive
33-=====================================
34-
35-.. contents:: :local:
36-
37-What needs doing?
38------------------
39-
40-There is plenty of code to write. Testers are always welcome for experimental
41-changes. In general, from the `Performance Tasks`_ graph, pick a BLUE node that has nothing
42-pointing at it that is also BLUE, and start working on that.
43-
44-Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
45-flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
46-to the bzr log file for every method call which triggers a slow or non-scalable
47-part of the bzr library. So checking that a given command with ``-Devil`` has
48-no backtraces logged to the log file is a good way to find problem function
49-calls that might be nested deep in the code base.
50-
51-Status
52-------
53-
54-The performance drive is well under way. At the moment we are finalising the
55-analysis documents from the sprint at London. If you were not at that sprint,
56-please read the analysis documents - consider them living documents much like
57-code, to be patched and corrected.
58-
59-If you were at the London performance sprint, please help finish documenting
60-the core command analysis work. The core commands that have not been analysed
61-are listed in `Performance Tasks`_ as the BLUE nodes. For quick reference:
62-
63-* status
64-* log
65-* diff
66-* uncommit
67-* missing
68-* update
69-* cbranch
70-
71-Once a given command has had its analysis created, the bottleneck of 'folk who
72-attended London' is removed. The next task is in general the creation of a
73-targeted API stack for that command. This API stack is done by starting with
74-the cmd object in ``builtins.py`` and cleaning up the code so that the API used
75-there is one which allows an implementation matching the analysis document.
76-This then gets repeated, iteratively, on each of the called API's, until all
77-the current slow code is cleanly abstracted behind the ``Tree``, ``Branch`` and
78-``Repository`` API's.
79-
80-Resources
81----------
82-
83-The usual resources for contributing to bzr - the mailing list, wiki, bug
84-tracker and IRC channels are documented in the `Bazaar Developer Guide`_. Additionally
85-there are members of the project focusing on performance at the moment who are
86-willing to mentor contributors on performance issues. Just send a mail to the
87-list asking for mentoring on the step of the performance plan you want to help
88-with.
89-
90-.. _`Bazaar Developer Guide`: ../en/developer-guide/HACKING.html
91-.. _`Performance Tasks`: performance.png
92
93=== modified file 'doc/developers/performance-roadmap.txt'
94--- doc/developers/performance-roadmap.txt 2007-09-03 09:10:13 +0000
95+++ doc/developers/performance-roadmap.txt 2009-06-10 09:35:31 +0000
96@@ -18,8 +18,6 @@
97
98 .. include:: planned-performance-changes.txt
99
100-.. include:: performance-contributing.txt
101-
102 .. include:: planned-change-integration.txt
103
104 Analysis of use cases
105
106=== modified file 'doc/developers/planned-change-integration.txt'
107--- doc/developers/planned-change-integration.txt 2009-03-20 02:25:19 +0000
108+++ doc/developers/planned-change-integration.txt 2009-06-10 09:35:31 +0000
109@@ -11,14 +11,16 @@
110 integrate because we will often need to alter apis throughout the code base to
111 expose the increased or reduced model of the preferred disk format.
112
113-`Performance Tasks`_, which is generated from the Graphviz "dot" file ``performance.dot``, graphs out the dependencies to let us make
114-accurate assessments of the changes needed in terms of code and API, hopefully
115-minimising the number of different integration steps we have to take, while
116-giving us a broad surface area for development. It's based on a summary in the
117-next section of this document of the planned changes with their expected
118-collaborators and dependencies. Where a command is listed, the expectation is
119-that all uses of that command - local, remote, dumb transport and smart
120-transport are being addressed together.
121+You can generate a graph ``performance.png`` in the source tree from
122+Graphviz "dot" file ``performance.dot``. This graphs out the dependencies
123+to let us make accurate assessments of the changes needed in terms of code
124+and API, hopefully minimising the number of different integration steps we
125+have to take, while giving us a broad surface area for development. It's
126+based on a summary in the next section of this document of the planned
127+changes with their expected collaborators and dependencies. Where a
128+command is listed, the expectation is that all uses of that command -
129+local, remote, dumb transport and smart transport are being addressed
130+together.
131
132
133 The following provides a summary of the planned changes and their expected
134@@ -139,5 +141,3 @@
135 data, making only explicit uses of it visible, and isolating the impact of
136 removing it : allowing us to experiment sensibly. This covers both dropping
137 the per-file merge graph and the hash-based-names proposals.
138-
139-.. _`Performance Tasks`: performance.png
140
141=== modified file 'doc/en/developer-guide/HACKING.txt'
142--- doc/en/developer-guide/HACKING.txt 2009-05-05 07:17:43 +0000
143+++ doc/en/developer-guide/HACKING.txt 2009-06-10 09:35:31 +0000
144@@ -46,6 +46,15 @@
145 If nothing else, perhaps you'll find inspiration in how other developers
146 have solved their challenges.
147
148+Finding Something To Do
149+=======================
150+
151+Ad-hoc performance work can also be done. One useful tool is the 'evil' debug
152+flag. For instance running ``bzr -Devil commit -m "test"`` will log a backtrace
153+to the bzr log file for every method call which triggers a slow or non-scalable
154+part of the bzr library. So checking that a given command with ``-Devil`` has
155+no backtraces logged to the log file is a good way to find problem function
156+calls that might be nested deep in the code base.
157
158 Planning and Discussing Changes
159 ===============================