[MERGE] Revised mini-tutorial

[John Gabriele]

On 9/28/07, Matthew Revell <matthew.revell at canonical.com> wrote:
> Hi all,
>
> I've fleshed out the mini-tutorial somewhat and, perhaps, pitched it
> at a slightly less experienced reader. I've also moved the "creating a
> personal branch" sections to the end.

Hi Matthew. Glad to see the mini-tut getting attention.

> +
> +Over the next five minutes, you'll learn how to XXX, XXX and XXX.
> +
> +If you'd prefer a more detailed intrdouced, take a look at our guide
> +`Learning More`_.

Typo: intrdouced --> introduction.

>
>  Installation
>  ============
>
> -See http://bazaar-vcs.org/Download. Bazaar is probably in your GNU/Linux
> -distribution already. If not, it's trivial to install on any platform that
> -runs Python 2.4, including Windows. Installation should take at most a few
> -minutes.
> -
> -
> -Introducing Yourself
> +For this guide, we'll assume you Bazaar is already on your system. If not,

Typo: remove "you".

> +
> +
> +Introducing yourself
>  ====================
>
> -You want Bazaar to correctly identify you in revision logs. Using your name
> -and email instead of Joe Doe's, type::
> +Hello, meet bzr. bzr is the command you'll use to invoke Bazaar.

I don't like "Hello, meet bzr". It seems too cutsie, IMO, for vcs docs.

Also, formatting typo: bzr --> ``bzr`` when referring to the program
you run on the command line.

> +
> +Now it's your turn tell Bazaar who you are. This allows Bazaar to correctly
> +identify your work in revision logs.
> +
> +Using your name and email address, instead of Joe Doe's, type::
>
>    $ bzr whoami "Joe Doe <joe.doe at gmail.com>"

I think here, it needs to be mentioned that the command creates or
modifies the ``~/.bazaar/bazaar.conf`` file. This would add meaning to
the "tell Bazaar who you are" statement above.

> -Now try::
> +Now, check that your name and email address are correctly registered::
>
>    $ bzr whoami
>    Joe Doe <joe.doe at gmail.com>
>
>
> -Putting Existing Files Under Version Control
> +Putting existing files under version control
>  ============================================

Personally, I find capitalizing every word in a section heading
distracting and unattractive, preferring to instead only captitalize
the first word.

> -It is very easy to put an existing set of files under version control using
> -Bazaar::
> -
> -  $ cd my-project
> +Okay, it's time to put Bazaar to work.

These sort of comments, though adding an element of familiarity, IMO
are often unecessary. I'm already putting Bazaar to work by going
through the 5-minute tutorial. I would suggest this: don't be afraid
to be brief. If the content is there, and it's concise, accurate, and
there's enough of it, you can stop. Actually, the same goes for the
above remark about "It is very easy to put an existing...". Users will
have limited time and patience. We can just *show* them how easy it is
and say: "Put an existing set of files under version control like
so:".

> +The first step is to tell Bazaar that you want it to track the files in a
> +particular directory.
> +
> +Switch to a directory where you've already got some files, then type::
> +
>    $ bzr init .
> +
> +If it looks like nothing happened, don't worry. You now have an empty
> +Bazaar branch. Let's tell Bazaar which files your want to work with.
> +
>    $ bzr add
> +

Wait. Right here. Did that one ``bzr add`` command just add every file
in the current directory? Did it recurse into subdirectories? I think
it needs to be stated here specifically what ``bzr`` just added.

> +Your files aren't in your branch just yet; you need to commit them first,

At this point, I'm thinking that maybe we should be linking to
glossary pages as we go. We just told the reader they created an empty
branch, but they're going to fidgit in their seat because they don't
really know what a branch is yet. There's also a glossary page for
"commit".

> +along with a quick message to explain the purpose of that commit::
> +
>    $ bzr commit -m "Initial import"

At this point, the reader is probably wondering where the files were
committed to. If they've got any experience at all with version
control, they're wondering where the repository is. If we just leave
them hanging and continue, they're going to be even more unsure of
what's going on. I'd put a comment here describing where the
repository is.

> -
> -
> -Making Changes
> -==============
> +Bazaar has just taken a snapshot of everything in that directory.

