Rev 2512: (bialix, r=john, r=aaron) sanitize dev docs (performance-roadmap) & in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Wed Jun 6 09:37:16 BST 2007
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 2512
revision-id: pqm at pqm.ubuntu.com-20070606083714-rt2za45t9gt5nqqh
parent: pqm at pqm.ubuntu.com-20070606050006-o4yiw7jnwytgf561
parent: bialix at ukr.net-20070606075700-fefq7kluy10inv0m
committer: Canonical.com Patch Queue Manager<pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Wed 2007-06-06 09:37:14 +0100
message:
(bialix,r=john,r=aaron) sanitize dev docs (performance-roadmap) &
win32 installers improvements
renamed:
doc/developers/bundle-creation.rst => doc/developers/bundle-creation.txt bundlecreation.rst-20070527173558-rqaqxn1al7vzgcto-1
doc/developers/initial-push-pull.rst => doc/developers/initial-push-pull.txt initialpushpull.rst-20070527184539-wodba32mi5dehhct-1
doc/developers/merge-scaling.rst => doc/developers/merge-scaling.txt mergescaling.rst-20070527173558-rqaqxn1al7vzgcto-2
modified:
Makefile Makefile-20050805140406-d96e3498bb61c5bb
doc/developers/add.txt add.txt-20070515094933-xhgz3xjc7o0edok0-2
doc/developers/annotate.txt annotate.txt-20070515142136-rq51c4kqhwrjsh8k-1
doc/developers/gc.txt gc.txt-20070515102609-90x5kzjokrurfbke-1
doc/developers/incremental-push-pull.txt incrementalpushpull.-20070508045640-zneiu1yzbci574c6-1
doc/developers/performance-roadmap-rationale.txt performanceroadmapra-20070507174912-mwv3xv517cs4sisd-1
doc/developers/performance-roadmap.txt performanceroadmap.t-20070507174912-mwv3xv517cs4sisd-2
doc/developers/performance-use-case-analysis.txt performanceusecasean-20070508045640-zneiu1yzbci574c6-2
doc/developers/planned-performance-changes.txt plannedperformancech-20070604053752-bnjdhako613xfufb-1
doc/developers/revert.txt revert.txt-20070515111013-grc9hgp21zxqbwbl-1
setup.py setup.py-20050314065409-02f8a0a6e3f9bc70
doc/developers/bundle-creation.txt bundlecreation.rst-20070527173558-rqaqxn1al7vzgcto-1
doc/developers/initial-push-pull.txt initialpushpull.rst-20070527184539-wodba32mi5dehhct-1
doc/developers/merge-scaling.txt mergescaling.rst-20070527173558-rqaqxn1al7vzgcto-2
------------------------------------------------------------
revno: 2506.1.4
merged: bialix at ukr.net-20070606075700-fefq7kluy10inv0m
parent: bialix at ukr.net-20070606074514-qq7bxr0x2uj8c5c2
committer: Alexander Belchenko <bialix at ukr.net>
branch nick: installer-0.17
timestamp: Wed 2007-06-06 10:57:00 +0300
message:
pack developers docs to windows installers
------------------------------------------------------------
revno: 2506.1.3
merged: bialix at ukr.net-20070606074514-qq7bxr0x2uj8c5c2
parent: bialix at ukr.net-20070606071152-a2jaa16xqvu92teg
parent: pqm at pqm.ubuntu.com-20070606050006-o4yiw7jnwytgf561
committer: Alexander Belchenko <bialix at ukr.net>
branch nick: installer-0.17
timestamp: Wed 2007-06-06 10:45:14 +0300
message:
merge bzr.dev; fix ReST formatting in planned-performance-changes.txt
------------------------------------------------------------
revno: 2506.1.2
merged: bialix at ukr.net-20070606071152-a2jaa16xqvu92teg
parent: bialix at ukr.net-20070605080204-hvhqw69njlpxcscb
committer: Alexander Belchenko <bialix at ukr.net>
branch nick: installer-0.17
timestamp: Wed 2007-06-06 10:11:52 +0300
message:
better wording suggested by John Meinel
------------------------------------------------------------
revno: 2506.1.1
merged: bialix at ukr.net-20070605080204-hvhqw69njlpxcscb
parent: pqm at pqm.ubuntu.com-20070604194535-ihhpf84qp0icoj2t
committer: Alexander Belchenko <bialix at ukr.net>
branch nick: installer-0.17
timestamp: Tue 2007-06-05 11:02:04 +0300
message:
sanitize developers docs
=== renamed file 'doc/developers/bundle-creation.rst' => 'doc/developers/bundle-creation.txt'
--- a/doc/developers/bundle-creation.rst 2007-05-27 17:45:50 +0000
+++ b/doc/developers/bundle-creation.txt 2007-06-05 08:02:04 +0000
@@ -26,7 +26,7 @@
:i: length of stored diff
Needs
-=====
+-----
- Improved common ancestor algorithm
- Access to partial revision graph proportional to relevant revisions
- Access to changed files proportional to number of change files and
=== renamed file 'doc/developers/initial-push-pull.rst' => 'doc/developers/initial-push-pull.txt'
--- a/doc/developers/initial-push-pull.rst 2007-05-27 18:47:54 +0000
+++ b/doc/developers/initial-push-pull.txt 2007-06-05 08:02:04 +0000
@@ -1,5 +1,5 @@
Initial push / pull
-###################
+===================
Optimal case
------------
@@ -43,12 +43,12 @@
------------------
Phase 1
-=======
+~~~~~~~
Push: ask if there is a repository, and if not, what formats are okay
Pull: Nothing
Phase 2
-=======
+~~~~~~~
Push: send initial push command, streaming data in acceptable format, following
disk case strategy
Pull: receive initial pull command, specifying format
=== renamed file 'doc/developers/merge-scaling.rst' => 'doc/developers/merge-scaling.txt'
--- a/doc/developers/merge-scaling.rst 2007-06-04 04:07:20 +0000
+++ b/doc/developers/merge-scaling.txt 2007-06-05 08:02:04 +0000
@@ -25,11 +25,11 @@
:i: number of revisions between base and other
Needs
-=====
+-----
- Access to revision graph proportional to number of revisions read
- Access to changed file metadata proportional to number of changes and number of intervening revisions.
- O(1) access to fulltexts
Notes
-=====
+-----
Multiparent deltas may offer some nice properties for performance of annotation based merging.
=== modified file 'Makefile'
--- a/Makefile 2007-05-30 18:40:26 +0000
+++ b/Makefile 2007-06-06 07:57:00 +0000
@@ -121,6 +121,7 @@
doc/default.css NEWS README \
win32_bzr.exe/doc
python tools/win32/ostools.py copytodir doc/developers/HACKING.htm \
+ $(dev_htm_files) \
win32_bzr.exe/doc/developers
# clean produced docs
@@ -154,6 +155,7 @@
python tools/win32/ostools.py remove win32_bzr.exe
python tools/win32/ostools.py remove py2exe.log
python tools/win32/ostools.py remove doc/*.htm
+ python tools/win32/ostools.py remove doc/developers/*.htm
python tools/win32/ostools.py remove doc/bzr_man.txt
python tools/win32/ostools.py remove tools/win32/bzr.iss
python tools/win32/ostools.py remove bzr-setup*.exe
=== modified file 'doc/developers/add.txt'
--- a/doc/developers/add.txt 2007-06-04 03:39:48 +0000
+++ b/doc/developers/add.txt 2007-06-05 08:02:04 +0000
@@ -1,5 +1,5 @@
Add
----
+===
Add is used to recursively version some paths supplied by the user. Paths that
match ignore rules are not versioned, and paths that become versioned are
@@ -7,7 +7,7 @@
a single tree, but perhaps with nested trees this should change.
Least work we can hope to perform
-=================================
+---------------------------------
* Read a subset of the full versioned paths data for the tree matching the scope of the paths the user supplied.
* Seek once to each directory within the scope and readdir its contents.
@@ -25,7 +25,7 @@
(proportional to the number we actually calculate).
Per file algorithm
-==================
+------------------
#. If the path is versioned, and it is a directory, push onto the recurse stack.
#. If the path is supplied by the user or is not ignored, version it, and if a
=== modified file 'doc/developers/annotate.txt'
--- a/doc/developers/annotate.txt 2007-05-15 14:31:42 +0000
+++ b/doc/developers/annotate.txt 2007-06-05 08:02:04 +0000
@@ -1,5 +1,5 @@
Annotate
---------
+========
Broadly tries to ascribe parts of the tree state to individual commits.
=== modified file 'doc/developers/gc.txt'
--- a/doc/developers/gc.txt 2007-05-15 14:31:42 +0000
+++ b/doc/developers/gc.txt 2007-06-05 08:02:04 +0000
@@ -1,5 +1,5 @@
Garbage Collection
-------------------
+==================
Garbage collection is used to remove data from a repository that is no longer referenced.
@@ -7,7 +7,7 @@
then generating a new repository with less data.
Least work we can hope to perform
-=================================
+---------------------------------
* Read all branches to get initial references - tips + tags.
* Read through the revision graph to find unreferenced revisions. A cheap HEADS
=== modified file 'doc/developers/incremental-push-pull.txt'
--- a/doc/developers/incremental-push-pull.txt 2007-06-04 03:39:48 +0000
+++ b/doc/developers/incremental-push-pull.txt 2007-06-05 08:02:04 +0000
@@ -1,5 +1,5 @@
Incremental push/pull
----------------------
+=====================
This use case covers pulling in or pushing out some number of revisions which
is typically a small fraction of the number already present in the target
@@ -9,7 +9,7 @@
responsibility of the Repository object.
Functional Requirements
-=======================
+-----------------------
A push or pull operation must:
* Copy all the data to reconstruct the selected revisions in the target
@@ -18,7 +18,7 @@
data, corrupted data should not be incorporated accidentally.
Factors which should add work for push/pull
-===========================================
+-------------------------------------------
* Baseline overhead: The time to connect to both branches.
* Actual new data in the revisions being pulled (drives the amount of data to
@@ -27,7 +27,7 @@
determination of what revisions to move around).
Push/pull overview
-==================
+------------------
1. New data is identified in the source repository.
2. That data is read from the source repository.
@@ -35,7 +35,7 @@
manner that its not visible to readers until its ready for use.
New data identification
-+++++++++++++++++++++++
+~~~~~~~~~~~~~~~~~~~~~~~
We have a single top level data object: revisions. Everything else is
subordinate to revisions, so determining the revisions to propogate should be
@@ -124,7 +124,7 @@
Data reading
-++++++++++++
+~~~~~~~~~~~~
When transferring information about a revision the graph of data for the
revision is walked: revision -> inventory, revision -> matching signature,
@@ -156,7 +156,7 @@
Data Verification and writing
-+++++++++++++++++++++++++++++
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
New data written to a repository should be completed intact when it is made
visible. This suggests that either all the data for a revision must be made
@@ -247,7 +247,7 @@
avoid ending up wth corrupt/bad data
Notes from London
-=================
+-----------------
#. setup
@@ -268,7 +268,7 @@
#. validate the sha1 of the full text of each transmitted text.
#. validate the sha1:name mapping in each newly referenced inventory item.
#. validate the sha1 of the XML of each inventory against the revision.
- *** this is proportional to tree size and must be fixed ***
+ **this is proportional to tree size and must be fixed**
#. write the data to the local repo.
The API should output the file texts needed by the merge as by product of the transmission
=== modified file 'doc/developers/performance-roadmap-rationale.txt'
--- a/doc/developers/performance-roadmap-rationale.txt 2007-05-07 17:49:30 +0000
+++ b/doc/developers/performance-roadmap-rationale.txt 2007-06-05 08:02:04 +0000
@@ -1,5 +1,5 @@
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
@@ -28,7 +28,7 @@
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
@@ -50,7 +50,7 @@
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
@@ -88,8 +88,8 @@
* update
* cbranch
-how is development on the roadmap coordinated?
-----------------------------------------------
+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
=== modified file 'doc/developers/performance-roadmap.txt'
--- a/doc/developers/performance-roadmap.txt 2007-06-04 05:38:02 +0000
+++ b/doc/developers/performance-roadmap.txt 2007-06-06 07:45:14 +0000
@@ -2,6 +2,15 @@
Bazaar Performance Roadmap
==========================
+.. Mark sections in included files as following:
+.. level 1 ========
+.. level 2 --------
+.. level 3 ~~~~~~~~
+.. level 4 ^^^^^^^^ (it is better not to use nesting deeper than 3 levels)
+
+.. contents::
+.. sectnum::
+
About the performance roadmap
#############################
@@ -14,7 +23,10 @@
.. include:: performance-use-case-analysis.txt
-.. include:: initial-push-pull.rst
+Use cases
+#########
+
+.. include:: initial-push-pull.txt
.. include:: incremental-push-pull.txt
@@ -26,6 +38,6 @@
.. include:: annotate.txt
-.. include:: merge-scaling.rst
+.. include:: merge-scaling.txt
-.. include:: bundle-creation.rst
+.. include:: bundle-creation.txt
=== modified file 'doc/developers/performance-use-case-analysis.txt'
--- a/doc/developers/performance-use-case-analysis.txt 2007-05-09 15:36:06 +0000
+++ b/doc/developers/performance-use-case-analysis.txt 2007-06-05 08:02:04 +0000
@@ -1,5 +1,5 @@
Analysing a specific use case
------------------------------
+=============================
The analysis of a use case needs to provide as outputs:
* The functional requirements that the use case has to satisfy.
@@ -15,7 +15,7 @@
should also be mentioned.
Performing the analysis
------------------------
+=======================
The analysis needs to be able to define the characteristics of the
involved disk storage and APIs. That means we need to examine the data
@@ -38,7 +38,7 @@
fine to post-process the annotated text to obtain dotted-revnos.'
What factors should be considered?
-----------------------------------
+==================================
Obviously, those that will make for an extremely fast system :). There
are many possible factors, but the ones I think are most interesting to
@@ -49,7 +49,7 @@
- The time to get bzr ready to begin the use case.
- scaling: how does performance change when any of the follow aspects
- of the system are ratched massively up or down:
+ of the system are ratched massively up or down:
- number of files/dirs/symlinks/subtrees in a tree (both working and
revision trees)
@@ -71,12 +71,13 @@
- bandwidth to the disk storage
- latency to perform semantic operations (hpss specific)
- bandwidth when performing semantic operations.
+
- locality of reference: If an operation requires data that is located
- within a small region at any point, we often get better performance
- than with an implementation of the same operation that requires the
- same amount of data but with a lower locality of reference. Its
- fairly tricky to add locality of reference after the fact, so I think
- its worth considering up front.
+ within a small region at any point, we often get better performance
+ than with an implementation of the same operation that requires the
+ same amount of data but with a lower locality of reference. Its
+ fairly tricky to add locality of reference after the fact, so I think
+ its worth considering up front.
Using these factors, to the annotate example we can add that its
reasonable to do two 'semantic' round trips to the local tree, one to
=== modified file 'doc/developers/planned-performance-changes.txt'
--- a/doc/developers/planned-performance-changes.txt 2007-06-06 01:01:58 +0000
+++ b/doc/developers/planned-performance-changes.txt 2007-06-06 07:45:14 +0000
@@ -1,5 +1,5 @@
Planned changes to the bzr core
--------------------------------
+===============================
Delivering the best possible performance requires changing the bzr core design
from that present in 0.16. Some of these changes are incremental and can be
@@ -22,7 +22,7 @@
unknown, and disk format, not interoperable.
Library changes
-===============
+---------------
These changes will change bzrlib's API but will not affect the disk format and
thus do not pose a significant migration issue.
@@ -88,7 +88,7 @@
sufficiently clean to let us simplify/remove a lot of related code today.
Interoperable disk changes
-==========================
+--------------------------
* New container format to allow single-file description of multiple named
objects. This will provide the basis for transmission of revisions over the
@@ -132,7 +132,7 @@
established as [un]needed.
Possibly non-interoperable disk changes
-=======================================
+---------------------------------------
* Removing of derivable data from the core of bzr. Much of the data that bzr
stores is derivable from the users source files. For instance the
@@ -157,7 +157,7 @@
* Annotations
Non-interoperable disk changes
-==============================
+------------------------------
* Drop the per-file merge graph 'cache' currently held in the FILE-ID.kndx
files. A specific case of removing derivable data, this may allow smaller
=== modified file 'doc/developers/revert.txt'
--- a/doc/developers/revert.txt 2007-06-04 03:39:48 +0000
+++ b/doc/developers/revert.txt 2007-06-05 08:02:04 +0000
@@ -1,11 +1,11 @@
Revert
-------
+======
Change users selected paths to be the same as those in a given revision making
backups of any paths that bzr did not set the last contents itself.
Least work we can hope to perform
-=================================
+---------------------------------
We should be able to do work proportional to the scope the user is reverting
and the amount of changes between the working tree and the revision being
=== modified file 'setup.py'
--- a/setup.py 2007-05-04 11:02:41 +0000
+++ b/setup.py 2007-06-06 07:57:00 +0000
@@ -170,10 +170,13 @@
import glob
# doc files
docs = glob.glob('doc/*.htm') + ['doc/default.css']
+ dev_docs = glob.glob('doc/developers/*.htm')
# python's distutils-based win32 installer
ARGS = {'scripts': ['bzr', 'tools/win32/bzr-win32-bdist-postinstall.py'],
# help pages
- 'data_files': [('Doc/Bazaar', docs)],
+ 'data_files': [('Doc/Bazaar', docs),
+ ('Doc/Bazaar/developers', dev_docs),
+ ],
}
ARGS.update(META_INFO)
More information about the bazaar-commits
mailing list