Introductory Document For New Developers

[Jan Hudec]

On Mon, Apr 03, 2006 at 18:38:12 +0800, Declan McGrath wrote:
> 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.

Best, and really only reasonable, place for such document is the Wiki
(bazaar-vcs.org). You can register there and put up the document. On the main
page, there is 'How can I Contribute' section near the bottom, where you
should link it. I think adding it is a good idea. Please try to link related
or already existing information on the wiki.

> Kind regards,
> Declan
> 

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

As you have already been told, you don't want to obtain a release, but rather
you want to branch the development branch. See http://bazaar-vcs.org/OfficialDownloads

> * 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! 

What are you talking about?!?! There is exactly one directory bzrlib (yes,
I do have current head checked out and I made sure there is exactly one). If
you run the setup.py script, then there will be more, but the one with
sources is obviously the one that exists in what you have downloaded.

>   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

There are only two files called 'bzr'. One of them is in contrib/bash, which
makes it rather obvious it's not the one you want. Of course the final binary
/could/ be generated. In this case it is not.

>   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)!

No. You want to run /all/ tests -- not just the blackbox ones. The API tests
will usually tell you much more useful information when you screw up.

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

There is exactly one test matching a pattern 'whitebox'. So you certainly
don't want that. Basically the argument is a pattern agains full names of the
tests to select which ones you want to run. You can limit yourself to tests
for particular subsystem while you hack on it and then only run the whole
suite once the subtest succeeds.

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

... and is exactly the point /from/ which it starts to be interesting. You
described the simple part in detail. The interesting information is, that
each user-level command is implemented by a class in bzrlib.builtins called
cmd_<command-name>.

-- 
						 Jan 'Bulb' Hudec <bulb at ucw.cz>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: Digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060404/783176c1/attachment.pgp