1. Working with the Source Code

1. Working with the Source Code
Prev	Chapter 2. Getting Started	Next

1. Working with the Source Code

1.1. Getting the Source Code

If all that you would like to do is browse through the source code, then you can just go to the Trac/Subversion page.

The version control system used by Zenoss is Subversion. Subversion has excellent documentation in the form of an O'Reilly book. For the moment, we'll just provide the minimum number of commands to get started.

The absolute latest version of Zenoss can be accessed directly through the Subversion repository. This code should not be used for production purposes as there are changes actively being made which may not have been thoroughly tested.

From a command-line prompt, go to a directory where you would like to see the source code be delivered. Here's a sample command to get the source code:

$ svn co http://dev.zenoss.org/svn/trunk/Products

This will create a directory called Products in the current directory and checkout the source code. This repository is readable anonymously, so no credentials are required.

To see what other portions of the code are available, such as ZenPacks or support utilities, you can look using the following Subversion command:

$ svn ls http://dev.zenoss.org/svn/trunk

Other tools that can be used to view or checkout the source code for different platforms are available. See the Subversion web site for more details.

1.1.1. Getting Subversion for the Appliance

The rPath appliance does not ship with the svn binaries, but you can still obtain them.

Procedure 2.1. Installing Subversion on Appliances

Edit the /etc/conaryrc file.
- For the Community version, look for the line that looks like this:
```
installLabelPath zenoss-project.zenoss.loc@zenoss:core-2.3
```
  Change the above line to this (note that this should be all one line and has been modified to make it look better in print):
```
installLabelPath zenoss-project.zenoss.loc@zenoss:core-2.3
    conary.rpath.com@rpl:1
```
- For the Enterprise version, look for the line that looks like this:
```
installLabelPath zenoss-project.zenoss.loc@zenoss:enterprise-2.3
```
  Change the above line to this (note that this should be all one line and has been modified to make it look better in print):
```
installLabelPath zenoss-project.zenoss.loc@zenoss:enterprise-2.3
    conary.rpath.com@rpl:1
```
Now you should be able to obtain the subversion package by using the conary update command:
```
[root@localhost ~] conary update --resolve subversion
```

For more information about rPath commands, see their documentation wiki. There are also a set of blog entries Conary Uncorked has been put together by a dedicated rPath user that introduces some of the conary commands much more gently.

1.2. Keeping up-to-date with your checked-out code

The following command, issued from the base directory of where you checked out the Zenoss code, will update all code from that directory and all subdirectories and bring it up to date with what is current in the Subversion repository (and therefore apply all of the current patches to the code you checked out previously):

$ svn update

If you have modified any code in this directory, these changes will be merged with the latest code updates. If there are differences that Subversion cannot automatically resolve, Subversion will tell you that there is a problem by showing the updated file is in conflict (for example, showing a 'C' beside the file when you run svn status).

You can tell if you have modified any of the files in the checked-out directory by typing the following:

$ svn status

If you are only interested in modifying one file rather than everything, you can specify that one file:

$ svn udpate filename

1.3. Getting Patches

For issue tracking, bug reports and linking patches to bug reports, Zenoss uses Trac to manage issues. The Zenoss Trac server is found here.

You can click on the Search box on the top right-hand side and enter a search term to look for keywords in the tickets. This will then present you with the ability to search for changesets (ie Subversion revisions), trouble tickets, or the Wiki.

Alternatively, from the start page you can click on the Custom Query which will allow you to view the results from your customized query.

Once you have found a patch that applies to your system, you can use the zenpatch command in order to apply them to your system. (As mentioned previously, if you use the svn update commands, you will already be at the latest patched level.)

$ zenpatch revision_number

1.4. Style Guidelines

These following guidelines are targeted at Python files. HTML files, Zope Page Template (ZPT) files, shell scripts, etc should adhere to these as much as is reasonable and conventional in those languages. Currently, we follow Guido's Style Guide for Python Code which is detailed in PEP 8 (Python Enhancement Proposals).

Any style conventions that stray from PEP-8 should be annotated in this document.

1.4.1. Docstrings

Every method and function definition within Zenoss should include a docstring. The docstring is usually composed of two parts: the explanatory text and the doctest code. The explanation usually includes a description of all or most of the following aspects of the function:

The function's purpose
The context in which the function is usually called
What parameters it expects
What it returns
Any side effects of the function

This explanatory text should scale in size with the complexity and significance of the function.

The second part of the docstring is the doctest section. This is composed of zendmd commands and expected output from those commands. The commands are run as part of the testing process and output is compared to the output lines. This code serves two primary purposes. First it is a working example of how the function should be called and what it returns. Second it serves as a basic test to ensure the function is not horribly broken. This is not intended as a replacement for unit tests. Thorough testing of boundary cases and unusual situations still belongs in unit tests whereas the doctests are much simpler and more instructional in nature.

Docstrings begin on the line immediately following the function definition and are indented one level from the definition. The first and last lines of the docstring are three double quotes and a newline. One blank line separates the description from the epydoc section. epydoc can take specially formatted text in the docstrings and use them to create API documentation. The Zenoss API documentation is located on the Zenoss website and is updated every release.

Another blank line separates the epydoc section from the doctest section. The code for the function begins on the line immediately following the docstring. Example:

def TruncateStrings(longStrings, maxLength):
   """
   Foo truncates all the strings in a list to a maximum length.
   longStrings is any iterable object which returns zero or more
   strings.  maxLength is the length to which each element from
   longStrings should be truncated.

   @param longStrings: an iterable object which returns zero or more strings
   @type longStrings: Python iterable
   @param maxLength: max length of each element in longStrings
   @type maxLength: int
   @return: longStrings in the same order but possibly truncated
   @rtype: list
   @todo: Add more epydoc attributes!

   >>> from Products.SomeModule import TruncateStrings
   >>> TruncateStrings(['abcd', 'efg', 'hi', ''], 3)
   ['abc', 'efg', 'hi', '']
   >>> TruncateStrings([], 5)
   []
   """
   return [s[:maxLength] for s in longStrings]

The easiest way to create the doctest portion is from within zendmd. Except for the indentation, the docstring should exactly match commands and output from a zendmd session.

Use the available epydoc fields where they are applicable. Some of the useful common fields are:

Commonly-used epydoc fields

@param param_name: Describe the parameter
@type data_type: Data type of the parameter
@return: Describe the return value
@rtype: Data type of the return value
@permission: Zope permission that the method requires
@todo: Todo for this method

Note

Within the description section of the docstring, you may use the string DEPRECATED on its own line to denote that the method is deprecated.

1.5. Generating Diffs for new Fixes

Once you've determined how to fix something, or have found a way to add a feature, modify the source code in your checkout directory. Once that's complete, we just need to generate a diff starting from the base of the checkout directory.

To generate a diff of all files in the current directory and all subdirectories:

$ svn diff > mychanges.diff

To produce a diff for just a single file:

$ svn diff source_file > mychanges.diff

1.6. Submitting a Fix

Zenoss accepts user contributions using the following procedure:

Complete the form to allow Zenoss to accept your code.
Create a ticket in our ticketing system .
Add the keyword contribute to the ticket.
Attach your patch (in diff format) or code to the ticket.

Note

All contributions will be accepted under the terms of the Zenoss Contribution Agreement.

Prev	Up	Next
Chapter 2. Getting Started	Home	2. Development Toolchain Requirements

Developer's Guide