[RFC] Draft 2 of revised mini-tutorial

John Gabriele jmg3000 at gmail.com
Wed Oct 3 22:50:18 BST 2007


On 10/3/07, Matthew Revell <matthew.revell at canonical.com> wrote:
> Following the input I've had from my first revision of the
> mini-tutorial, here's a new draft.
>

Thanks Matthew. Nice work.

| +Over the next five minutes, you'll learn how to put your files under
| +version control, how to create your own

incomplete

| +For this guide, we'll assume Bazaar is already on your system. If not, it's
| +trivial to install on any platform that runs Python 2.4:
| +
| +- *GNU/Linux:* Bazaar is probably in your GNU/Linux distribution already.

Possibly add: "If not, see the `installation faq`__

__ http://bazaar-vcs.org/InstallationFaq"

Incidentally, that wiki page could probably be renamed to simply
"Installation" or "InstallInstructions". I've often found that the
better your docs are, the smaller your faq gets. ;)

| +If it looks like nothing happened, don't worry. Bazaar has created a
| +_branch where it will store your files and their revision history.

"_branch" --> "branch_"

| +branch and all its commits inside the directory you're working with - look
| +for the ```.bzr``` sub-directory.

```.bzr``` --> ``.bzr``

|  Edit a file::
|
| -  $ cd foobar.joe
| +  $ cd foobar.john
|    $ hack...

Just a sec. At this point, we're still talking about making changes to
files in our own project. This is the first appearance of the name
"foobar.john". Is that the name of our project's top-level directory?
You may want to clarify here, as new users will read than and think
maybe bzr is creating a directory for them for some reason.

| +Let's assume you want to publish your branch at jod.example.com/foobar.john
| +and you have sftp access to the server::
| +
| +  $ bzr push sftp://jod@jod.example.com/public_html/foobar.john/
| +  2 revision(s) pushed.

Just a personal opinion here: I'd like to see mention somewhere in
this paragraph of a url scheme with a plus sign ('+') in front of it.
New users are often unfamiliar with this syntax, and a quick mention
of what, say, "bzr+ssh" indicates would be good, IMO. Most users are
probably familiar with seeing plus signs in urls to mean spaces, so
seeing it *associated* with a urls probably looks unfamilar or
confusing to many.

| +Note that to use sftp, your may need to install ''paramiko'' and
| +''pyCrypto''. See http://bazaar-vcs.org/InstallationFaq for details.

You have 2 single quotes (instead of one double-quote) around paramiko
and pyCrypto.

| +Bazaar won't automatically commit changes from a merge. Although Bazaar
| +excels at handling complex merges, from time to time you may need to
| +resolve conflicts or make other minor changes before committing.

Brief mention after this paragraph (a sentence or two, including the
nessary command(s)) about how your own branch could then be merged
into the trunk would be useful here, IMO, bringing the tutorial full
circle.

---John



More information about the bazaar mailing list