New tutorial and an intro

[James Westby]

On Thu, 2008-08-14 at 12:58 -0400, Emma Jane Hogbin wrote:
> James,
> 
> Thank you for the feedback! (And also thanks for your emails back in
> June where you convinced me that Bazaar was better than Git when I was
> looking to switch from svn and cvs.)

Hey Emma, I'm glad it worked.

> James Westby wrote:
> > On Tue, 2008-08-12 at 02:19 -0400, Emma Jane Hogbin wrote:
> > Hi Emma, thanks for writing this it's good to have specific
> > documents for certain groups of users.  It would be great if
> > we could flesh it out in to a full guide for web developers.
> 
> I'd be delighted to help with this. I think it would also be nice to
> extend the workflows page to have an "in five minutes" for each of the
> scenarios. Although it would be a lot of very similar documents, I think
> it would help to entice new users...There are also ways of dealing with
> this similar, but different, documents. For now I'll refrain from
> getting excited about DITA and reusable chunks of documentation though.
> I appreciate not everyone cares about these sorts of things with the
> same depth of passion. *ahem*
> 

While I can't say I understand what DITA is, let alone share your
passion for it, I think it would be good to have this.

> I have updated this to: The first thing you need to do is to convert
> your project's files into a working tree by initializing a Bazaar branch
> within your project's directory.
> Is that right?

I think that works.

There's always a danger of trying to explain too many concepts at
an early stage like this.

> I've updated the text as follows:
> Note: This will include all files in the directory, and sub-directories.
> If you want to include only a few files, you may add them individually,
> or as a batch, with:
>   * bzr add [FILE...]
> If you would like to omit sub-directories you may choose to add only
> files in the current directory with the --no-recurse parameter as follows:
>   * bzr add --no-recurse
> You may also choose to "ignore" some types of files, or directories.
> Additional information is available from the command line help with:
>   * bzr --help ignore

That's good.

    * bzr help ignore

is slightly more elegant in my opinion.

> I've omitted "remove" as it actually deletes the files and my guess is
> that people don't want to delete files from their computers as they try
> to set up version control.

There is a --keep option, and it won't remove the file anyway if there
would be data loss (which would be the case if the file hadn't been
committed yet).

The aim was to give users a pointer in case they accidentally added 
an .iso and committed, as even if they removed it in the next commit
it would still have to be carried around in the branch. If you think
it's not worth it then that is fine.

> This is where only mostly understanding some of the basics gets in the
> way. I've updated that sentence to read:
> "This plugin is installed only on the laptop machine and is only
> necessary if you want to force a remote machine to update its files on
> commit from your local machine."
> Is that true though?

s/commit/push/, but yes.

> I've updated this text to:
> change directories to your local Bazaar plugin directory
> (~/.bazaar/plugins). This directory may not exist, if it does not exist
> you will need to create it now.

That's why I think we should create it by default, easier for
documentation and IRC support. Not your problem though, unless
you want to submit a patches as well.

>  I don't think alternatives need to be
> explained or described in the "in five minutes" version...let me know if
> you think people should be directed back to the main documentation for
> alternative plugin directories?

I think it's something that can be largely ignored.

> >> You are now ready to work from either branch on either computer. To
> >> push the changes to the server repeat the push command and then the
> >> bzr update via ssh. They look like this:
> >>
> >>       * bzr push
> >>         sftp://username@servername.com/~/path/on/server/to/put/files
> >>
> >>       * ssh username at servername.com bzr update /path/on/server
> >
> > The point of the push-and-update plugin is that it automates this.
> > Presumably "bzr push-and-update" would do both the steps.
> >
> > Also, "bzr push" remembers the default URL to use (and so does
> > push-and-update I assume), so this should just become
> >
> >   bzr push-and-update
> 
> /me face palms. NOW I get it. :) Document updated as follows:
> 
> You are now ready to work from either branch on either computer. To push
> the updates and immediately publish the changed files use the
> push-and-update plugin as follows:
>  * bzr push-and-update
> sftp://username@servername.com/~/path/on/server/to/put/files
> For subsequent pushes you can omit the remote path. Bazaar will remember
> where to put the files. This command effectively automates a "push" to
> the server and a checkout.

"update" I think?

>  Without the plugin this would be a multi-step
> process of (1) bzr push and (2) connecting to the server via SSH to
> perform at bzr update.
> 

That was the original way of using the plugin.

> Unless of course John's subsequent email shows that I've completely
> misunderstood things again. Guidance is required. :)

John made the plugin smarter so that "bzr push" will do the update
if you have the plugin installed and the target has a working tree.
I don't know if you think it's better to show the more explicit
command above, or explain the "magic".

Thanks,

James