I might change that to something more pithy, such as: "Bazaar has just
stored the current state of all the files you've committed.".

>
> -Commit your hard work::
> +Commit your work to your Bazaar branch::
>
>    $ bzr commit -m 'added some whitespace'
>    Committed revision 2.
>
> -
> -Viewing the Revision Log
> +Bazaar has taken another snapshot of your files.
> +

I notice "snapshot" is not in the glossary. You might either define it
and link to it, or change that line to something more concrete.

> +
> +Viewing the revision log
>  ========================
>
> -Browse the history of the branch::
> +You can see the history of your branch by browsing its log::
>
>    $ bzr log
>    ------------------------------------------------------------
>    revno: 2
>    committer: Joe Doe <joe.doe at gmail.com>
>    branch nick: foobar.joe
> -  timestamp: Mon 2006-02-06 01:33:35 +0200
> +  timestamp: Mon 2007-09-28 01:33:35 +0200
>    message:
>      added some whitespace
>    ------------------------------------------------------------
>    revno: 1
> -  committer: James Hacker <jmh at example.com>
> +  committer: Joe Doe <joe.doe at gmail.com>

Nitpicking: Not sure who James is, but folks have been known to use
"J. Random Hacker" for a good name. :) I've never heard of "Joe Doe"
before (though *have*, of course, heard of "John Doe" as used on crime
shows when they identify a body).

>    branch nick: foobar.dev

Request: This is a great place to introduce how this naming.scheme
works (with the dot). Is it a convention? Is it only a nickname, or
does ``bzr`` expect branches to be named like this? Is it a namespace
thing, with 2 names glued together? A sentence or two here would be
great.

> -  timestamp: Mon 2006-02-06 01:06:11 +0200
> +  timestamp: Mon 2006-09-28 01:06:11 +0200
>    message:
>      initial revision
>
>
> -Updating Your Branch from the Main Branch
> +Publishing Your Branch
> +======================
> +
> +There are a couple of ways to publish your branch but the easiest way is to
> +push it to a web server.
> +

Would be nice to have "publish" be a link to the relevant glossary
page (though, again, I see that there isn't one).

> +
> +Now anyone can get their own copy of your branch by typing::
> +
> +  bzr branch http://jod.example.com/foobar.joe/
> +
> +Their branch will have all the same files, with the same revision history
> +as yours but any changes they make will stay in their own branch. If you
> +like, you can merge your branches at any time.
> +

Maybe mention that an alias for "branch" is "get", since some sites
who publish using Bazaar mention to use ``bzr get`` to get their
source.

> +
> +Creating your own branch Personal Branch
> +========================================
> +
> +Of course, you can also make your own branch of someone else's work. Let's
> +say you're interested interested in the Foo project::
> +
> +  $ bzr branch http://example.com/code/foobar.dev foobar.joe
> +  Branched 1 revision(s).
> +
> +Bazaar will download all the files and complete revision history from the
> +Foo project's development branch. Just as you created your own branch from
> +scratch, you now have your own copy of the Foo dev branch.

You refer here to the "Foo dev" branch, but you checked out something
named "foobar.dev". You may want to add that the Foo project calls
their development branch "foobar.dev".

> +Now, any changes you commit will stay in your new personal copy of that
> +branch. So, you don't need internet access to make commits but it also
> +means that your changes won't appear automatically in the Foo project's
> +dev branch.
> +
> +
> +Updating your branch from the main branch
>  =========================================
>
> -While you work hard on your branch, others may have committed new code to the
> -main branch. From time to time, you want to merge changes from the main
> -branch into your branch::
> +While you work hard on your branch,

Possibly change: "work hard on" --> "commit changes to".

> it's likely that other people will
> +continue to commit code to the main branch.
> +
> +To make sure your branch stays up to date, you should merge changes from

"should merge" --> "should periodically merge".

> +the main branch into your personal branch::
>
>    $ bzr merge
>    Using saved location: http://example.com/code/foobar.dev
> @@ -143,35 +206,16 @@
>            return result;
>     }
>
> -Commit the changes from the main branch::
> +You still need to commit those changes into your personal branch::

Instead, maybe use: "and then, of course, also commit them::"

Thanks for your work Matthew. Hope this was helpful.

---John