Rev 4085: 'Organizing your workspace' section added to User Guide (Ian in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Fri Mar 6 04:18:18 GMT 2009
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 4085
revision-id: pqm at pqm.ubuntu.com-20090306041815-ce2pd0ulkcih0jxq
parent: pqm at pqm.ubuntu.com-20090306030219-enauehb3achqqq7c
parent: ian.clatworthy at canonical.com-20090306033020-9scn4nggpqvnpcv5
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Fri 2009-03-06 04:18:15 +0000
message:
'Organizing your workspace' section added to User Guide (Ian
Clatworthy)
added:
doc/en/user-guide/organizing_your_workspace.txt organizing_your_work-20090226112520-bc2njq3kwvpeo814-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/branching_a_project.txt branching_a_project.-20071122141511-0knao2lklsdsvb1q-2
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/publishing_a_branch.txt publishing_a_branch.-20071123055134-k5x4ekduci2lbn36-2
doc/en/user-guide/shared_repository_layouts.txt shared_repository_la-20070502152030-bagewuqs18ns24o7-1
------------------------------------------------------------
revno: 4084.1.1
revision-id: ian.clatworthy at canonical.com-20090306033020-9scn4nggpqvnpcv5
parent: pqm at pqm.ubuntu.com-20090306030219-enauehb3achqqq7c
parent: ian.clatworthy at canonical.com-20090226112850-e4pdzx2nafu3jso3
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: ianc-integration
timestamp: Fri 2009-03-06 13:30:20 +1000
message:
'Organizing your workspace' section added to User Guide (Ian Clatworthy)
added:
doc/en/user-guide/organizing_your_workspace.txt organizing_your_work-20090226112520-bc2njq3kwvpeo814-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/branching_a_project.txt branching_a_project.-20071122141511-0knao2lklsdsvb1q-2
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/publishing_a_branch.txt publishing_a_branch.-20071123055134-k5x4ekduci2lbn36-2
doc/en/user-guide/shared_repository_layouts.txt shared_repository_la-20070502152030-bagewuqs18ns24o7-1
------------------------------------------------------------
revno: 4054.4.1
revision-id: ian.clatworthy at canonical.com-20090226112850-e4pdzx2nafu3jso3
parent: pqm at pqm.ubuntu.com-20090226031558-1ubr618vdn4r5f07
committer: Ian Clatworthy <ian.clatworthy at canonical.com>
branch nick: bzr.setup-help
timestamp: Thu 2009-02-26 21:28:50 +1000
message:
added Organizing your workspace to the User Guide
added:
doc/en/user-guide/organizing_your_workspace.txt organizing_your_work-20090226112520-bc2njq3kwvpeo814-1
modified:
NEWS NEWS-20050323055033-4e00b5db738777ff
doc/en/user-guide/branching_a_project.txt branching_a_project.-20071122141511-0knao2lklsdsvb1q-2
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
doc/en/user-guide/publishing_a_branch.txt publishing_a_branch.-20071123055134-k5x4ekduci2lbn36-2
doc/en/user-guide/shared_repository_layouts.txt shared_repository_la-20070502152030-bagewuqs18ns24o7-1
=== modified file 'NEWS'
--- a/NEWS 2009-03-06 01:01:32 +0000
+++ b/NEWS 2009-03-06 03:30:20 +0000
@@ -118,6 +118,11 @@
DOCUMENTATION:
+ * Added ``Organizing your workspace`` to the User Guide appendices,
+ summarizing some common ways of organizing trees, branches and
+ repositories and the processes/workflows implied/enabled by each.
+ (Ian Clatworthy)
+
* The documentation for ``shelve`` and ``unshelve`` has been clarified.
(Daniel Watkins, #327421, #327425)
=== modified file 'doc/en/user-guide/branching_a_project.txt'
--- a/doc/en/user-guide/branching_a_project.txt 2008-10-16 10:57:16 +0000
+++ b/doc/en/user-guide/branching_a_project.txt 2009-02-26 11:28:50 +0000
@@ -37,8 +37,8 @@
where to put it on your filesystem. For maximum storage
efficiency down the track, it is recommended that branches
be created somewhere under a directory that has been set up
-as a shared repository. (See `Choosing a shared repository
-layout`_ in the appendices for guidelines and examples.)
+as a shared repository. (See `Feature branches`_ in
+n `Organizing your workspace`_ for a commonly used layout.)
For example::
bzr init-repo my-repo
=== modified file 'doc/en/user-guide/index.txt'
--- a/doc/en/user-guide/index.txt 2009-02-26 10:10:45 +0000
+++ b/doc/en/user-guide/index.txt 2009-03-06 03:30:20 +0000
@@ -111,6 +111,7 @@
##########
.. include:: specifying_revisions.txt
+.. include:: organizing_your_workspace.txt
.. include:: shared_repository_layouts.txt
.. include:: setting_up_email.txt
.. include:: http_smart_server.txt
=== added file 'doc/en/user-guide/organizing_your_workspace.txt'
--- a/doc/en/user-guide/organizing_your_workspace.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/organizing_your_workspace.txt 2009-02-26 11:28:50 +0000
@@ -0,0 +1,176 @@
+Organizing your workspace
+=========================
+
+Common workspace layouts
+------------------------
+
+The best way for a Bazaar user to organize their workspace for a project
+depends on numerous factors including:
+
+* user role: project owner vs core developer vs casual contributor
+
+* workflows: particularly the workflow the project encourages/mandates
+ for making contributions
+
+* size: large projects have different resource requirements to small ones.
+
+There are at least 4 common ways of organizing one's workspace:
+
+* lightweight checkout
+* standalone tree
+* feature branches
+* switchable sandbox.
+
+A brief description of each layout follows.
+
+
+Lightweight checkout
+--------------------
+
+In this layout, the working tree is local and the branch is remote.
+This is the standard layout used by CVS and Subversion: it's simple
+and well understood.
+
+To set up::
+
+ bzr checkout --lightweight URL project
+ cd project
+
+To work::
+
+ (make changes)
+ bzr commit
+ (make changes)
+ bzr commit
+
+Note that each commit implicitly publishes the change to everyone else
+working from that branch. However, you need to be up to date with changes
+in the remote branch for the commit to succeed. To grab the latest code
+and merge it with your changes, if any::
+
+ bzr update
+
+
+Standalone tree
+---------------
+
+In this layout, the working tree & branch are in the one place. Unless
+a shared repository exists in a higher level directory, the repository
+is located in that same place as well. This is the default layout in
+Bazaar and it's great for small to moderately sized projects.
+
+To set up::
+
+ bzr branch URL project
+ cd project
+
+To work::
+
+ (make changes)
+ bzr commit
+ (make changes)
+ bzr commit
+
+To publish changes to a central location::
+
+ bzr push [URL]
+
+The URL for push is only required the first time.
+
+If the central location has, in the meantime, received changes from
+other users, then you'll need to merge those changes into your local
+branch before you try to push again::
+
+ bzr merge
+ (resolve conflicts)
+ bzr commit
+
+As an alternative, a checkout can be used. Like a branch, a checkout
+has a full copy of the history stored locally but the local branch
+is bound to the remote location so that commits are published to
+both locations at once.
+
+Note: A checkout is actually smarter than a local commit followed by
+a push. In particular, a checkout wil commit to the remote location
+first and only commit locally if the remote commit succeeds.
+
+
+Feature branches
+----------------
+
+In this layout, there are multiple branches/trees, typically sharing
+a repository. One branch is kept as a mirror of "trunk" and each
+unit-of-work (i.e. bug-fix or enhancement) gets its own "feature branch".
+This layout is ideal for most projects, particularly moderately sized ones.
+
+To set up::
+
+ bzr init-repo project
+ cd project
+ bzr branch URL trunk
+
+To start a feature branch::
+
+ bzr branch trunk featureX
+ cd featureX
+
+To work::
+
+ (make changes)
+ bzr commit
+ (make changes)
+ bzr commit
+
+To publish changes to a mailing list for review & approval::
+
+ bzr send
+
+To publish changes to a public branch (that can then be registered as
+a Launchpad merge request, say)::
+
+ bzr push [URL]
+
+As a variation, the trunk can be created as a checkout. If you have
+commit privileges on trunk, that lets you merge into trunk and the
+commit of the merge will implicitly publish your change. Alternatively,
+if the trunk URL is read-only (e.g. a http address), that prevents
+accidental submission this way - ideal if the project workflow uses
+an automated gatekeeper like PQM, say.
+
+
+Local sandbox
+-------------
+
+This layout is very similar to the feature branches layout except that
+the feature branches share a single working tree rather than having one
+each. This is similar to git's default layout and it's useful for projects
+with really large trees (> 10000 files say) or for projects with lots of
+build artifacts (like .o or .class files).
+
+To set up::
+
+ bzr init-repo --no-trees project
+ cd project
+ bzr branch URL trunk
+ bzr checkout --lightweight trunk sandbox
+ cd sandbox
+
+While you *could* start making changes in sandbox now, committing while
+the sandbox is pointing to the trunk would mean that trunk is no longer
+a mirror of the upstream URL (well unless the trunk is a checkout).
+Therefore, you usually want to immediately create a feature branch and
+switch your sandbox to it like this::
+
+ bzr branch ../trunk ../featureX
+ bzr switch ../featureX
+
+The processes for making changes and submitting them are otherwise
+pretty much the same as those used for feature branches.
+
+
+Advanced layouts
+----------------
+
+If you wish, you can put together your own layout based on how **you** like
+things organized. See `Advanced shared repository layouts`_ for examples
+and inspiration.
=== modified file 'doc/en/user-guide/publishing_a_branch.txt'
--- a/doc/en/user-guide/publishing_a_branch.txt 2008-12-24 03:14:16 +0000
+++ b/doc/en/user-guide/publishing_a_branch.txt 2009-02-26 11:28:50 +0000
@@ -19,7 +19,7 @@
You can think of this step as similar to setting up a new cvsroot or
Subversion repository. However, Bazaar gives you more flexibility
in how branches may be organised in your repository. See
-`Choosing a shared repository layout`_ in the appendices for
+`Advanced shared repository layouts`_ in the appendices for
guidelines and examples.
=== modified file 'doc/en/user-guide/shared_repository_layouts.txt'
--- a/doc/en/user-guide/shared_repository_layouts.txt 2007-11-14 03:50:56 +0000
+++ b/doc/en/user-guide/shared_repository_layouts.txt 2009-02-26 11:28:50 +0000
@@ -1,5 +1,5 @@
-Choosing a shared repository layout
-===================================
+Advanced shared repository layouts
+==================================
Bazaar is designed to give you flexibility in how you layout branches inside a shared repository.
This flexibility allows users to tailor Bazaar to their workflow,
More information about the bazaar-commits
mailing list