Note! yt has migrated exclusively to Mercurial for version control, and we are in the process of updating the documentation to reflect this.
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:
Inside the source distribution we also provide doc/how_to_develop_yt.txt, which has some tips on how to dive into the code base.
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. The unit test suite is not comprehensive, but it covers a substantial number of cases; before declaring victory, you should run the test suite. Typically, running only the lagos tests is necessary, as the cover the primary data handling mechanisms.
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.
Submission
If you do not have commit access to the repository, and you have fixed a bug that has been reported on the bug tracker, you can leave a comment on that bug with your patch, generated from the subversion repository:
cd $YT_SRC svn diff LIST_OF_FILES > patch
it's better to keep the LIST_OF_FILES as small as possible; try to weed out the files in the repository that aren't related. It is probably a good idea to fire off an email to the yt-dev email list mentioning the bug.
If the bug has not been reported on the bug tracker, you should feel free to open one! Alternatively, you can submit your patch to the pastebin and then notify the dev list that you have done so. If you're using mercurial on BitBucket, with the YT branch that is posted there, you can request a 'pull' and the patch will get migrated upstream by Matt.
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. The YT design philosophy is being codified in Matt's thesis; this thesis is due on June 2nd, but until then, the SciPy? proceedings paper should give an idea of how YT was designed. It's not completely consistent, but we're trying! We'd like to strive for sensible defaults with the option for customization, and to encapsulate objects as best as possible.
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 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!
