[RFC] Draft 2 of revised mini-tutorial

John Arbash Meinel john at arbash-meinel.com
Tue Oct 9 19:19:48 BST 2007


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Matthew Revell wrote:
> On 03/10/2007, Matthew Revell <matthew.revell at canonical.com> wrote:
> 
> I've updated the mini-tutorial to include John and Martin's
> suggestions. Although, I'd like to solicit input on what the
> "contributing back to a project" section should include?
> 
>  - Straightforward merging by the project?
>  - Cherrypicks?
>  - Bundles?
> 
> Bundle attached.
> 
> Thanks.
> 
> 
> 

There are a few small ReST syntax issues, and I thought I would mention
that you can do:

make doc/en/mini-tutorial/index.html

And it should run the rst2html parser with the right options. That way
you can check if the output matches what you think it should. (So that
you see ``monospace`` blocks rather than just ''double quotes'', etc.)


Maybe "For the rest of this guide". Otherwise it seems a little odd to
say "we will assume you have it" and then describe (minimally) how to
install it.

Or maybe just say:

This guide does not cover how to install Bazaar. It is usually very easy
to do so, and is described in ...


> +For this guide, we'll assume Bazaar is already on your system. If not, it's
> +trivial to install on any platform that runs Python 2.4:
> +
> +- *GNU/Linux:* Bazaar is probably in your GNU/Linux distribution already.
> +- *Windows:* `installation instructions`_.
> +- *Mac OS X:* `install using MacPorts`_.
> +
> +For other platforms and how to install from source code, see the Downloads_
> +and Installation_ pages.
> +
> +.. _installation instructions: http://bazaar-vcs.org/WindowsDownloads
> +.. _install using MacPorts: http://bazaar-vcs.org/MacPorts
> +.. _Downloads: http://bazaar-vcs.org/Download
> +.. _Installation: http://bazaar-vcs.org/InstallationFAQ
> +
> +
> +Introducing yourself
>  ====================
>  


Before you start working, it is good to tell Bazaar who you are. That
way your work is properly identified.

... properly identified in the committed information.
... properly identified in the revision logs.
... properly recorded so other people can identify who did it.

I'm guessing in a 5-min tutorial we don't want to mention that you don't
have to use an email address. But maybe if we had a link to more
information? Or we could put it as a footnote. Something like:

your name and email address. [1]_

.. [1] An email address is not strictly required. But it is the standard
way of keeping track of people who would otherwise have the same name.
It also means people who see your great work have a way to get in touch
with you to thank you and send you money.


> +Before you start work, you need to tell Bazaar your name and email address.
> +This lets Bazaar identify your work in revision logs.
> +
> +Using your name and email address, instead of John Doe's, type::
> +
> +  $ bzr whoami "John Doe <john.doe at gmail.com>"
> +  
> +Bazaar will now create or modify a configuration file, including your name
> +and email address, at ~/.bazaar/bazaar.conf
> +
> +Now, check that your name and email address are correctly registered::
>  
>    $ bzr whoami
> -  Joe Doe <joe.doe at gmail.com>
> -
> -
> -Putting Existing Files Under Version Control
> +  John Doe <john.doe at gmail.com>
> +
> +
> +Putting existing files under version control
>  ============================================


This section was originally intended for people who already have a
project they want to start versioning. So creating the files is a little
bit odd.

Maybe we can start with:

Often you will already have a project with files that you want to start
versioning. Assuming you have a project with files like::

  my-project/
    test1.txt
    test2.txt
    test3.txt
    subdirectory/test4.txt



>  
> -It is very easy to put an existing set of files under version control using
> -Bazaar::
> -
> -  $ cd my-project
> -  $ bzr init .
> +Let's create a directory and some files to use with Bazaar::
> +
> + $ mkdir myproject
> + $ cd myproject
> + $ mkdir subdirectory
> + $ touch test1.txt test2.txt test3.txt subdirectory/test4.txt
> +
> +Now get Bazaar to initalise itself in that directory::
> +
> +  $ bzr init
> +  
> +If it looks like nothing happened, don't worry. Bazaar has created a
> +_branch where it will store your files and their revision history.
> +
> +.. _branch: http://bazaar-vcs.org/Branch
> +


