New tutorial and an intro

[James Westby]

On Tue, 2008-08-12 at 02:19 -0400, Emma Jane Hogbin wrote:
> Good morning,

> Thanks to some excellent feedback I received in the IRC channel while
> setting up my own system, I have written up a little tutorial on how to
> get a system set up using a Partner workflow (server and laptop). I've
> put the tutorial on the Wiki, please feel free to edit it directly:
> http://bazaar-vcs.org/BazaarForWebDevs

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 realise it's a wiki, but if you'll permit me I'll respond
to it like I would a code review. If you like I can make
the changes directly in the wiki.

> In some workflows you will have access to different computers all the
> time and need to do version controlled revisions at each of the
> different workstations you use. In fact you may also need to do some
> of this revisions directly on the server! Bazaar can help you to keep
> all of these versions correctly up-to-date. Additional information
> about various set-ups for Bazaar are available on the Workflows page:
> http://bazaar-vcs.org/Workflows 

I'd say "changes" instead of "revisions," as the latter is quite
an overloaded term.

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

> 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
>               * 
>       * take a snapshot of the current files by starting a change
>         history in the .bzr hidden directory (i.e. you do NOT need to
>         be connected to the Internet to start commit your files to a
>         revision control system) 
>               * bzr commit -m "Initial import of all project files" 
>       * proceed with your work, checking your files into the
>         repository as appropriate with the commit command. Update the
>         message so that it matches your work. 
>               * bzr commit -m "draft of feature XYZ finished, ready to
>                 test on dev server." 
> 
> When you are ready to upload the files to the server you will need to
> install the bzr-push-and-update plugin. 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 
>                 
> 
> Create a new .bzr branch on the server. Note this uploads the change
> history and general bzr working files only. It does not upload the
> files to the server (yet!). This command assumes the directory does
> not yet exist on the remote server. Please update the username,
> servername.com and /path/to/files as appropriate for your system. 
> 
>       * bzr push --create-prefix
>         sftp://username@servername.com/~/path/on/server/to/put/files 
>         
> 
> This may take a while. When it has completed you will see a message
> printed to the screen that reads, "Created new branch." 
> 
> 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 
> 
> 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 
>         
> 
> Note: you cannot use a ~ in the remote path if your laptop username
> does not match your username on the server. 
> 
> 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 
>         
> 
> If you have been working on the server you will need to merge changes
> down to your laptop. 
> 
>       * bzr merge sftp://username@servername.com/~/path/on/server/ 
>         
> 
> For additional information on using Bazaar, please refer to the full
> documentation on this site. http://bazaar-vcs.org/Documentation
>