New tutorial and an intro

[Emma Jane Hogbin]

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.) I've incorporated your requested
changes into the Wiki (and snipped the email where I agreed), combined
your two emails into one, and left only the bits where I have
outstanding questions. Please let me know if there's a better way to go
back and forth.


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*


>> Let's assume you are starting this project from scratch. Your files
>> are available on your laptop, but not the server. The first thing you
>> need to do is create a Bazaar working tree that contains all of the
>> files for your project. 
> 
> "branch" may be the better term than "working tree" here, though
> you are actually creating both, so making that explicit may be
> good.

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?

[begin second email]


>> Change directories into your project directory (note, these steps are
>> done within the project directory, not from above).
>>
>>       * initalize the directory:
>>               * bzr init
>>       * check to see that a hidden .bzr folder has been created:
>>               * ls -al
>>       * add all files in your project to the revision control system:
>>               * bzr add
>
> Mentioning "rm" and "ignore" may be worthwhile, so that users know
> how to avoid versioning everything.

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

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...I've also only given a pointer to the help
for ignore because it looks complicated and may prevent people from
achieving Bazaar goodness in under five minutes. :)


>> When you are ready to upload the files to the server you will need to
>> install the bzr-push-and-update plugin.
>
> You probably realise that this isn't required for normal push, just
> to get the working tree as you desire. Perhaps that should be
> explicit.

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?

I have also updated the intro paragraph to make it clear this set-up is
for people who have one computer that wants to receive changes but does
not have a predictable 'net address.


>>  This plugin is installed only on the laptop machine. Any changes that
>> are made on the server will be pulled back down to the laptop and
>> merged into that branch. Use the following steps to install the
>> bzr-push-and-update plugin.
>>
>>       * change directories to the location where you'd like to put
>>         your plugins (~/.bazaar/plugins is used in this example; this
>>         directory may already exist)
>>               * mkdir ~/.bazaar/plugins
>>               * cd ~/.bazaar/plugins
>>       * install the bzr-push-and-update plugin:
>>               * bzr branch https://launchpad.net/bzr-push-and-update
>>                 bzr_push_and_update
>
> ~/.bazaar/plugins is effectively the required place to put this.
> Otherwise you need to be root and use the bzrlib/ directory, or
> you need to set $BZR_PLUGIN_PATH, which isn't that convenient.

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


>> Note: At this point you will not have a "checkout" directory on the
>> server. You will not be able to run the second part of this process
>> without it. At this point you must log into the server and run the
>> checkout command.
>>
>>       * ssh username at servername.com
>>
>>       * cd /path/on/server/to/put/files
>>       * bzr checkout
>
> This could be one command as below couldn't it?

It could be, however, I am not fond of combined commands. I think that
it leads to people copying and pasting on blind faith instead of having
some recognition of what they're doing. For example: in the original,
"in five minutes" it took me several reads to see that I wasn't using
some kind of magical bzr wand. I've updated the text below to show my
preferred structure for explaining steps...


>> Once you've created the Bazaar branch on the server you can push the
>> files into the working tree from your laptop.
>>
>>       * ssh username at servername.com bzr update /path/on/server
>
> That's not necessary at this point is it, as this will be a no-op
> with the preceeding "checkout"?

Um. I'll defer to the wisdom of the crowd on this...


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

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

Thanks!!



regards,
emma