v- At a minimum you need to end this line with "::" so that ReST knows
the next line is a Code section.

> +The next step is to tell Bazaar which files you want to track.
> +
>    $ bzr add
> +
> +Bazaar will now recursively put everything in the directory under version
> +control::
> +
> + $ added subdirectory
> + $ added test1.txt
> + $ added test2.txt
> + $ added test3.txt
> + $ added subdirectory/test4.txt
> +

^- Generally you are showing the command line, and its output. Output
lines do not start with "$". It might be clearer as

The next step is to tell Bazaar which files you want to track. Running
``bzr add`` will recursively add everything in the project::

  $ bzr add
  added subdirectory
  added test1.txt
  added test2.txt
  ...


> +Next, take a snapshot of your files by committing them to your branch. Add 
> +a commit message to explain why you made the commit::
> +
>    $ bzr commit -m "Initial import"

...

> +  
> +As Bazaar is a distributed version control system, it doesn't need to 
> +connect to a central server to make the commit. Instead, Bazaar stores your 
> +branch and all its commits inside the directory you're working with - look
> +for the ``.bzr`` sub-directory.
> +
> +
> +Making changes to your files
> +============================
> +
> +Let's change a file and commit those changes to your branch.
> +
> +Edit ``test1.txt`` in your favourite editor, then check what have you done::


You need to mention running "bzr diff" here.

   $ bzr diff
   === modified file 'test1.txt'
   --- test1.txt
...


> +
> + === modified file 'test1.txt'
> + --- test1.txt   2007-10-08 17:56:14 +0000
> + +++ test1.txt   2007-10-08 17:46:22 +0000
> + @@ -0,0 +1,1 @@
> + +test test test
> +
> +Commit your work to your Bazaar branch::
> +
> +  $ bzr commit -m 'added first line of text'
>    Committed revision 2.
>  
>  
> -Viewing the Revision Log
> +Viewing the revision log
>  ========================
>  
> -Browse the history of the branch::
> +You can see the history of your branch by browsing its log::
>  
>    $ bzr log
>    ------------------------------------------------------------
>    revno: 2
> -  committer: Joe Doe <joe.doe at gmail.com>
> -  branch nick: foobar.joe
> -  timestamp: Mon 2006-02-06 01:33:35 +0200
> +  committer: John Doe <john.doe at gmail.com>
> +  branch nick: myproject
> +  timestamp: Mon 2007-10-08 17:56:14 +0000
>    message:
> -    added some whitespace
> +    added first line of text
>    ------------------------------------------------------------
>    revno: 1
> -  committer: James Hacker <jmh at example.com>
> -  branch nick: foobar.dev
> -  timestamp: Mon 2006-02-06 01:06:11 +0200
> +  committer: John Doe <john.doe at gmail.com>
> +  branch nick: myproject
> +  timestamp: Mon 2006-10-08 17:46:22 +0000
>    message:
> -    initial revision
> -
> -
> -Updating Your Branch from the Main Branch
> +    Initial import
> +


^- In your commit messages, you are being a little inconsistent with
capitalization. "Initial import" versus "added first line of text".

While I'm sure users will always do that, it looks better in a tutorial
if we are consistent.


> +
> +Publishing Your Branch
> +======================
> +
> +There are a couple of ways to publish your branch but the easiest way is to
> +push it to a web server.
> +
> +Let's assume you want to publish your branch at myserver.com/myproject
> +and you have sftp access to the server::
> +
> +  $ bzr push sftp://me@myserver.com/public_html/myproject/
> +  2 revision(s) pushed.

^- With 'sftp' you almost always would have this as "/~/public_html/"
since that is the users directory.

At least *I* haven't seen http repositories which put public_html in '/'
and then have all files served from there.


