Introductory Document For New Developers

[Declan McGrath]

Hiya,

I'm new to bzr but really like what I see in the project. Hope to
contribute sometime soon - I'm currently trying to become more familiar
with the project.

I have found it a little confusing to work out how to get started so I
have written up a 'getting started' guide for developers new to bzr. As
I work my way through the code base I plan to add to it so that it may
help other newbie developers. Would you like to add it to bzr's doc/
directory? If you think this is worthwhile I'll keep adding to it,
otherwise I'll trash it.

Kind regards,
Declan

-------------- next part --------------
==========================
Intro to hacking on Bazaar
==========================
This is an overview of how do get hacking on a development working copy
of Bazaar. It does not represent how other Bazaar develop their code, but
if you're new to the project and would like to contribute it may help you
get up and running.

* Note: -X.x in the following guide should be replaced with the version 
  number of the bzr release that you have obtained. Replace as 
  appropriate when using the following instructions.
* cd to the bzr-X.x directory
  This is the directory that holds the working tree that you will want 
  to work on along with a million other things! The code for Bazaar is
  located in the 'bzrlib' directory. Sounds simple? But the first thing
  you notice if you look through the subdirectories of bzr-X.x is that
  there is a couple of different directories called bzrlib - oh dear! 
  Which one do I edit to make code changes? There are also numerous 
  occurrences of 'bzr' command in different places - as a developer 
  which one do I run to see my changes in action? In other words, what 
  is the entry point to the development version of the application? Well 
  here's the answers. For development purposes the entry point to bzr 
  application is the command 'bzr' in the top-level directory bzr-X.x. 
  This is the command that you run after making code changes to see the 
  effects of your changes. The files you edit to make code changes are 
  those located under the folder 'bzr-X.x/bzrlib'. So cd to this 
  directory and get hacking to contribute. If you'd like bzr command to 
  be updated to include your changes, then rerun setup as outlined in 
  the INSTALL file in the top-level directory.
* Test driven development is crucial to bzr development. Run
  bzr selftest -v blackbox
  This should run execute the bzr test scripts. Ensure that the bzr 
  command that you are running is the one in your working copy (not the 
  system installed command)!
* Summary of the basic Bazaar development process
  - Edit code files in bzr-X.x/bzrlib/
  - Add test cases to bzr-X.x/bzrlib/tests based on 
    bzr-X.x/bzrlib/selftest/testsampler.py
  - Run bzr or it's tests by running the following commands from the top
    level of your working copy directory,
    ./bzr OR
    ./bzr selftest -v blackbox OR
    ./bzr selftest -v whitebox
  - Repeat until the perfect new feature you're working on is coded!

Debugging Bazaar
================
This section will be written soon. Until then, try not to pull too much
hair out :)

Overview of different Bazaar commands (developers perspective)
=====================================================================
This section will be written soon too. Promise!

Basic Bazaar Program Control Flow
=================================
This is a quick overview of the code path taken on program execution.

* The entry point to the application is the bzr command which is located 
  in the top level directory. This carries out some basic prerequiste 
  system requirements checks.
* From here control passes to the method bzrlib.commands.main()
* main() does some initialisation before calling run_bzr_catch_errors()
  which in turn calls run_bzr(). run_bzr() is the 'real' main method, but
  this scenic route to calling it allows trappings for logging and error
  handling to be set up. From run_bzr() control is branched, depending on
  what command the user passed to bzr.

:: vim:tw=74:ai