Rev 3419: Add plugin and integration chapters to User Guide (Ian Clatworthy) in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri May 9 17:35:44 BST 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3419
revision-id:pqm at pqm.ubuntu.com-20080509163534-t75i8ugsnro38rsh
parent: pqm at pqm.ubuntu.com-20080508230313-knn3ibom6wt27w5k
parent: ian.clatworthy at canonical.com-20080509151047-z5aa8rt9k90liaed
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2008-05-09 17:35:34 +0100
message:
Add plugin and integration chapters to User Guide (Ian Clatworthy)
added:
doc/en/user-guide/bzrtools_plugin.txt bzrtools_plugin.txt-20080509065016-cjc90f46407vi9a0-1
doc/en/user-guide/svn_plugin.txt svn_plugin.txt-20080509065016-cjc90f46407vi9a0-2
doc/en/user-guide/web_browsing.txt web_browsing.txt-20080509065016-cjc90f46407vi9a0-3
renamed:
doc/en/user-guide/best_practice_intro.txt => doc/en/user-guide/part2_intro.txt best_practice_intro.-20071123154453-dk2mjhrg1vpjm5w2-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/bug_trackers.txt bug_trackers.txt-20070713223459-khxdlcudraii95uv-1
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/introducing_bazaar.txt introducing_bazaar.t-20071114035000-q36a9h57ps06uvnl-5
doc/en/user-guide/part2_intro.txt best_practice_intro.-20071123154453-dk2mjhrg1vpjm5w2-1
------------------------------------------------------------
revno: 3418.1.1
revision-id:ian.clatworthy at canonical.com-20080509151047-z5aa8rt9k90liaed
parent: pqm at pqm.ubuntu.com-20080508230313-knn3ibom6wt27w5k
parent: ian.clatworthy at canonical.com-20080509065622-ghlthslc8k070f31
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: ianc-integration
timestamp: Sat 2008-05-10 01:10:47 +1000
message:
Add plugin and integration chapters to User Guide (Ian Clatworthy)
added:
doc/en/user-guide/bzrtools_plugin.txt bzrtools_plugin.txt-20080509065016-cjc90f46407vi9a0-1
doc/en/user-guide/svn_plugin.txt svn_plugin.txt-20080509065016-cjc90f46407vi9a0-2
doc/en/user-guide/web_browsing.txt web_browsing.txt-20080509065016-cjc90f46407vi9a0-3
renamed:
doc/en/user-guide/best_practice_intro.txt => doc/en/user-guide/part2_intro.txt best_practice_intro.-20071123154453-dk2mjhrg1vpjm5w2-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/bug_trackers.txt bug_trackers.txt-20070713223459-khxdlcudraii95uv-1
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/introducing_bazaar.txt introducing_bazaar.t-20071114035000-q36a9h57ps06uvnl-5
doc/en/user-guide/part2_intro.txt best_practice_intro.-20071123154453-dk2mjhrg1vpjm5w2-1
------------------------------------------------------------
revno: 3416.1.2
revision-id:ian.clatworthy at canonical.com-20080509065622-ghlthslc8k070f31
parent: ian.clatworthy at canonical.com-20080509065235-77s3aeza63ootzwy
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-expanded
timestamp: Fri 2008-05-09 16:56:22 +1000
message:
NEWS item
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
------------------------------------------------------------
revno: 3416.1.1
revision-id:ian.clatworthy at canonical.com-20080509065235-77s3aeza63ootzwy
parent: pqm at pqm.ubuntu.com-20080508082241-zyx68bbzrgnlhw9m
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.ug-expanded
timestamp: Fri 2008-05-09 16:52:35 +1000
message:
new structure and initial content for closing chapters
added:
doc/en/user-guide/bzrtools_plugin.txt bzrtools_plugin.txt-20080509065016-cjc90f46407vi9a0-1
doc/en/user-guide/svn_plugin.txt svn_plugin.txt-20080509065016-cjc90f46407vi9a0-2
doc/en/user-guide/web_browsing.txt web_browsing.txt-20080509065016-cjc90f46407vi9a0-3
renamed:
doc/en/user-guide/best_practice_intro.txt => doc/en/user-guide/part2_intro.txt best_practice_intro.-20071123154453-dk2mjhrg1vpjm5w2-1
modified:
doc/en/user-guide/bug_trackers.txt bug_trackers.txt-20070713223459-khxdlcudraii95uv-1
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/introducing_bazaar.txt introducing_bazaar.t-20071114035000-q36a9h57ps06uvnl-5
doc/en/user-guide/part2_intro.txt best_practice_intro.-20071123154453-dk2mjhrg1vpjm5w2-1
=== added file 'doc/en/user-guide/bzrtools_plugin.txt'
--- a/doc/en/user-guide/bzrtools_plugin.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/bzrtools_plugin.txt 2008-05-09 06:52:35 +0000
@@ -0,0 +1,149 @@
+BzrTools
+========
+
+Overview
+--------
+
+BzrTools is a collection of useful enhancements to Bazaar.
+Here is a sample of the frequently used commands it provides.
+
+
+shelve, shelf, unshelve
+-----------------------
+
+These commands provide a fine-grained (patch-hunk level) undo facility.
+This allows you to put aside some of your changes, commit,
+and get back to where you were before.
+
+For example, consider a working tree with one or more changes made ... ::
+
+ $ bzr diff
+ === modified file 'description.txt'
+ --- description.txt
+ +++ description.txt
+ @@ -2,7 +2,7 @@
+ ===============
+
+ These plugins
+ -by Michael Ellerman
+ +written by Michael Ellerman
+ provide a very
+ fine-grained 'undo'
+ facility
+ @@ -11,6 +11,6 @@
+ This allows you to
+ undo some of
+ your changes,
+ -commit, and get
+ +perform a commit, and get
+ back to where you
+ were before.
+
+The ``shelve`` command interactively asks which changes
+you want to retain in the working tree::
+
+ $ bzr shelve
+ --- description.txt
+ +++ description.txt
+ @@ -2,7 +2,7 @@
+ ===============
+
+ These plugins
+ -by Michael Ellerman
+ +written by Michael Ellerman
+ provide a very
+ fine-grained 'undo'
+ facility
+
+ Keep this change? (1 of 2) [nydisq?] (n): y
+ --- description.txt
+ +++ description.txt
+ @@ -11,6 +11,6 @@
+ This allows you to
+ undo some of
+ your changes,
+ -commit, and get
+ +perform a commit, and get
+ back to where you
+ were before.
+
+ Keep this change? (2 of 2) [nydisq?] (n): n
+
+ Status:
+ description.txt
+ 1 hunks to be shelved
+ 1 hunks to be kept
+
+ Shelve these changes, or restart? [yrsiq?] (y): y
+ Saving shelved patches to /tmp/proj/.bzr-shelf
+ Reverting shelved patches
+ Diff status is now:
+ description.txt | 2 +-
+ 1 files changes, 1 insertions(+), 1 deletions(-)
+
+If there are lots of changes in the working tree, you
+can provide the ``shelve`` command with a list of files
+and you will only be asked about changes in those files.
+After shelving changes, it's a good idea to use ``diff``
+to confirm the tree has just the changes you expect::
+
+ $ bzr diff
+ === modified file 'description.txt'
+ --- description.txt
+ +++ description.txt
+ @@ -2,7 +2,7 @@
+ ===============
+
+ These plugins
+ -by Michael Ellerman
+ +written by Michael Ellerman
+ provide a very
+ fine-grained 'undo'
+ facility
+
+Great - you're ready to commit::
+
+ $ bzr commit -m "improve first sentence"
+
+At some later time, you can bring the shelved changes back into the
+working tree using ``unshelve``::
+
+ $ bzr unshelve
+ Reapplying shelved patches
+ Diff status is now:
+ description.txt | 4 ++--
+ 1 files changes, 2 insertions(+), 2 deletions(-)
+
+If you want to, you can put multiple items on the shelf.
+Normally each time you run ``unshelve`` the most recently
+shelved changes will be reinstated. However, you can also
+unshelve changes in a different order by explicitly
+specifying which changes to unshelve. (This works best
+when the changes don't depend on each other.)
+
+While you have patches on the shelf you can view and manipulate them
+with the ``shelf`` command. Run ``bzr shelf -h`` for more information
+about how to do this.
+
+
+shell
+-----
+
+``bzr shell`` starts up a command interpreter than understands
+Bazaar commands natively. This has several advantages:
+
+ * There's no need to type ``bzr`` at the front of every command.
+
+ * Intelligent auto-completion is provided.
+
+ * Commands run slightly faster as there's no need to load Bazaar's
+ libraries each time.
+
+
+cdiff
+-----
+
+``bzr cdiff`` provides a colored version of ``bzr diff`` output.
+On GNU/Linux, UNIX and OS X, this is often used like this::
+
+ bzr cdiff | less -R
=== added file 'doc/en/user-guide/svn_plugin.txt'
--- a/doc/en/user-guide/svn_plugin.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/svn_plugin.txt 2008-05-09 06:52:35 +0000
@@ -0,0 +1,111 @@
+bzr-svn
+=======
+
+Overview
+--------
+
+bzr-svn lets developers use Bazaar as their VCS client on projects
+still using a central Subversion repository. Access to Subversion
+repositories is largely transparent, i.e. you can use most ``bzr``
+commands directly on Subversion repositories exactly the same
+as if you were using ``bzr`` on native Bazaar branches.
+
+Many bzr-svn users create a local mirror of the central Subversion
+trunk, work in local feature branches, and submit their
+overall change back to Subversion when it is ready
+to go. This lets them gain many of the advantages of distributed
+VCS tools without interrupting existing team-wide processes and
+tool integration hooks currently built on top of Subversion. Indeed,
+this is a common interim step for teams looking to adopt Bazaar but
+who are unable to do so yet for timing or non-technical reasons.
+
+
+A simple example
+----------------
+
+Here's a simple example of how you can use bzr-svn to hack on a
+GNOME project like **beagle**. Firstly, setup a local shared repository
+for storing your branches in and checkout the trunk::
+
+ bzr init-repo --rich-root-pack beagle-repo
+ cd beagle-repo
+ bzr checkout svn+ssh://svn.gnome.org/svn/beagle/trunk beagle-trunk
+
+Note that using the ``rich-root-pack`` option to ``init-repo`` is
+important as bzr-svn requires some extra metadata not yet supported in Bazaar's
+default repository format. Next, create a feature branch and hack away::
+
+ bzr branch beagle-trunk beagle-feature1
+ cd beagle-feature1
+ *changes*
+ bzr commit -m "blah blah blah"
+ *changes*
+ bzr commit -m "blah blah blah"
+
+When the feature is cooked, refresh your trunk mirror and merge
+your change::
+
+ cd ../beagle-trunk
+ bzr update
+ bzr merge ../beagle-feature1
+ bzr commit -m "Complete comment for SVN commit"
+
+As your trunk mirror is a checkout, committing to it implicitly
+commits to the real Subversion trunk. That's it!
+
+
+Using a central repository mirror
+---------------------------------
+
+For large projects, it often makes sense to tweak the recipe given above.
+In particular, the initial checkout can get quite slow so you may wish
+to import the Subversion repository into a Bazaar one once and for all
+for your project, and then branch from that native Bazaar repository
+instead. bzr-svn provides the ``svn-import`` command for doing this
+repository-to-repository conversion. See ``bzr help svn-import`` for details.
+
+Here's the recipe from above updated to use a central Bazaar mirror::
+
+ bzr init-repo --rich-root-pack beagle-repo
+ cd beagle-repo
+ bzr branch bzr+ssh://bzr.gnome.org/bzr/beagle/trunk beagle-trunk
+ bzr branch beagle-trunk beagle-feature1
+ cd beagle-feature1
+ *changes*
+ bzr commit -m "blah blah blah"
+ *changes*
+ bzr commit -m "blah blah blah"
+ cd ../beagle-trunk
+ bzr pull
+ bzr merge ../beagle-feature1
+ bzr commit -m "Complete comment for SVN commit"
+ bzr svn-push
+
+In this case, committing to the trunk only commits the merge locally.
+To commit back to the master Subversion trunk, an additional command
+(``bzr svn-push``) is required.
+
+Note: You'll need to give ``pull and ``svn-push`` the relevant URLs
+the first time you use those commands in the trunk branch. After that,
+bzr remembers them.
+
+The final piece of the puzzle in this setup is to put scripts in
+place to keep the central Bazaar mirror synchronized with the Subversion
+one. This can be done by adding a cron job, using a Subversion hook,
+or whatever makes sense in your environment.
+
+
+Limitations of bzr-svn
+----------------------
+
+Bazaar and Subversion are different tools with different capabilities
+so there will always be some limited interoperability issues.
+Here are some examples current as of bzr-svn 0.49:
+
+ * Bazaar doesn't support versioned properties
+
+ * Renames are not correctly communicated.
+
+See the bzr-svn web page,
+http://bazaar-vcs.org/BzrForeignBranches/Subversion,
+for the current list of constraints.
=== added file 'doc/en/user-guide/web_browsing.txt'
--- a/doc/en/user-guide/web_browsing.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/web_browsing.txt 2008-05-09 06:52:35 +0000
@@ -0,0 +1,20 @@
+Web browsing
+============
+
+Overview
+--------
+
+There are a range of options available for providing a web view of a
+Bazaar repository. In increasing order of complexity, these are:
+
+* bzrweb
+* webserve
+* Loggerhead
+
+The first 2 tools are lightweight and easy to install.
+Loggerhead takes more effort to setup but provides more functionality.
+See http://bazaar-vcs.org/WebInterface for the latest information on
+these packages including download links.
+
+Note: If your project is hosted or mirrored on Launchpad,
+Loggerhead code browsing is provided as part of the service.
=== renamed file 'doc/en/user-guide/best_practice_intro.txt' => 'doc/en/user-guide/part2_intro.txt'
--- a/doc/en/user-guide/best_practice_intro.txt 2007-11-23 15:45:20 +0000
+++ b/doc/en/user-guide/part2_intro.txt 2008-05-09 06:52:35 +0000
@@ -1,5 +1,5 @@
-Welcome to best practices
-=========================
+The journey ahead
+=================
We hope that earlier chapters have given you a solid
understanding of how Bazaar can assist you in being productive
@@ -8,7 +8,10 @@
good to try the procedures covered already for a while,
coming back to this manual once you have mastered them.
-This chapter covers miscellaneous topics to guide you in
-further optimizing how you use Bazaar. Unless stated otherwise,
-the topics are independent of each other and can therefore be
-read in whichever order you wish.
+This chapter briefly introduces some of the more popular plugins
+and explains why you may wish to use them. Remaining chapters
+covers various topics to guide you in further optimizing how you
+use Bazaar. Unless stated otherwise, the topics in this and
+remaining chapters are independent of each other and can therefore
+be read in whichever order you wish.
+
=== modified file 'NEWS'
--- a/NEWS 2008-05-08 21:22:06 +0000
+++ b/NEWS 2008-05-09 15:10:47 +0000
@@ -86,6 +86,11 @@
DOCUMENTATION:
+ * Expanded the User Guide to include new chapters on popular plugins and
+ integrating Bazaar into your environment. The *Best practices* chapter
+ was renamed to *Miscellaneous topics* as suggested by community
+ feedback as well. (Ian Clatworthy)
+
* Document outlining strategies for TortoiseBzr. (Mark Hammond)
* Improved the documentation on hooks. (Ian Clatworthy)
=== modified file 'doc/en/user-guide/bug_trackers.txt'
--- a/doc/en/user-guide/bug_trackers.txt 2008-01-03 02:17:12 +0000
+++ b/doc/en/user-guide/bug_trackers.txt 2008-05-09 06:52:35 +0000
@@ -1,5 +1,5 @@
-Integrating Bazaar with bug trackers
-====================================
+Bug trackers
+============
Bazaar has a facility that allows you to associate a commit with a bug
in the project's bug tracker. Other tools (or hooks) can then use this
=== modified file 'doc/en/user-guide/index.txt'
--- a/doc/en/user-guide/index.txt 2008-01-15 20:55:15 +0000
+++ b/doc/en/user-guide/index.txt 2008-05-09 06:52:35 +0000
@@ -76,15 +76,33 @@
.. include:: sending_changes.txt
-Best practices
-##############
-
-.. include:: best_practice_intro.txt
+A brief tour of some popular plugins
+####################################
+
+.. include:: part2_intro.txt
+.. include:: bzrtools_plugin.txt
+.. include:: svn_plugin.txt
+.. include later looms_plugin.txt
+
+
+Integrating Bazaar into your environment
+########################################
+
+.. include:: web_browsing.txt
+.. include later - file_explorers.txt
+.. include later - desktop_integration.txt
+.. include later - editors_and_ides.txt
+.. include later - email.txt
+.. include:: bug_trackers.txt
+
+
+Miscellaneous topics
+####################
+
.. include:: adv_merging.txt
.. include:: server.txt
.. include:: hooks.txt
.. include:: version_info.txt
-.. include:: bug_trackers.txt
Appendices
=== modified file 'doc/en/user-guide/introducing_bazaar.txt'
--- a/doc/en/user-guide/introducing_bazaar.txt 2008-03-28 01:49:20 +0000
+++ b/doc/en/user-guide/introducing_bazaar.txt 2008-05-09 06:52:35 +0000
@@ -118,9 +118,10 @@
Chapters 2-6 provide a closer look at how to use Bazaar to complete
various tasks. It is recommended that most users read these in first-to-last
-order shortly after starting to use Bazaar. Chapters 7 and beyond provide
-additional information including some recommended best practices.
-This material can be read when required and in any order.
+order shortly after starting to use Bazaar. Chapter 7 and beyond provide
+additional information that helps you make the most of Bazaar once the core
+functionality is understood. This material can be read when required and in
+any order.
If you are already familar with other version control tools,
you may wish to get started quickly by reading the following documents:
More information about the bazaar-commits
mailing list