> +    
> +*Note:* to use sftp, you may need to install ``paramiko`` and
> +``pyCrypto``. See http://bazaar-vcs.org/InstallationFaq for details.
> +
> +Now anyone can get their own copy of your branch by typing::
> +
> +  bzr branch http://myserver.com/myproject/
> +
> +Their branch will have all the same files, with the same revision history
> +as yours but any changes they make will stay in their own branch. If you
> +like, you can merge your branches at any time.
> +
> +
> +Creating and working with your own copy of someone else's branch
> +================================================================
> +
> +You can also make your own branch of someone else's work. Let's take a
> +real-world example, Bazaar's GTK interface::
> +
> +  $ bzr branch http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk bzr-gtk.john
> +  Branched 292 revision(s).                                                        
> +
> +Bazaar will download all the files and complete revision history from the
> +bzr-gtk project's trunk branch and create a copy called bzr-gtk.john.
> +
> +Now, you have your own copy of the branch you can make any changes you want
> +without a net connection. You can share your branch at any time by 
> +publishing it. If the  bzr-gtk team want to use your work, Bazaar makes it 
> +easy for them to merge your branch back into their trunk branch.
> +
> +
> +Updating your branch from the main branch
>  =========================================
>  
> -While you work hard on your branch, others may have committed new code to the
> -main branch. From time to time, you want to merge changes from the main
> -branch into your branch::
> +While you commit changes to your branch, it's likely that other people will
> +also continue to commit code to the main branch.
> +
> +To make sure your branch stays up to date, you should merge changes from
> +the main branch into your personal branch::
>  
>    $ bzr merge
> -  Using saved location: http://example.com/code/foobar.dev
> +  Using saved location: http://bazaar.launchpad.net/~bzr/bzr-gtk/trunk
>    All changes applied successfully.
>              
> -What was changed locally by merging the main branch?
> -
> -::
> +Check what has changed::
>  
>    $ bzr diff
> -  === modified file 'pyfribidi.c'
> -  --- pyfribidi.c
> -  +++ pyfribidi.c
> -  @@ -236,6 +236,7 @@
> -          PyMem_Del (logical);
> -          PyMem_Del (visual);
> -   
> -  +    /* evil hack! */
> -          return result;
> -   }
>   
> -Commit the changes from the main branch::
> +If you're happy with the changes, you can commit them to your personal
> +branch::
>  
>    $ bzr commit -m 'merge from main branch'
> -  Committed revision 6.
> -
> -Note that you may occasionally need to resolve conflicts or make other minor
> -changes (so tests pass say) before committing. For these reasons, merge does
> -not implicitly commit.
> -
> -
> -Publishing Your Branch
> -======================
> -
> -You can simply use rsync to copy your branch to a web server, but using
> -``bzr push`` is the easiest way. Let's assume you want to publish your
> -branch in jod.example.com/foobar.joe and you have sftp access to the server::
> -
> -  $ bzr push sftp://jod@jod.example.com/public_html/foobar.joe/
> -  2 revision(s) pushed.
> -    
> -Note that to use sftp, your may need to install ''paramiko'' and ''pyCrypto''.
> -See http://bazaar-vcs.org/InstallationFaq for details.
> -
> -Now anyone can get your branch with (try it yourself!)::
> -
> -  bzr branch http://jod.example.com/foobar.joe/
> -
> -
> -Learning More
> +  Committed revision 295.
> +
> +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. 
> +

^- There are more ideological reasons for not doing so. But certainly
this isn't the place for a long discussion. Even so, this doesn't
*quite* sit right to me.


> +
> +Learning more
>  =============
>  
> -To learn about bzr topics::
> +To learn about Bazaar::
>  
>    $ bzr help
>  
> -To learn about bzr commands::
> +To learn about Bazaar commands::
>  
>    $ bzr help commands

^- I think you definitely want to include some sort of link here to more
documentation. Maybe some sort of "in-depth" chapter. Or direct links to
an index/specific workflow discussions/etc.

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHC8ZEJdeBCYSNAAMRAt+gAJ4jiVI1YZ9ywA08nKvp8E2bYNp6xgCgzF0V
gTk9Z6Z/Ce0FAIdjY29PN1s=
=+CQL
-----END PGP SIGNATURE-----



More information about the bazaar mailing list