[RFC] bzr-upload documentation

[Emma Jane Hogbin]

Hello,

I have written a new tutorial for Web developers who might be interested
in using the bzr plugin, Upload. The document uses the same format as
the "in five minutes" tutorial that is already available on-line. I've
included the text of the document below, it is also available at:
http://bazaar-vcs.org/BazaarUploadForWebDev

Once it's accepted I think it will make sense to link to the page from
the plugin page <http://bazaar-vcs.org/BzrPlugins>. I am happy to
incorporate comments sent to me, or if you're feeling up to the
challenge, please feel free to edit the document directly.

I look forward to your comments.

regards,
emma



Bazaar Upload Plugin for Web Development
http://bazaar-vcs.org/BazaarUploadForWebDev

In this tutorial you will learn how to use the plugin bzr-upload to
upload the current revision of your working tree to a remote machine.
This plugin is typically used by Web developers who use Bazaar for
revision control on their local machines, but only want to upload the
latest changes (and not the full revision history) to the Web server.
When uploading files with bzr-upload you may choose between FTP and SFTP
protocols. Additional information about various set-ups for Bazaar are
available on the Workflows page.

This tutorial assumes you have a local testing machine (the local
machine) and a networked Web server (the server). It also assumes you
are comfortable working at the command line and that you have installed
Bazaar on your local machine. Bazaar installation instructions are
available from: http://bazaar-vcs.org/Download

The first thing you need to do is to convert your project's files on the
local machine into a working tree. This is done by initializing a Bazaar
branch within your project's directory. Change directories into your
project directory (note, these steps are done within the project
directory, not from above).

    * initalize the directory:
          o bzr init
    * check to see that a hidden .bzr folder has been created:
          o ls -al
    * add all files in your project to the revision control system:
          o bzr add

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

Once your files have all been added to Bazaar, you will need to take a
snapshot of them. This will start a change history in the hidden
directory .bzr.

    * 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.
          o 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-upload plugin. This plugin is installed only on the
local machine. Use the following steps to install the plugin bzr-upload.

    * 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.
          o mkdir ~/.bazaar/plugins
          o cd ~/.bazaar/plugins
    * install bzr-upload, and initialize the python scripts:
          o

            bzr branch https://launchpad.net/bzr-upload bzr_upload
          o cd bzr_upload
          o python setup.py build_ext -i

Once you've installed the plugin bzr-upload on your local machine you
can upload the files to your server. This command assumes the directory
does not yet exist on the remote server and will create a new directory
for you using the file path you provide. Please update the username,
servername.com and /path/to/files as appropriate for your system.

    * bzr upload
sftp://username@servername.com/~/path/on/server/to/put/files

The first time you run this command the following message will be
printed to the screen, "No uploaded revision id found, switching to full
upload." Each of the files will be listed as they are uploaded to your
server. This may take a while to upload all files on the initial upload.

For subsequent updates you can omit the remote path. Bazaar will
remember where to put the files.

Additional information for the plugin is available from the plugin's
help file. You can read this typing into the command line: bzr --help upload

For additional information on using Bazaar, please refer to the full
documentation on this site. http://bazaar-vcs.org/Documentation




-- 
Emma Jane Hogbin
https://wiki.ubuntu.com/EmmaJane
https://launchpad.net/people/emmajane