1. chickenmeatball
  2. yt

Source

yt / doc / how_to_develop_yt.txt

How To Develop yt
=================

We are very happy to accept patches, features, and bugfixes from any member of
the community!  yt is developed using mercurial, primarily because it enables
very easy and straightforward submission of changesets.  We're eager to hear
from you, and if you are developing yt, we encourage you to subscribe to the
developer mailing list:

http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org

Please feel free to hack around, commit changes, and send them upstream.  If
you're new to Mercurial, these three resources are pretty great for learning
the ins and outs:

   * http://hginit.com
   * http://hgbook.red-bean.com/read/
   * http://mercurial.selenic.com/

Keep in touch, and happy hacking!  We also provide doc/coding_styleguide.txt
and an example of a fiducial docstring in doc/docstring_example.txt.  Please
read them before hacking on the codebase, and feel free to email any of the
mailing lists for help with the codebase.

Licenses
--------

All code in yt should be under the GPL-3 (preferred) or a compatible license.

How To Get The Source Code
--------------------------

yt is hosted on BitBucket, and you can see all of the yt repositories at
http://hg.enzotools.org/ .  With the yt installation script you should have a
copy of Mercurial.  You can clone the repository like so:

   $ hg clone http://hg.enzotools.org/yt/

You can update to any branch or revision by executing the command:

   $ hg up -C some_revision_specifier

Specifying a branch name in the revspec will update to the latest revision on
that branch.  If you ran the installation script, you can tell Python to use a
different version of the library by executing:

   $ python2.6 setup.py develop

This will rebuild all C modules as well.

How To Submit Changes
---------------------

You can submit changes a couple different ways, but the easiest is to use the
"fork" mechanism on BitBucket.  Just go here:

http://hg.enzotools.org/yt/fork

and you're all set, ready to go.  You'll have to either clone a new copy of the
repository or edit .hg/hgrc to point to the location of your new fork, first,
though.

When you're ready to submit them to the main repository, simply go to:

http://hg.enzotools.org/yt/fork

Make sure you notify "yt_analysis" and put in a little description.  That'll
notify the core developers that you've got something ready to submit, and we
will review it an (hopefully!) merge it in.  If it goes well, you may end up
with push access to the main repository.

How To Read The Source Code
---------------------------

yt is organized into several sub-packages, each of which governs a different
conceptual regime.

   frontends
      This is where interfaces to codes are created.  Within each subdirectory of
      yt/frontends/ there must exist the following files, even if empty:

      * data_structures.py, where subclasses of AMRGridPatch, StaticOutput and
        AMRHierarchy are defined.
      * io.py, where a subclass of IOHandler is defined.
      * misc.py, where any miscellaneous functions or classes are defined.
      * definitions.py, where any definitions specific to the frontend are
        defined.  (i.e., header formats, etc.)

   visualization
      This is where all visualization modules are stored.  This includes plot
      collections, the volume rendering interface, and pixelization frontends.

   data_objects
      All objects that handle data, processed or unprocessed, not explicitly
      defined as visualization are located in here.  This includes the base
      classes for data regions, covering grids, time series, and so on.  This
      also includes derived fields and derived quantities.

   astro_objects
      This is where all objects that represent astrophysical objects should
      live -- for instance, galaxies, halos, disks, clusters and so on.  These
      can be expressive, provide astrophysical analysis functionality and will
      in general be more user-modifiable, user-tweakable, and much less of a
      black box that data_objects.

   analysis_modules
      This is where all mechanisms for processing data live.  This includes
      things like clump finding, halo profiling, halo finding, and so on.  This
      is something of a catchall, but it serves as a level of greater
      abstraction that simply data selection and modification.

   gui
      This is where all GUI components go.  Typically this will be some small
      tool used for one or two things, which contains a launching mechanism on
      the command line.

   utilities
      All broadly useful code that doesn't clearly fit in one of the other
      categories goes here.

How To Use Branching
--------------------

If you are planning on making a large change to the code base that may not be
ready for many commits, or if you are planning on breaking some functionality
and rewriting it, you are encouraged to create a new named branch.  You can
mark the current repository as a new named branch by executing:

   $ hg branch new_feature_name

The next commit and all subsequent commits will be contained within that named
branch.  At this point, add your branch here:

http://yt.enzotools.org/wiki/ExistingBranches

To merge changes in from another branch, you would execute:

   $ hg merge some_other_branch

Note also that you can use revision specifiers instead of "some_other_branch".
When you are ready to merge back into the main branch, execute this process:

   $ hg merge name_of_main_branch
   $ hg commit --close-branch
   $ hg up -C name_of_main_branch
   $ hg merge name_of_feature_branch
   $ hg commit

When you execute the merge you may have to resolve conflicts.  Once you resolve
conflicts in a file, you can mark it as resolved by doing:

   $ hg resolve -m path/to/conflicting/file.py

Please be careful when resolving conflicts in files.

Once your branch has been merged in, mark it as closed on the wiki page.