Simplified Tutorial

[John Arbash Meinel]

Olaf Conradi wrote:
> On 06/05/06, Erik Bågfors <zindar at gmail.com> wrote:
>> On 5/6/06, Ramon Diaz-Uriarte <rdiaz02 at gmail.com> wrote:
>> > On 05/05/06, Erik Bågfors <zindar at gmail.com> wrote:
>> > > A shared repository is a storage that can contain multiple branches.
>> > > By putting the branches in a shared repository, they will use the
>> same
>> > > storage for things that are the same between different branches.  It
>> > > is recommended to keep related branches in a shared repository.
>> > >
>> > > Branches in bzr can also be standalone, in this case, each branch
>> does
>> > > not share the same storage.
>> > >
>> > > The setup described in this document is where you have one
>> centralized
>> > > shared repository on a central server. This repository is then
>> used by
>> > > all developers.  In this setup, each developer needs to be able to
>> >
>> > In the last paragraph, does "shared" have the meaning of "shared by
>> > several users" or "shared because there are several branches". If the
>> > later, why/how does that relate to  the cvs/svn-like usage.
>>
>> Shared between several branches, they may or may not also be shared
>> between several users, but so may standalone branches. In the example
>> above, it's both.
>>
>> In svn-terms a shared repository is what's also called a repository in
>> svn, and a branch is "trunk", or "branches/foobranch".  In CVS it's
>> harder, because CVS sucks :)
> 
> This nicely demonstrates James Blackwell's point that "shared" in
> "shared repository" is not a great name to use. As shared is often
> interpreted by users as "shared between users" and not "shared by
> branches".
> 
> The same ambiguity might be found in JAM's tutotial, but he hides it a
> bit. Wherever he uses repository it's a shared repository. He mentions
> branches sharing a repository and all other uses of shared refer to
> shared locations, as in sharing among users for publishing.
> 
> But when users read bzr help init-repo later on, it says it will
> create a shared repository. I can imagine a users gets confused and
> thinks this is only useful for centralized revision control. So not
> mentioning that branches sharing a repository is called a shared
> repository in the bzr ui, might be just as confusing.
> 
> On 5/5/06, John Arbash Meinel <john at arbash-meinel.com> wrote:
>> * Repository Branch: With Bzr it is possible to have branches share
>>  their history data. This is especially useful for projects that
>>  create lots of branches (such as short-lived feature branches).
>>  This is done by creating a Repository (``bzr init-repo``). Future
>>  branches that are created in subdirectories will all store their
>>  historical information in the same location.
>>  Merging between branches that share the same repository is very
>>  fast, since no information needs to be copied.
> 
> So this is about shared repositories.

Yes, this is about 'repository the collection of branches', versus
'repository the place where history is stored.'.
Though because the history is store there, it isn't entirely a different
concept.

> 
>> Using Repositories
>> ------------------
>> Create a remote repository for archiving and sharing your branches,
>> and a local repository to reduce the need to copy information around.
> 
> Where both local and remote repositories are "shared repositories" and
> the remote one is used for archiving and publishing. But using sharing
> in the context of "archiving and sharing" makes one associate the word
> sharing with "sharing among users", which might confuse users if they
> read about "shared repository".
> 
> -Olaf

I don't know if 'shared repository' is a great term to be using. I think
we started using it, because we have been a little focused on the
implementation. And I'm realizing we need to step back a little bit, and
come at it from a user, rather than as a developer.
A repository is a repository, and it may have the 'shared' bit set.
Which tells other branches to use it, rather than creating their own.

And I think that is the way we can make it clear in user's minds. "If
you create a repository with 'bzr init-repo', branches in subdirectories
will use it for storing history. Otherwise, each branch will create its
own repository inside the .bzr directory for that branch".

I don't have to use the word 'shared' at all for that explanation. I
think it is relatively clear, and is a true statement (always a bonus :)

What if we change the help text for init-repo to:

Create a repository where branches can share history storage.

New branches created under the repository directory will store their
revisions in the repository, rather than creating a separate repository
inside the branch directory (if the branch format supports shared storage).


John
=:->


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 254 bytes
Desc: OpenPGP digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060506/fe55fc2f/attachment.pgp