How to Hack on YT

Hi there! So you want to hack around with YT, maybe fix some bugs, make some changes, add a feature or two? Great! We've tried to compile a couple of the most useful suggestions here, to get you started. But, there are a couple websites you might find of use:

• The pastebin, for snippets of code
• The yt-dev mailing list
• http://yt.enzotools.org/doc/advanced/developing.html, a developer guide for submitting source code

Fixing Bugs

There are typically three steps for fixing a bug. Identification, repair and notification.

Identification

This may require more than simply getting a traceback, examining it, and making changes to the source. Often, variables must be examined, source code stepped through, and so forth. Fortunately there are a couple tools in the YT toolbox for digging deeper.

The first is the insertion of an interactive interpreter at any place in the source code. If you're not sure what a variable holds, or if you want to make changes dynamically to the contents of a variable and then continue execution, you can insert this command:

insert_ipython()

and an IPython shell will be spawned at that location. Upon termination of the shell, execution resumes.

The second tool is pdb. Pdb is the Python Debugger, and it comes with the main python distribution; for more information on pdb, you should cosult the main python documentation at python.org. However, you can set pdb to spawn and examine the entire call stack at any point in one of two different ways:

import pdb; pdb.set_trace()

will import and call pdb at any point in the code. Alternatively, YT has a convenience function: if you want to have a function debugged every time it is called, you can 'decorate' it with the run_pdb decorator:

@run_pdb
def function_to_debug(...):

and when the function is called, execution will proceed through the debugger.

Repair

Before repairing and submitting a bug fix, it's important to check that your fix is not going to repair the bug you identified without introducing new bugs.

If you can write a unit test that demonstrates your bug, that fails before you fix the bug and passes after you have fixed it, please submit that as well. This is the preferred validation of bug fixes.

Design

If you're contributing new code, it's more likely to be accepted if you try to follow the object-oriented philosophy that we've tried to use in YT. See our ApJS paper

Coding Style

The style we attempt to adhere to is that of PEP-8. There are numerous violations throughout the code, but we're slowly trying to fix those as we come across them. New code should do its best to have:

• Objects should inherit from a base class or from "object"
• Private methods should be prefixed with _ and ultra-private methods should have __
• Classes should be capitalized, but methods should not be. Instead of camelcase, use underscores.
• ALWAYS use 4 spaces for indentation.

Language

Profanity or similar language is 'unacceptable' for inclusion. Before you commit any changes to any public repo, please strip any inappropriate language from comments, print statements, debug statements, and variable names.

Licensing

YT is [http://www.gnu.org/copyleft/gpl.html | GPL'd]. Your code must either by GPL'd or licensed in a compatible fashion.

Sign Your Code

If you contribute new source files, include a modified version of the standard header located throughout YT with your name and affiliation included. If you contribute substantially to an existing source file (new classes, new functionality) then add your name to the end of the list of authors of that file.

Happy hacking!

This revision is from 2012-01-27 18:31