[RFC] Draft 2 of revised mini-tutorial

Matthew Revell matthew.revell at canonical.com
Mon Oct 8 18:27:59 BST 2007


On 03/10/2007, John Gabriele <jmg3000 at gmail.com> wrote:
> On 10/3/07, Matthew Revell <matthew.revell at canonical.com> wrote:

> |  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.

I've removed that small code block as I'm not really sure what it
added to the doc.

>
> | +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.

Interesting point. I'm not sure right now of the best way to include
that without complicating the document. I think it's probably worth
complicating the document, though, to introduce the idea that bzr has
its own protocol. What do other people think?

>
> | +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.

Sorry, wiki formatting getting the better of me; was meant to be
italics. Would back-ticks (mentioned below by Martin) be a better
option?

>
> | +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.

Thanks. I've added that.

Will post new draft when I've taken account of other feedback.

-- 
Matthew Revell
launchpad.net

mrevell in #launchpad on Freenode



More information about the bazaar mailing list