[yt-svn] commit/yt: 12 new changesets
commits-noreply at bitbucket.org
commits-noreply at bitbucket.org
Mon Nov 23 11:46:08 PST 2015
12 new commits in yt:
https://bitbucket.org/yt_analysis/yt/commits/0680472b1643/
Changeset: 0680472b1643
Branch: yt
User: ngoldbaum
Date: 2015-11-18 03:42:14+00:00
Summary: Moving the dev docs to a CONTRIBUTING file.
Affected #: 4 files
diff -r 90f900be7a36433fdd48941cae4bc91066ff5c76 -r 0680472b164304f6596dc04f5a6f37324a06236e CONTRIBUTING
--- /dev/null
+++ b/CONTRIBUTING
@@ -0,0 +1,732 @@
+How to Develop yt
+=================
+
+yt is a community project!
+
+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.
+
+.. note:: If you already know how to use the `mercurial version control system
+ <http://mercurial-scm.org>`_ and are comfortable with handling it yourself,
+ the quickest way to contribute to yt is to `fork us on BitBucket
+ <http://bitbucket.org/yt_analysis/yt/fork>`_, make your changes, push the
+ changes to your fork and issue a `pull request
+ <http://bitbucket.org/yt_analysis/yt/pull-requests>`_. The rest of this
+ document is just an explanation of how to do that.
+
+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/
+
+The commands that are essential for using mercurial include:
+
+* ``hg commit`` which commits changes in the working directory to the
+ repository, creating a new "changeset object."
+* ``hg add`` which adds a new file to be tracked by mercurial. This does
+ not change the working directory.
+* ``hg pull`` which pulls (from an optional path specifier) changeset
+ objects from a remote source. The working directory is not modified.
+* ``hg push`` which sends (to an optional path specifier) changeset objects
+ to a remote source. The working directory is not modified.
+* ``hg log`` which shows a log of all changeset objects in the current
+ repository. Use ``-G`` to show a graph of changeset objects and their
+ relationship.
+* ``hg update`` which (with an optional "revision" specifier) updates the
+ state of the working directory to match a changeset object in the
+ repository.
+* ``hg merge`` which combines two changesets to make a union of their lines
+ of development. This updates the working directory.
+* ``hg help`` which provides help for any mercurial command. For example, you
+ can learn more about the ``log`` command by doing ``hg help log``. Other useful
+ topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
+ ``hg help extensions``, and ``hg help revsets``.
+
+See :ref:`code-style-guide` for more information about coding style in yt and
+:ref:`docstrings` for an example docstring. Please read them before hacking on
+the codebase, and feel free to email any of the mailing lists for help with the
+codebase.
+
+Keep in touch, and happy hacking!
+
+.. _bootstrap-dev:
+
+Submitting Changes
+------------------
+
+We provide a brief introduction to submitting changes here. yt thrives on the
+strength of its communities ( http://arxiv.org/abs/1301.7064 has further
+discussion) and we encourage contributions from any user. While we do not
+discuss in detail version control, mercurial or the advanced usage of
+BitBucket, we do provide an outline of how to submit changes and we are happy
+to provide further assistance or guidance.
+
+Licensing
++++++++++
+
+yt has, with the 2.6 release, been `relicensed
+<http://blog.yt-project.org/post/Relicensing.html>`_ under the BSD 3-clause
+license. Previously versions were released under the GPLv3.
+
+All contributed code must be BSD-compatible. If you'd rather not license in
+this manner, but still want to contribute, please consider creating an external
+package, which we'll happily link to.
+
+.. _requirements-for-code-submission:
+
+Requirements for Code Submission
+++++++++++++++++++++++++++++++++
+
+Modifications to the code typically fall into one of three categories, each of
+which have different requirements for acceptance into the code base. These
+requirements are in place for a few reasons -- to make sure that the code is
+maintainable, testable, and that we can easily include information about
+changes in changelogs during the release procedure. (See `YTEP-0008
+<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
+detail.)
+
+* New Features
+
+ * New unit tests (possibly new answer tests) (See :ref:`testing`)
+ * Docstrings in the source code for the public API
+ * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
+ * Addition of cookbook recipe (See :ref:`writing_documentation`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Extension or Breakage of API in Existing Features
+
+ * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
+ * Update existing cookbook recipes (See :ref:`writing_documentation`)
+ * Modify of create new unit tests (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Bug fixes
+
+ * Unit test is encouraged, to ensure breakage does not happen again in the
+ future. (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+When submitting, you will be asked to make sure that your changes meet all of
+these requirements. They are pretty easy to meet, and we're also happy to help
+out with them. In :ref:`code-style-guide` there is a list of handy tips for
+how to structure and write your code.
+
+.. _mercurial-with-yt:
+
+How to Use Mercurial with yt
+++++++++++++++++++++++++++++
+
+This document doesn't cover detailed mercurial use, but on IRC we are happy to
+walk you through any troubles you might have. Here are some suggestions
+for using mercurial with yt:
+
+* Named branches are to be avoided. Try using bookmarks (``hg bookmark``) to
+ track work. (`More <http://mercurial.selenic.com/wiki/Bookmarks>`_)
+* Make sure you set a username in your ``~/.hgrc`` before you commit any
+ changes! All of the tutorials above will describe how to do this as one of
+ the very first steps.
+* When contributing changes, you might be asked to make a handful of
+ modifications to your source code. We'll work through how to do this with
+ you, and try to make it as painless as possible.
+* Please avoid deleting your yt forks, as that eliminates the code review
+ process from BitBucket's website.
+* In all likelihood, you only need one fork. To keep it in sync, you can
+ sync from the website. (See Bitbucket's `Blog Post
+ <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
+ about this.)
+* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
+ list.
+
+.. _building-yt:
+
+Building yt
++++++++++++
+
+If you have made changes to any C or Cython (``.pyx``) modules, you have to
+rebuild yt. If your changes have exclusively been to Python modules, you will
+not need to re-build, but (see below) you may need to re-install.
+
+If you are running from a clone that is executable in-place (i.e., has been
+installed via the installation script or you have run ``setup.py develop``) you
+can rebuild these modules by executing:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py develop
+
+If you have previously "installed" via ``setup.py install`` you have to
+re-install:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py install
+
+Only one of these two options is needed.
+
+.. _windows-developing:
+
+Developing yt on Windows
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you plan to develop yt on Windows, it is necessary to use the `MinGW
+<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
+Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
+installed from Anaconda as well. These can both be installed with a single command:
+
+.. code-block:: bash
+
+ $ conda install libpython mingw
+
+Additionally, the syntax for the setup command is slightly different; you must type:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 develop
+
+or
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 install
+
+.. _sharing-changes:
+
+Making and Sharing Changes
+++++++++++++++++++++++++++
+
+The simplest way to submit changes to yt is to do the following:
+
+* Build yt from the mercurial repository
+* Navigate to the root of the yt repository
+* Make some changes and commit them
+* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
+* Push the changesets to your fork
+* Issue a pull request.
+
+Here's a more detailed flowchart of how to submit changes.
+
+#. If you have used the installation script, the source code for yt can be
+ found in ``$YT_DEST/src/yt-hg``. Alternatively see
+ :ref:`source-installation` for instructions on how to build yt from the
+ mercurial repository. (Below, in :ref:`reading-source`, we describe how to
+ find items of interest.)
+#. Edit the source file you are interested in and
+ test your changes. (See :ref:`testing` for more information.)
+#. Fork yt on BitBucket. (This step only has to be done once.) You can do
+ this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
+ yt.
+#. Commit these changes, using ``hg commit``. This can take an argument
+ which is a series of filenames, if you have some changes you do not want
+ to commit.
+#. Remember that this is a large development effort and to keep the code
+ accessible to everyone, good documentation is a must. Add in source code
+ comments for what you are doing. Add in docstrings
+ if you are adding a new function or class or keyword to a function.
+ Add documentation to the appropriate section of the online docs so that
+ people other than yourself know how to use your new code.
+#. If your changes include new functionality or cover an untested area of the
+ code, add a test. (See :ref:`testing` for more information.) Commit
+ these changes as well.
+#. Push your changes to your new fork using the command::
+
+ hg push -r . https://bitbucket.org/YourUsername/yt/
+
+ If you end up doing considerable development, you can set an alias in the
+ file ``.hg/hgrc`` to point to this path.
+
+ .. note::
+ Note that the above approach uses HTTPS as the transfer protocol
+ between your machine and BitBucket. If you prefer to use SSH - or
+ perhaps you're behind a proxy that doesn't play well with SSL via
+ HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
+ the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
+ place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
+ For consistency, all commands we list in this document will use the HTTPS
+ protocol.
+
+ .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
+
+#. Issue a pull request at
+ https://bitbucket.org/YourUsername/yt/pull-request/new
+ A pull request is essentially just asking people to review and accept the
+ modifications you have made to your personal version of the code.
+
+
+During the course of your pull request you may be asked to make changes. These
+changes may be related to style issues, correctness issues, or even requesting
+tests. The process for responding to pull request code review is relatively
+straightforward.
+
+#. Make requested changes, or leave a comment indicating why you don't think
+ they should be made.
+#. Commit those changes to your local repository.
+#. Push the changes to your fork:
+
+ hg push https://bitbucket.org/YourUsername/yt/
+
+#. Your pull request will be automatically updated.
+
+.. _multiple-PRs:
+
+Working with Multiple BitBucket Pull Requests
++++++++++++++++++++++++++++++++++++++++++++++
+
+Once you become active developing for yt, you may be working on
+various aspects of the code or bugfixes at the same time. Currently,
+BitBucket's *modus operandi* for pull requests automatically updates
+your active pull request with every ``hg push`` of commits that are a
+descendant of the head of your pull request. In a normal workflow,
+this means that if you have an active pull request, make some changes
+locally for, say, an unrelated bugfix, then push those changes back to
+your fork in the hopes of creating a *new* pull request, you'll
+actually end up updating your current pull request!
+
+There are a few ways around this feature of BitBucket that will allow
+for multiple pull requests to coexist; we outline one such method
+below. We assume that you have a fork of yt at
+``http://bitbucket.org/YourUsername/Your_yt`` (see
+:ref:`sharing-changes` for instructions on creating a fork) and that
+you have an active pull request to the main repository.
+
+The main issue with starting another pull request is to make sure that
+your push to BitBucket doesn't go to the same head as your
+existing pull request and trigger BitBucket's auto-update feature.
+Here's how to get your local repository away from your current pull
+request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
+and your ``hgrc`` file:
+
+#. Set up a Mercurial path for the main yt repository (note this is a convenience
+ step and only needs to be done once). Add the following to your
+ ``Your_yt/.hg/hgrc``::
+
+ [paths]
+ upstream = https://bitbucket.org/yt_analysis/yt
+
+ This will create a path called ``upstream`` that is aliased to the URL of the
+ main yt repository.
+#. Now we'll use revsets_ to update your local repository to the tip of the
+ ``upstream`` path:
+
+ .. code-block:: bash
+
+ $ hg pull upstream
+ $ hg update -r "remote(tip,'upstream')"
+
+After the above steps, your local repository should be at the tip of
+the main yt repository. If you find yourself doing this a lot, it may
+be worth aliasing this task in your ``hgrc`` file by adding something like::
+
+ [alias]
+ myupdate = update -r "remote(tip,'upstream')"
+
+And then you can just issue ``hg myupdate`` to get at the tip of the main yt repository.
+
+Make sure you are on the branch you want to be on, and then you can
+make changes and ``hg commit`` them. If you prefer working with
+`bookmarks <http://mercurial.selenic.com/wiki/Bookmarks>`_, you may
+want to make a bookmark before committing your changes, such as ``hg
+bookmark mybookmark``.
+
+To push to your fork on BitBucket if you didn't use a bookmark, you issue the following:
+
+.. code-block:: bash
+
+ $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
+
+The ``-r .`` means "push only the commit I'm standing on and any ancestors." The
+``-f`` is to force Mecurial to do the push since we are creating a new remote head.
+
+Note that if you *did* use a bookmark, you don't have to force the push, but you do
+need to push the bookmark; in other words do the following instead of the above:
+
+.. code-block:: bash
+
+ $ hg push -B mybookmark https://bitbucket.org/YourUsername/Your_yt
+
+The ``-B`` means "publish my bookmark and any relevant changesets to the remote server."
+
+You can then go to the BitBucket interface and issue a new pull request based on
+your last changes, as usual.
+
+How To Get The Source Code For Editing
+--------------------------------------
+
+yt is hosted on BitBucket, and you can see all of the yt repositories at
+http://bitbucket.org/yt_analysis/. With the yt installation script you should have a
+copy of Mercurial for checking out pieces of code. Make sure you have followed
+the steps above for bootstrapping your development (to assure you have a
+bitbucket account, etc.)
+
+In order to modify the source code for yt, we ask that you make a "fork" of the
+main yt repository on bitbucket. A fork is simply an exact copy of the main
+repository (along with its history) that you will now own and can make
+modifications as you please. You can create a personal fork by visiting the yt
+bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in,
+you should see an option near the top right labeled "fork". Click this option,
+and then click the fork repository button on the subsequent page. You now have
+a forked copy of the yt repository for your own personal modification.
+
+This forked copy exists on the bitbucket repository, so in order to access
+it locally, follow the instructions at the top of that webpage for that
+forked repository, namely run at a local command line:
+
+.. code-block:: bash
+
+ $ hg clone http://bitbucket.org/<USER>/<REPOSITORY_NAME>
+
+This downloads that new forked repository to your local machine, so that you
+can access it, read it, make modifications, etc. It will put the repository in
+a local directory of the same name as the repository in the current working
+directory. You can see any past state of the code by using the hg log command.
+For example, the following command would show you the last 5 changesets
+(modifications to the code) that were submitted to that repository.
+
+.. code-block:: bash
+
+ $ cd <REPOSITORY_NAME>
+ $ hg log -l 5
+
+Using the revision specifier (the number or hash identifier next to each
+changeset), you can update the local repository to any past state of the
+code (a previous changeset or version) by executing the command:
+
+.. code-block:: bash
+
+ $ hg up revision_specifier
+
+Lastly, if you want to use this new downloaded version of your yt repository as
+the *active* version of yt on your computer (i.e. the one which is executed when
+you run yt from the command line or the one that is loaded when you do ``import
+yt``), then you must "activate" it using the following commands from within the
+repository directory.
+
+.. code-block:: bash
+
+ $ cd <REPOSITORY_NAME>
+ $ python2.7 setup.py develop
+
+This will rebuild all C modules as well.
+
+.. _reading-source:
+
+How To Read The Source Code
+---------------------------
+
+If you just want to *look* at the source code, you may already have it on your
+computer. If you build yt using the install script, the source is available at
+``$YT_DEST/src/yt-hg``. See :ref:`source-installation` for more details about
+to obtain the yt source code if you did not build yt using the install
+script.
+
+The root directory of the yt mercurial repository contains a number of
+subdirectories with different components of the code. Most of the yt source
+code is contained in the yt subdirectory. This directory its self contains
+the following subdirectories:
+
+``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, Dataset
+ and AMRHierarchy are defined.
+ * ``io.py``, where a subclass of IOHandler is defined.
+ * ``fields.py``, where fields we expect to find in datasets are 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.)
+
+``fields``
+ This is where all of the derived fields that ship with yt are defined.
+
+``geometry``
+ This is where geometric helpler routines are defined. Handlers
+ for grid and oct data, as well as helpers for coordinate transformations
+ can be found here.
+
+``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.
+
+``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.
+
+``extern``
+ Bundled external modules (i.e. code that was not written by one of
+ the yt authors but that yt depends on) lives here.
+
+
+If you're looking for a specific file or function in the yt source code, use
+the unix find command:
+
+.. code-block:: bash
+
+ $ find <DIRECTORY_TREE_TO_SEARCH> -name '<FILENAME>'
+
+The above command will find the FILENAME in any subdirectory in the
+DIRECTORY_TREE_TO_SEARCH. Alternatively, if you're looking for a function
+call or a keyword in an unknown file in a directory tree, try:
+
+.. code-block:: bash
+
+ $ grep -R <KEYWORD_TO_FIND><DIRECTORY_TREE_TO_SEARCH>
+
+This can be very useful for tracking down functions in the yt source.
+
+Testing
+-------
+
+When adding new features or fixing bugs, please make sure that you add
+tests. When fixing bugs, this ensures the bug cannot reappear in the future, and
+also helps if we want to make major changes to yt internals.
+
+To learn more details about yt tests, see `the yt testing guide
+<http://yt-project.org/doc/developing/testing.html>`_.
+
+.. _code-style-guide:
+
+Style Guide for Coding in yt
+============================
+
+Below are a list of rules for coding style in yt. Some of these rules are
+suggestions are not explicitly enforced, while some are enforced via automated
+testing. The yt project uses a subset of the rules checked by ``flake8`` to
+verify our code. The ``flake8`` tool is a combination of the ``pyflakes`` and
+``pep8`` tools. To check the coding style of your contributions locally you will
+need to install the ``flake8`` tool from ``pip``:
+
+ $ pip install flake8
+
+And then navigate to the root of the yt repository and run ``flake8`` on the
+``yt`` folder:
+
+ $ cd $YT_HG
+ $ flake8 ./yt
+
+This will print out any ``flake8`` errors or warnings that your newly added code
+triggers. The errors in your newly added code because we have already cleaned up
+the yt codebase. Note that this will only trigger a subset of the full
+``flake8`` error and warning list, since we explicitly blacklist a large number
+of the full list of rules that are checked by ``flake8`` by default.
+
+Coding Style Guide
+------------------
+
+ * In general, follow PEP-8 guidelines.
+ http://www.python.org/dev/peps/pep-0008/
+ * Classes are ``ConjoinedCapitals``, methods and functions are
+ ``lowercase_with_underscores``.
+ * Use 4 spaces, not tabs, to represent indentation.
+ * Line widths should not be more than 80 characters.
+ * Do not use nested classes unless you have a very good reason to, such as
+ requiring a namespace or class-definition modification. Classes should live
+ at the top level. ``__metaclass__`` is exempt from this.
+ * Do not use unnecessary parenthesis in conditionals. ``if((something) and
+ (something_else))`` should be rewritten as
+ ``if something and something_else``. Python is more forgiving than C.
+ * Avoid copying memory when possible. For example, don't do
+ ``a = a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3``
+ should be ``np.multiply(a, 3, a)``.
+ * In general, avoid all double-underscore method names: ``__something`` is
+ usually unnecessary.
+ * When writing a subclass, use the super built-in to access the super class,
+ rather than explicitly. Ex: ``super(SpecialGridSubclass, self).__init__()``
+ rather than ``SpecialGrid.__init__()``.
+ * Docstrings should describe input, output, behavior, and any state changes
+ that occur on an object. See the file ``doc/docstring_example.txt`` for a
+ fiducial example of a docstring.
+ * Use only one top-level import per line. Unless there is a good reason not to,
+ imports should happen at the top of the file, after the copyright blurb.
+ * Never compare with ``True`` or ``False`` using ``==`` or ``!=``, always use
+ ``is`` or ``is not``.
+ * If you are comparing with a numpy boolean array, just refer to the array.
+ Ex: do ``np.all(array)`` instead of ``np.all(array == True)``.
+ * Never comapre with None using ``==`` or ``!=``, use ``is None`` or
+ ``is not None``.
+ * Use ``statement is not True`` instead of ``not statement is True``
+ * Only one statement per line, do not use semicolons to put two or more
+ statements on a single line.
+ * Only declare local variables if they will be used later. If you do not use the
+ return value of a function, do not store it in a variable.
+ * Add tests for new functionality. When fixing a bug, consider adding a test to
+ prevent the bug from recurring.
+
+API Guide
+---------
+
+ * Do not use ``from some_module import *``
+ * Internally, only import from source files directly -- instead of:
+
+ ``from yt.visualization.api import ProjectionPlot``
+
+ do:
+
+ ``from yt.visualization.plot_window import ProjectionPlot``
+
+ * Import symbols from the module where they are defined, avoid transitive
+ imports.
+ * Import standard library modules, functions, and classes from builtins, do not
+ import them from other yt files.
+ * Numpy is to be imported as ``np``.
+ * Do not use too many keyword arguments. If you have a lot of keyword
+ arguments, then you are doing too much in ``__init__`` and not enough via
+ parameter setting.
+ * In function arguments, place spaces before commas. ``def something(a,b,c)``
+ should be ``def something(a, b, c)``.
+ * Don't create a new class to replicate the functionality of an old class --
+ replace the old class. Too many options makes for a confusing user
+ experience.
+ * Parameter files external to yt are a last resort.
+ * The usage of the ``**kwargs`` construction should be avoided. If they cannot
+ be avoided, they must be explained, even if they are only to be passed on to
+ a nested function.
+
+.. _docstrings
+
+Docstrings
+----------
+
+The following is an example docstring. You can use it as a template for
+docstrings in your code and as a guide for how we expect docstrings to look and
+the level of detail we are looking for. Note that we use NumPy style docstrings
+written in `Sphinx restructured text format <http://sphinx-doc.org/rest.html>`_.
+
+ r"""A one-line summary that does not use variable names or the
+ function name.
+
+ Several sentences providing an extended description. Refer to
+ variables using back-ticks, e.g. ``var``.
+
+ Parameters
+ ----------
+ var1 : array_like
+ Array_like means all those objects -- lists, nested lists, etc. --
+ that can be converted to an array. We can also refer to
+ variables like `var1`.
+ var2 : int
+ The type above can either refer to an actual Python type
+ (e.g. ``int``), or describe the type of the variable in more
+ detail, e.g. ``(N,) ndarray`` or ``array_like``.
+ Long_variable_name : {'hi', 'ho'}, optional
+ Choices in brackets, default first when optional.
+
+ Returns
+ -------
+ describe : type
+ Explanation
+ output : type
+ Explanation
+ tuple : type
+ Explanation
+ items : type
+ even more explaining
+
+ Other Parameters
+ ----------------
+ only_seldom_used_keywords : type
+ Explanation
+ common_parameters_listed_above : type
+ Explanation
+
+ Raises
+ ------
+ BadException
+ Because you shouldn't have done that.
+
+ See Also
+ --------
+ otherfunc : relationship (optional)
+ newfunc : Relationship (optional), which could be fairly long, in which
+ case the line wraps here.
+ thirdfunc, fourthfunc, fifthfunc
+
+ Notes
+ -----
+ Notes about the implementation algorithm (if needed).
+
+ This can have multiple paragraphs.
+
+ You may include some math:
+
+ .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+ And even use a greek symbol like :math:`omega` inline.
+
+ References
+ ----------
+ Cite the relevant literature, e.g. [1]_. You may also cite these
+ references in the notes section above.
+
+ .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+ expert systems and adaptive co-kriging for environmental habitat
+ modelling of the Highland Haggis using object-oriented, fuzzy-logic
+ and neural-network techniques," Computers & Geosciences, vol. 22,
+ pp. 585-588, 1996.
+
+ Examples
+ --------
+ These are written in doctest format, and should illustrate how to
+ use the function. Use the variables 'ds' for the dataset, 'pc' for
+ a plot collection, 'c' for a center, and 'L' for a vector.
+
+ >>> a=[1,2,3]
+ >>> print [x + 3 for x in a]
+ [4, 5, 6]
+ >>> print "a\n\nb"
+ a
+ b
+
+ """
+
+
+Variable Names and Enzo-isms
+----------------------------
+Avoid Enzo-isms. This includes but is not limited to:
+
+ * Hard-coding parameter names that are the same as those in Enzo. The
+ following translation table should be of some help. Note that the
+ parameters are now properties on a ``Dataset`` subclass: you access them
+ like ds.refine_by .
+
+ - ``RefineBy `` => `` refine_by``
+ - ``TopGridRank `` => `` dimensionality``
+ - ``TopGridDimensions `` => `` domain_dimensions``
+ - ``InitialTime `` => `` current_time``
+ - ``DomainLeftEdge `` => `` domain_left_edge``
+ - ``DomainRightEdge `` => `` domain_right_edge``
+ - ``CurrentTimeIdentifier `` => `` unique_identifier``
+ - ``CosmologyCurrentRedshift `` => `` current_redshift``
+ - ``ComovingCoordinates `` => `` cosmological_simulation``
+ - ``CosmologyOmegaMatterNow `` => `` omega_matter``
+ - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
+ - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
+
+ * Do not assume that the domain runs from 0 .. 1. This is not true
+ everywhere.
+ * Variable names should be short but descriptive.
+ * No globals!
+
diff -r 90f900be7a36433fdd48941cae4bc91066ff5c76 -r 0680472b164304f6596dc04f5a6f37324a06236e coding_styleguide.txt
--- a/coding_styleguide.txt
+++ /dev/null
@@ -1,101 +0,0 @@
-Style Guide for Coding in yt
-============================
-
-Coding Style Guide
-------------------
-
- * In general, follow PEP-8 guidelines.
- http://www.python.org/dev/peps/pep-0008/
- * Classes are ``ConjoinedCapitals``, methods and functions are
- ``lowercase_with_underscores``.
- * Use 4 spaces, not tabs, to represent indentation.
- * Line widths should not be more than 80 characters.
- * Do not use nested classes unless you have a very good reason to, such as
- requiring a namespace or class-definition modification. Classes should live
- at the top level. ``__metaclass__`` is exempt from this.
- * Do not use unnecessary parenthesis in conditionals. ``if((something) and
- (something_else))`` should be rewritten as
- ``if something and something_else``. Python is more forgiving than C.
- * Avoid copying memory when possible. For example, don't do
- ``a = a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3``
- should be ``np.multiply(a, 3, a)``.
- * In general, avoid all double-underscore method names: ``__something`` is
- usually unnecessary.
- * When writing a subclass, use the super built-in to access the super class,
- rather than explicitly. Ex: ``super(SpecialGridSubclass, self).__init__()``
- rather than ``SpecialGrid.__init__()``.
- * Docstrings should describe input, output, behavior, and any state changes
- that occur on an object. See the file ``doc/docstring_example.txt`` for a
- fiducial example of a docstring.
- * Use only one top-level import per line. Unless there is a good reason not to,
- imports should happen at the top of the file, after the copyright blurb.
- * Never compare with ``True`` or ``False`` using ``==`` or ``!=``, always use
- ``is`` or ``is not``.
- * If you are comparing with a numpy boolean array, just refer to the array.
- Ex: do ``np.all(array)`` instead of ``np.all(array == True)``.
- * Never comapre with None using ``==`` or ``!=``, use ``is None`` or
- ``is not None``.
- * Use ``statement is not True`` instead of ``not statement is True``
- * Only one statement per line, do not use semicolons to put two or more
- statements on a single line.
- * Only declare local variables if they will be used later. If you do not use the
- return value of a function, do not store it in a variable.
- * Add tests for new functionality. When fixing a bug, consider adding a test to
- prevent the bug from recurring.
-
-API Guide
----------
-
- * Do not use ``from some_module import *``
- * Internally, only import from source files directly -- instead of:
-
- ``from yt.visualization.api import ProjectionPlot``
-
- do:
-
- ``from yt.visualization.plot_window import ProjectionPlot``
-
- * Import symbols from the module where they are defined, avoid transitive
- imports.
- * Import standard library modules, functions, and classes from builtins, do not
- import them from other yt files.
- * Numpy is to be imported as ``np``.
- * Do not use too many keyword arguments. If you have a lot of keyword
- arguments, then you are doing too much in ``__init__`` and not enough via
- parameter setting.
- * In function arguments, place spaces before commas. ``def something(a,b,c)``
- should be ``def something(a, b, c)``.
- * Don't create a new class to replicate the functionality of an old class --
- replace the old class. Too many options makes for a confusing user
- experience.
- * Parameter files external to yt are a last resort.
- * The usage of the ``**kwargs`` construction should be avoided. If they cannot
- be avoided, they must be explained, even if they are only to be passed on to
- a nested function.
-
-Variable Names and Enzo-isms
-----------------------------
-Avoid Enzo-isms. This includes but is not limited to:
-
- * Hard-coding parameter names that are the same as those in Enzo. The
- following translation table should be of some help. Note that the
- parameters are now properties on a ``Dataset`` subclass: you access them
- like ds.refine_by .
-
- - ``RefineBy `` => `` refine_by``
- - ``TopGridRank `` => `` dimensionality``
- - ``TopGridDimensions `` => `` domain_dimensions``
- - ``InitialTime `` => `` current_time``
- - ``DomainLeftEdge `` => `` domain_left_edge``
- - ``DomainRightEdge `` => `` domain_right_edge``
- - ``CurrentTimeIdentifier `` => `` unique_identifier``
- - ``CosmologyCurrentRedshift `` => `` current_redshift``
- - ``ComovingCoordinates `` => `` cosmological_simulation``
- - ``CosmologyOmegaMatterNow `` => `` omega_matter``
- - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
- - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
-
- * Do not assume that the domain runs from 0 .. 1. This is not true
- everywhere.
- * Variable names should be short but descriptive.
- * No globals!
diff -r 90f900be7a36433fdd48941cae4bc91066ff5c76 -r 0680472b164304f6596dc04f5a6f37324a06236e doc/docstring_example.txt
--- a/doc/docstring_example.txt
+++ b/doc/docstring_example.txt
@@ -1,86 +0,0 @@
- r"""A one-line summary that does not use variable names or the
- function name.
-
- Several sentences providing an extended description. Refer to
- variables using back-ticks, e.g. `var`.
-
- Parameters
- ----------
- var1 : array_like
- Array_like means all those objects -- lists, nested lists, etc. --
- that can be converted to an array. We can also refer to
- variables like `var1`.
- var2 : int
- The type above can either refer to an actual Python type
- (e.g. ``int``), or describe the type of the variable in more
- detail, e.g. ``(N,) ndarray`` or ``array_like``.
- Long_variable_name : {'hi', 'ho'}, optional
- Choices in brackets, default first when optional.
-
- Returns
- -------
- describe : type
- Explanation
- output : type
- Explanation
- tuple : type
- Explanation
- items : type
- even more explaining
-
- Other Parameters
- ----------------
- only_seldom_used_keywords : type
- Explanation
- common_parameters_listed_above : type
- Explanation
-
- Raises
- ------
- BadException
- Because you shouldn't have done that.
-
- See Also
- --------
- otherfunc : relationship (optional)
- newfunc : Relationship (optional), which could be fairly long, in which
- case the line wraps here.
- thirdfunc, fourthfunc, fifthfunc
-
- Notes
- -----
- Notes about the implementation algorithm (if needed).
-
- This can have multiple paragraphs.
-
- You may include some math:
-
- .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
-
- And even use a greek symbol like :math:`omega` inline.
-
- References
- ----------
- Cite the relevant literature, e.g. [1]_. You may also cite these
- references in the notes section above.
-
- .. [1] O. McNoleg, "The integration of GIS, remote sensing,
- expert systems and adaptive co-kriging for environmental habitat
- modelling of the Highland Haggis using object-oriented, fuzzy-logic
- and neural-network techniques," Computers & Geosciences, vol. 22,
- pp. 585-588, 1996.
-
- Examples
- --------
- These are written in doctest format, and should illustrate how to
- use the function. Use the variables 'ds' for the dataset, 'pc' for
- a plot collection, 'c' for a center, and 'L' for a vector.
-
- >>> a=[1,2,3]
- >>> print [x + 3 for x in a]
- [4, 5, 6]
- >>> print "a\n\nb"
- a
- b
-
- """
diff -r 90f900be7a36433fdd48941cae4bc91066ff5c76 -r 0680472b164304f6596dc04f5a6f37324a06236e doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -1,497 +1,3 @@
.. _contributing-code:
-How to Develop yt
-=================
-
-.. note:: If you already know how to use version control and are comfortable
- with handling it yourself, the quickest way to contribute to yt is to `fork
- us on BitBucket <http://bitbucket.org/yt_analysis/yt/fork>`_, `make your changes
- <http://mercurial.selenic.com/>`_, and issue a `pull request
- <http://bitbucket.org/yt_analysis/yt/pull-requests>`_. The rest of this document is just an
- explanation of how to do that.
-
-yt is a community project!
-
-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/
-
-The commands that are essential for using mercurial include:
-
-* ``hg commit`` which commits changes in the working directory to the
- repository, creating a new "changeset object."
-* ``hg add`` which adds a new file to be tracked by mercurial. This does
- not change the working directory.
-* ``hg pull`` which pulls (from an optional path specifier) changeset
- objects from a remote source. The working directory is not modified.
-* ``hg push`` which sends (to an optional path specifier) changeset objects
- to a remote source. The working directory is not modified.
-* ``hg log`` which shows a log of all changeset objects in the current
- repository. Use ``-g`` to show a graph of changeset objects and their
- relationship.
-* ``hg update`` which (with an optional "revision" specifier) updates the
- state of the working directory to match a changeset object in the
- repository.
-* ``hg merge`` which combines two changesets to make a union of their lines
- of development. This updates the working directory.
-
-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.
-
-.. _bootstrap-dev:
-
-Submitting Changes
-------------------
-
-We provide a brief introduction to submitting changes here. yt thrives on the
-strength of its communities ( http://arxiv.org/abs/1301.7064 has further
-discussion) and we encourage contributions from any user. While we do not
-discuss in detail version control, mercurial or the advanced usage of
-BitBucket, we do provide an outline of how to submit changes and we are happy
-to provide further assistance or guidance.
-
-Licensing
-+++++++++
-
-yt has, with the 2.6 release, been `relicensed
-<http://blog.yt-project.org/post/Relicensing.html>`_ under the BSD 3-clause
-license. Previously versions were released under the GPLv3.
-
-All contributed code must be BSD-compatible. If you'd rather not license in
-this manner, but still want to contribute, please consider creating an external
-package, which we'll happily link to.
-
-.. _requirements-for-code-submission:
-
-Requirements for Code Submission
-++++++++++++++++++++++++++++++++
-
-Modifications to the code typically fall into one of three categories, each of
-which have different requirements for acceptance into the code base. These
-requirements are in place for a few reasons -- to make sure that the code is
-maintainable, testable, and that we can easily include information about
-changes in changelogs during the release procedure. (See `YTEP-0008
-<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
-detail.)
-
-* New Features
-
- * New unit tests (possibly new answer tests) (See :ref:`testing`)
- * Docstrings in the source code for the public API
- * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
- * Addition of cookbook recipe (See :ref:`writing_documentation`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Extension or Breakage of API in Existing Features
-
- * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
- * Update existing cookbook recipes (See :ref:`writing_documentation`)
- * Modify of create new unit tests (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Bug fixes
-
- * Unit test is encouraged, to ensure breakage does not happen again in the
- future. (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-When submitting, you will be asked to make sure that your changes meet all of
-these requirements. They are pretty easy to meet, and we're also happy to help
-out with them. In :ref:`code-style-guide` there is a list of handy tips for
-how to structure and write your code.
-
-.. _mercurial-with-yt:
-
-How to Use Mercurial with yt
-++++++++++++++++++++++++++++
-
-This document doesn't cover detailed mercurial use, but on IRC we are happy to
-walk you through any troubles you might have. Here are some suggestions
-for using mercurial with yt:
-
-* Named branches are to be avoided. Try using bookmarks (``hg bookmark``) to
- track work. (`More <http://mercurial.selenic.com/wiki/Bookmarks>`_)
-* Make sure you set a username in your ``~/.hgrc`` before you commit any
- changes! All of the tutorials above will describe how to do this as one of
- the very first steps.
-* When contributing changes, you might be asked to make a handful of
- modifications to your source code. We'll work through how to do this with
- you, and try to make it as painless as possible.
-* Please avoid deleting your yt forks, as that eliminates the code review
- process from BitBucket's website.
-* In all likelihood, you only need one fork. To keep it in sync, you can
- sync from the website. (See Bitbucket's `Blog Post
- <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
- about this.)
-* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
- list.
-
-.. _building-yt:
-
-Building yt
-+++++++++++
-
-If you have made changes to any C or Cython (``.pyx``) modules, you have to
-rebuild yt. If your changes have exclusively been to Python modules, you will
-not need to re-build, but (see below) you may need to re-install.
-
-If you are running from a clone that is executable in-place (i.e., has been
-installed via the installation script or you have run ``setup.py develop``) you
-can rebuild these modules by executing:
-
-.. code-block:: bash
-
- $ python2.7 setup.py develop
-
-If you have previously "installed" via ``setup.py install`` you have to
-re-install:
-
-.. code-block:: bash
-
- $ python2.7 setup.py install
-
-Only one of these two options is needed.
-
-.. _windows-developing:
-
-Developing yt on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you plan to develop yt on Windows, it is necessary to use the `MinGW
-<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
-Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
-installed from Anaconda as well. These can both be installed with a single command:
-
-.. code-block:: bash
-
- $ conda install libpython mingw
-
-Additionally, the syntax for the setup command is slightly different; you must type:
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 develop
-
-or
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 install
-
-.. _sharing-changes:
-
-Making and Sharing Changes
-++++++++++++++++++++++++++
-
-The simplest way to submit changes to yt is to do the following:
-
-* Build yt from the mercurial repository
-* Navigate to the root of the yt repository
-* Make some changes and commit them
-* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
-* Push the changesets to your fork
-* Issue a pull request.
-
-Here's a more detailed flowchart of how to submit changes.
-
-#. If you have used the installation script, the source code for yt can be
- found in ``$YT_DEST/src/yt-hg``. Alternatively see
- :ref:`source-installation` for instructions on how to build yt from the
- mercurial repository. (Below, in :ref:`reading-source`, we describe how to
- find items of interest.)
-#. Edit the source file you are interested in and
- test your changes. (See :ref:`testing` for more information.)
-#. Fork yt on BitBucket. (This step only has to be done once.) You can do
- this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
- yt.
-#. Commit these changes, using ``hg commit``. This can take an argument
- which is a series of filenames, if you have some changes you do not want
- to commit.
-#. Remember that this is a large development effort and to keep the code
- accessible to everyone, good documentation is a must. Add in source code
- comments for what you are doing. Add in docstrings
- if you are adding a new function or class or keyword to a function.
- Add documentation to the appropriate section of the online docs so that
- people other than yourself know how to use your new code.
-#. If your changes include new functionality or cover an untested area of the
- code, add a test. (See :ref:`testing` for more information.) Commit
- these changes as well.
-#. Push your changes to your new fork using the command::
-
- hg push -r . https://bitbucket.org/YourUsername/yt/
-
- If you end up doing considerable development, you can set an alias in the
- file ``.hg/hgrc`` to point to this path.
-
- .. note::
- Note that the above approach uses HTTPS as the transfer protocol
- between your machine and BitBucket. If you prefer to use SSH - or
- perhaps you're behind a proxy that doesn't play well with SSL via
- HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
- the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
- place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
- For consistency, all commands we list in this document will use the HTTPS
- protocol.
-
- .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
-
-#. Issue a pull request at
- https://bitbucket.org/YourUsername/yt/pull-request/new
- A pull request is essentially just asking people to review and accept the
- modifications you have made to your personal version of the code.
-
-
-During the course of your pull request you may be asked to make changes. These
-changes may be related to style issues, correctness issues, or even requesting
-tests. The process for responding to pull request code review is relatively
-straightforward.
-
-#. Make requested changes, or leave a comment indicating why you don't think
- they should be made.
-#. Commit those changes to your local repository.
-#. Push the changes to your fork:
-
- hg push https://bitbucket.org/YourUsername/yt/
-
-#. Your pull request will be automatically updated.
-
-.. _multiple-PRs:
-
-Working with Multiple BitBucket Pull Requests
-+++++++++++++++++++++++++++++++++++++++++++++
-
-Once you become active developing for yt, you may be working on
-various aspects of the code or bugfixes at the same time. Currently,
-BitBucket's *modus operandi* for pull requests automatically updates
-your active pull request with every ``hg push`` of commits that are a
-descendant of the head of your pull request. In a normal workflow,
-this means that if you have an active pull request, make some changes
-locally for, say, an unrelated bugfix, then push those changes back to
-your fork in the hopes of creating a *new* pull request, you'll
-actually end up updating your current pull request!
-
-There are a few ways around this feature of BitBucket that will allow
-for multiple pull requests to coexist; we outline one such method
-below. We assume that you have a fork of yt at
-``http://bitbucket.org/YourUsername/Your_yt`` (see
-:ref:`sharing-changes` for instructions on creating a fork) and that
-you have an active pull request to the main repository.
-
-The main issue with starting another pull request is to make sure that
-your push to BitBucket doesn't go to the same head as your
-existing pull request and trigger BitBucket's auto-update feature.
-Here's how to get your local repository away from your current pull
-request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
-and your ``hgrc`` file:
-
-#. Set up a Mercurial path for the main yt repository (note this is a convenience
- step and only needs to be done once). Add the following to your
- ``Your_yt/.hg/hgrc``::
-
- [paths]
- upstream = https://bitbucket.org/yt_analysis/yt
-
- This will create a path called ``upstream`` that is aliased to the URL of the
- main yt repository.
-#. Now we'll use revsets_ to update your local repository to the tip of the
- ``upstream`` path:
-
- .. code-block:: bash
-
- $ hg pull upstream
- $ hg update -r "remote(tip,'upstream')"
-
-After the above steps, your local repository should be at the tip of
-the main yt repository. If you find yourself doing this a lot, it may
-be worth aliasing this task in your ``hgrc`` file by adding something like::
-
- [alias]
- myupdate = update -r "remote(tip,'upstream')"
-
-And then you can just issue ``hg myupdate`` to get at the tip of the main yt repository.
-
-Make sure you are on the branch you want to be on, and then you can
-make changes and ``hg commit`` them. If you prefer working with
-`bookmarks <http://mercurial.selenic.com/wiki/Bookmarks>`_, you may
-want to make a bookmark before committing your changes, such as ``hg
-bookmark mybookmark``.
-
-To push to your fork on BitBucket if you didn't use a bookmark, you issue the following:
-
-.. code-block:: bash
-
- $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
-
-The ``-r .`` means "push only the commit I'm standing on and any ancestors." The
-``-f`` is to force Mecurial to do the push since we are creating a new remote head.
-
-Note that if you *did* use a bookmark, you don't have to force the push, but you do
-need to push the bookmark; in other words do the following instead of the above:
-
-.. code-block:: bash
-
- $ hg push -B mybookmark https://bitbucket.org/YourUsername/Your_yt
-
-The ``-B`` means "publish my bookmark and any relevant changesets to the remote server."
-
-You can then go to the BitBucket interface and issue a new pull request based on
-your last changes, as usual.
-
-How To Get The Source Code For Editing
---------------------------------------
-
-yt is hosted on BitBucket, and you can see all of the yt repositories at
-http://bitbucket.org/yt_analysis/. With the yt installation script you should have a
-copy of Mercurial for checking out pieces of code. Make sure you have followed
-the steps above for bootstrapping your development (to assure you have a
-bitbucket account, etc.)
-
-In order to modify the source code for yt, we ask that you make a "fork" of the
-main yt repository on bitbucket. A fork is simply an exact copy of the main
-repository (along with its history) that you will now own and can make
-modifications as you please. You can create a personal fork by visiting the yt
-bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in,
-you should see an option near the top right labeled "fork". Click this option,
-and then click the fork repository button on the subsequent page. You now have
-a forked copy of the yt repository for your own personal modification.
-
-This forked copy exists on the bitbucket repository, so in order to access
-it locally, follow the instructions at the top of that webpage for that
-forked repository, namely run at a local command line:
-
-.. code-block:: bash
-
- $ hg clone http://bitbucket.org/<USER>/<REPOSITORY_NAME>
-
-This downloads that new forked repository to your local machine, so that you
-can access it, read it, make modifications, etc. It will put the repository in
-a local directory of the same name as the repository in the current working
-directory. You can see any past state of the code by using the hg log command.
-For example, the following command would show you the last 5 changesets
-(modifications to the code) that were submitted to that repository.
-
-.. code-block:: bash
-
- $ cd <REPOSITORY_NAME>
- $ hg log -l 5
-
-Using the revision specifier (the number or hash identifier next to each
-changeset), you can update the local repository to any past state of the
-code (a previous changeset or version) by executing the command:
-
-.. code-block:: bash
-
- $ hg up revision_specifier
-
-Lastly, if you want to use this new downloaded version of your yt repository as
-the *active* version of yt on your computer (i.e. the one which is executed when
-you run yt from the command line or the one that is loaded when you do ``import
-yt``), then you must "activate" it using the following commands from within the
-repository directory.
-
-.. code-block:: bash
-
- $ cd <REPOSITORY_NAME>
- $ python2.7 setup.py develop
-
-This will rebuild all C modules as well.
-
-.. _reading-source:
-
-How To Read The Source Code
----------------------------
-
-If you just want to *look* at the source code, you may already have it on your
-computer. If you build yt using the install script, the source is available at
-``$YT_DEST/src/yt-hg``. See :ref:`source-installation` for more details about
-to obtain the yt source code if you did not build yt using the install
-script.
-
-The root directory of the yt mercurial repository contains a number of
-subdirectories with different components of the code. Most of the yt source
-code is contained in the yt subdirectory. This directory its self contains
-the following subdirectories:
-
-``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, Dataset
- and AMRHierarchy are defined.
- * ``io.py``, where a subclass of IOHandler is defined.
- * ``fields.py``, where fields we expect to find in datasets are 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.)
-
-``fields``
- This is where all of the derived fields that ship with yt are defined.
-
-``geometry``
- This is where geometric helpler routines are defined. Handlers
- for grid and oct data, as well as helpers for coordinate transformations
- can be found here.
-
-``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.
-
-``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.
-
-``extern``
- Bundled external modules (i.e. code that was not written by one of
- the yt authors but that yt depends on) lives here.
-
-
-If you're looking for a specific file or function in the yt source code, use
-the unix find command:
-
-.. code-block:: bash
-
- $ find <DIRECTORY_TREE_TO_SEARCH> -name '<FILENAME>'
-
-The above command will find the FILENAME in any subdirectory in the
-DIRECTORY_TREE_TO_SEARCH. Alternatively, if you're looking for a function
-call or a keyword in an unknown file in a directory tree, try:
-
-.. code-block:: bash
-
- $ grep -R <KEYWORD_TO_FIND><DIRECTORY_TREE_TO_SEARCH>
-
-This can be very useful for tracking down functions in the yt source.
-
-.. _code-style-guide:
-
-.. include:: ../../../coding_styleguide.txt
+.. include:: ../../../CONTRIBUTING
https://bitbucket.org/yt_analysis/yt/commits/be81f861fd94/
Changeset: be81f861fd94
Branch: yt
User: ngoldbaum
Date: 2015-11-18 16:15:52+00:00
Summary: Rearranging and small updates for instructions on mercurial for yt development
Affected #: 1 file
diff -r 0680472b164304f6596dc04f5a6f37324a06236e -r be81f861fd94f5f9142f1052695b098e15e4a382 CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -19,36 +19,6 @@
<http://bitbucket.org/yt_analysis/yt/pull-requests>`_. The rest of this
document is just an explanation of how to do that.
-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/
-
-The commands that are essential for using mercurial include:
-
-* ``hg commit`` which commits changes in the working directory to the
- repository, creating a new "changeset object."
-* ``hg add`` which adds a new file to be tracked by mercurial. This does
- not change the working directory.
-* ``hg pull`` which pulls (from an optional path specifier) changeset
- objects from a remote source. The working directory is not modified.
-* ``hg push`` which sends (to an optional path specifier) changeset objects
- to a remote source. The working directory is not modified.
-* ``hg log`` which shows a log of all changeset objects in the current
- repository. Use ``-G`` to show a graph of changeset objects and their
- relationship.
-* ``hg update`` which (with an optional "revision" specifier) updates the
- state of the working directory to match a changeset object in the
- repository.
-* ``hg merge`` which combines two changesets to make a union of their lines
- of development. This updates the working directory.
-* ``hg help`` which provides help for any mercurial command. For example, you
- can learn more about the ``log`` command by doing ``hg help log``. Other useful
- topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
- ``hg help extensions``, and ``hg help revsets``.
-
See :ref:`code-style-guide` for more information about coding style in yt and
:ref:`docstrings` for an example docstring. Please read them before hacking on
the codebase, and feel free to email any of the mailing lists for help with the
@@ -123,12 +93,43 @@
How to Use Mercurial with yt
++++++++++++++++++++++++++++
-This document doesn't cover detailed mercurial use, but on IRC we are happy to
-walk you through any troubles you might have. Here are some suggestions
-for using mercurial with yt:
+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-scm.org/
+* http://mercurial-scm.org/wiki
+
+The commands that are essential for using mercurial include:
+
+* ``hg commit`` which commits changes in the working directory to the
+ repository, creating a new "changeset object."
+* ``hg add`` which adds a new file to be tracked by mercurial. This does
+ not change the working directory.
+* ``hg pull`` which pulls (from an optional path specifier) changeset
+ objects from a remote source. The working directory is not modified.
+* ``hg push`` which sends (to an optional path specifier) changeset objects
+ to a remote source. The working directory is not modified.
+* ``hg log`` which shows a log of all changeset objects in the current
+ repository. Use ``-G`` to show a graph of changeset objects and their
+ relationship.
+* ``hg update`` which (with an optional "revision" specifier) updates the
+ state of the working directory to match a changeset object in the
+ repository.
+* ``hg merge`` which combines two changesets to make a union of their lines
+ of development. This updates the working directory.
+* ``hg help`` which provides help for any mercurial command. For example, you
+ can learn more about the ``log`` command by doing ``hg help log``. Other useful
+ topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
+ ``hg help extensions``, and ``hg help revsets``.
+
+We are happy to asnswers questions about mercurial use on our IRC or slack
+channels or on the mailing list to walk you through any troubles you might have.
+Here are some general suggestions for using mercurial with yt:
* Named branches are to be avoided. Try using bookmarks (``hg bookmark``) to
- track work. (`More <http://mercurial.selenic.com/wiki/Bookmarks>`_)
+ track work. (`More <http://mercurial-scm.org/wiki/Bookmarks>`_)
* Make sure you set a username in your ``~/.hgrc`` before you commit any
changes! All of the tutorials above will describe how to do this as one of
the very first steps.
@@ -317,22 +318,23 @@
.. code-block:: bash
$ hg pull upstream
- $ hg update -r "remote(tip,'upstream')"
+ $ hg update -r "remote(yt, 'upstream')"
-After the above steps, your local repository should be at the tip of
-the main yt repository. If you find yourself doing this a lot, it may
-be worth aliasing this task in your ``hgrc`` file by adding something like::
+After the above steps, your local repository should be at the current head of
+the ``yt`` branch in the main yt repository. If you find yourself doing this a
+lot, it may be worth aliasing this task in your ``hgrc`` file by adding
+something like::
[alias]
- myupdate = update -r "remote(tip,'upstream')"
+ ytupdate = update -r "remote(yt, 'upstream')"
-And then you can just issue ``hg myupdate`` to get at the tip of the main yt repository.
+And then you can just issue ``hg ytupdate`` to get at the current head of the
+``yt`` branch on main yt repository.
-Make sure you are on the branch you want to be on, and then you can
-make changes and ``hg commit`` them. If you prefer working with
-`bookmarks <http://mercurial.selenic.com/wiki/Bookmarks>`_, you may
-want to make a bookmark before committing your changes, such as ``hg
-bookmark mybookmark``.
+Make sure you are on the branch you want to be on, and then you can make changes
+and ``hg commit`` them. If you prefer working with `bookmarks
+<http://mercurial-scm.org/wiki/Bookmarks>`_, you may want to make a bookmark
+before committing your changes, such as ``hg bookmark mybookmark``.
To push to your fork on BitBucket if you didn't use a bookmark, you issue the following:
https://bitbucket.org/yt_analysis/yt/commits/a7cfcf5ed9e1/
Changeset: a7cfcf5ed9e1
Branch: yt
User: ngoldbaum
Date: 2015-11-18 16:49:16+00:00
Summary: Adding a summary of the code of conduct
Affected #: 1 file
diff -r be81f861fd94f5f9142f1052695b098e15e4a382 -r a7cfcf5ed9e1bec7992d6b900b867a7e29e38049 CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -26,6 +26,29 @@
Keep in touch, and happy hacking!
+Code of Conduct
+---------------
+
+All contributors to yt are bound by the yt community `code of conduct
+<http://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0023.html>`_.
+
+The code code of conduct recognizes that open source Scientific projects are made
+up of members from around the globe with a diverse set of skills, personalities,
+and experiences. It is through these differences that our community experiences
+success and continued growth. We expect everyone in our community to follow
+the code of conduct when interacting with others both inside and outside of our
+community. Our goal is to keep ours a positive, inclusive, successful, and
+growing community.
+
+Harrassment of any kind for any reason is expressly forbidden. All community
+interactions should be done with a tone of respect and while acknowledging that
+contributors come from diverse backgrounds. Criticism about code must never be
+personal and must be done with respect.
+
+If you feel that the code of conduct has been violated, please send an e-mail to
+confidential at yt-project.org, where we will begin a formal process to resolve the
+issue
+
.. _bootstrap-dev:
Submitting Changes
https://bitbucket.org/yt_analysis/yt/commits/8ed1165917d7/
Changeset: 8ed1165917d7
Branch: yt
User: ngoldbaum
Date: 2015-11-21 04:13:31+00:00
Summary: Moving developer guide into into CONTRIBUTING as well
Affected #: 4 files
diff -r a7cfcf5ed9e1bec7992d6b900b867a7e29e38049 -r 8ed1165917d7a1ca16d011e7b05f4e5bc7a28506 CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -1,3 +1,208 @@
+.. This document is rendered in HTML with cross-reference links filled in at
+ http://yt-project.org/doc/developing/
+
+.. _getting-involved:
+
+Getting Involved
+================
+
+There are *lots* of ways to get involved with yt, as a community and as a
+technical system -- not all of them just contributing code, but also
+participating in the community, helping us with designing the websites, adding
+documentation, and sharing your scripts with others.
+
+Coding is only one way to be involved!
+
+Communication Channels
+----------------------
+
+There are four main communication channels for yt:
+
+ * We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
+ You can connect through our web
+ gateway without any special client, at http://yt-project.org/irc.html .
+ *IRC is the first stop for conversation!*
+ * `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
+ is a relatively high-traffic mailing list where people are encouraged to ask
+ questions about the code, figure things out and so on.
+ * `yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_ is
+ a much lower-traffic mailing list designed to focus on discussions of
+ improvements to the code, ideas about planning, development issues, and so
+ on.
+ * Many yt developers participate in the yt Slack community. Slack is a free chat service that many teams use to organize development. You can get an
+ invite to yt's Slack organization by clicking the "Join us @ Slack" button
+ on this page: http://yt-project.org/community.html
+ * `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
+ the (now-inaccurately titled) mailing list where all pushes to the primary
+ repository are sent.
+
+The easiest way to get involved with yt is to read the mailing lists, hang out
+in IRC or slack chat, and participate. If someone asks a question you know the
+answer to (or have your own question about!) write back and answer it.
+
+If you have an idea about something, suggest it! We not only welcome
+participation, we encourage it.
+
+Documentation
+-------------
+
+The yt documentation is constantly being updated, and it is a task we would very
+much appreciate assistance with. Whether that is adding a section, updating an
+outdated section, contributing typo or grammatical fixes, adding a FAQ, or
+increasing coverage of functionality, it would be very helpful if you wanted to
+help out.
+
+The easiest way to help out is to fork the main yt repository (where the
+documentation lives in the ``doc`` directory in the root of the yt mercurial
+repository) and then make your changes in your own fork. When you are done,
+issue a pull request through the website for your new fork, and we can comment
+back and forth and eventually accept your changes. See :ref:`sharing-changes` for
+more information about contributing your changes to yt on bitbucket.
+
+Gallery Images and Videos
+-------------------------
+
+If you have an image or video you'd like to display in the image or video
+galleries, getting it included it easy! You can either fork the `yt homepage
+repository <http://bitbucket.org/yt_analysis/website>`_ and add it there, or
+email it to us and we'll add it to the `Gallery
+<http://yt-project.org/gallery.html>`_.
+
+We're eager to show off the images and movies you make with yt, so please feel
+free to drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
+a line and let us know if you've got something great!
+
+Technical Contributions
+-----------------------
+
+Contributing code is another excellent way to participate -- whether it's
+bug fixes, new features, analysis modules, or a new code frontend. See
+:ref:`creating_frontend` for more details.
+
+The process is pretty simple: fork on BitBucket, make changes, issue a pull
+request. We can then go back and forth with comments in the pull request, but
+usually we end up accepting.
+
+For more information, see :ref:`contributing-code`, where we spell out how to
+get up and running with a development environment, how to commit, and how to
+use BitBucket.
+
+Online Presence
+---------------
+
+Some of these fall under the other items, but if you'd like to help out with
+the website or any of the other ways yt is presented online, please feel free!
+Almost everything is kept in hg repositories on BitBucket, and it is very easy
+to fork and contribute back changes.
+
+Please feel free to dig in and contribute changes.
+
+Word of Mouth
+-------------
+
+If you're using yt and it has increased your productivity, please feel
+encouraged to share that information. Cite our `paper
+<http://adsabs.harvard.edu/abs/2011ApJS..192....9T>`_, tell your colleagues,
+and just spread word of mouth. By telling people about your successes, you'll
+help bring more eyes and hands to the table -- in this manner, by increasing
+participation, collaboration, and simply spreading the limits of what the code
+is asked to do, we hope to help scale the utility and capability of yt with the
+community size.
+
+Feel free to `blog <http://blog.yt-project.org/>`_ about, `tweet
+<http://twitter.com/yt_astro>`_ about and talk about what you are up to!
+
+Long-Term Projects
+------------------
+
+There are some wild-eyed, out-there ideas that have been bandied about for the
+future directions of yt -- some of them even written into the mission
+statement. The ultimate goal is to move past simple analysis and visualization
+of data and begin to approach it from the other side, of generating data,
+running solvers. We also hope to increase its ability to act as an in situ
+analysis code, by presenting a unified protocol. Other projects include
+interfacing with ParaView and VisIt, creating a web GUI for running
+simulations, creating a run-tracker that follows simulations in progress, a
+federated database for simulation outputs, and so on and so forth.
+
+yt is an ambitious project. Let's be ambitious together.
+
+yt Community Code of Conduct
+----------------------------
+
+The community of participants in open source
+Scientific projects is made up of members from around the
+globe with a diverse set of skills, personalities, and
+experiences. It is through these differences that our
+community experiences success and continued growth. We
+expect everyone in our community to follow these guidelines
+when interacting with others both inside and outside of our
+community. Our goal is to keep ours a positive, inclusive,
+successful, and growing community.
+
+As members of the community,
+
+- We pledge to treat all people with respect and
+ provide a harassment- and bullying-free environment,
+ regardless of sex, sexual orientation and/or gender
+ identity, disability, physical appearance, body size,
+ race, nationality, ethnicity, and religion. In
+ particular, sexual language and imagery, sexist,
+ racist, or otherwise exclusionary jokes are not
+ appropriate.
+
+- We pledge to respect the work of others by
+ recognizing acknowledgment/citation requests of
+ original authors. As authors, we pledge to be explicit
+ about how we want our own work to be cited or
+ acknowledged.
+
+- We pledge to welcome those interested in joining the
+ community, and realize that including people with a
+ variety of opinions and backgrounds will only serve to
+ enrich our community. In particular, discussions
+ relating to pros/cons of various technologies,
+ programming languages, and so on are welcome, but
+ these should be done with respect, taking proactive
+ measure to ensure that all participants are heard and
+ feel confident that they can freely express their
+ opinions.
+
+- We pledge to welcome questions and answer them
+ respectfully, paying particular attention to those new
+ to the community. We pledge to provide respectful
+ criticisms and feedback in forums, especially in
+ discussion threads resulting from code
+ contributions.
+
+- We pledge to be conscientious of the perceptions of
+ the wider community and to respond to criticism
+ respectfully. We will strive to model behaviors that
+ encourage productive debate and disagreement, both
+ within our community and where we are criticized. We
+ will treat those outside our community with the same
+ respect as people within our community.
+
+- We pledge to help the entire community follow the
+ code of conduct, and to not remain silent when we see
+ violations of the code of conduct. We will take action
+ when members of our community violate this code such as
+ contacting confidential at yt-project.org (all emails sent to
+ this address will be treated with the strictest
+ confidence) or talking privately with the person.
+
+This code of conduct applies to all
+community situations online and offline, including mailing
+lists, forums, social media, conferences, meetings,
+associated social events, and one-to-one interactions.
+
+The yt Community Code of Conduct was adapted from the
+`Astropy Community Code of Conduct
+<http://www.astropy.org/about.html#codeofconduct>`_,
+which was partially inspired by the PSF code of conduct.
+
+.. _contributing-code:
+
How to Develop yt
=================
diff -r a7cfcf5ed9e1bec7992d6b900b867a7e29e38049 -r 8ed1165917d7a1ca16d011e7b05f4e5bc7a28506 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -1,3 +1,1 @@
-.. _contributing-code:
-
.. include:: ../../../CONTRIBUTING
diff -r a7cfcf5ed9e1bec7992d6b900b867a7e29e38049 -r 8ed1165917d7a1ca16d011e7b05f4e5bc7a28506 doc/source/developing/index.rst
--- a/doc/source/developing/index.rst
+++ b/doc/source/developing/index.rst
@@ -16,7 +16,6 @@
.. toctree::
:maxdepth: 2
- intro
developing
building_the_docs
testing
diff -r a7cfcf5ed9e1bec7992d6b900b867a7e29e38049 -r 8ed1165917d7a1ca16d011e7b05f4e5bc7a28506 doc/source/developing/intro.rst
--- a/doc/source/developing/intro.rst
+++ /dev/null
@@ -1,218 +0,0 @@
-.. _getting-involved:
-
-Getting Involved
-================
-
-There are *lots* of ways to get involved with yt, as a community and as a
-technical system -- not all of them just contributing code, but also
-participating in the community, helping us with designing the websites, adding
-documentation, and sharing your scripts with others.
-
-Coding is only one way to be involved!
-
-Communication Channels
-----------------------
-
-There are four main communication channels for yt:
-
- * We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
- You can connect through our web
- gateway without any special client, at http://yt-project.org/irc.html .
- *IRC is the first stop for conversation!*
- * `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
- is a relatively high-traffic mailing list where people are encouraged to ask
- questions about the code, figure things out and so on.
- * `yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_ is
- a much lower-traffic mailing list designed to focus on discussions of
- improvements to the code, ideas about planning, development issues, and so
- on.
- * `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
- the (now-inaccurately titled) mailing list where all pushes to the primary
- repository are sent.
-
-The easiest way to get involved with yt is to read the mailing lists, hang out
-in IRC, and participate. If someone asks a question you know the answer to (or
-have your own question about!) write back and answer it.
-
-If you have an idea about something, suggest it! We not only welcome
-participation, we encourage it.
-
-.. _share-your-scripts:
-
-Share Your Scripts
-------------------
-
-.. warning:: The yt Hub is currently offline due to some hosting problems. We
- hope to have it back up online soon.
-
-The next easiest way to get involved with yt is to participate in the `yt Hub
-<http://hub.yt-project.org/>`_. This is a place where scripts, paper
-repositories, documents and so on can be submitted to share with the broader
-community.
-
-If you have a repository on `BitBucket <https://bitbucket.org/>`_ then you can
-simply submit it through the ytHub submit link. Otherwise, we provide the
-``yt hubsubmit`` command, which will guide you through the process of creating
-a mercurial repository, uploading it to BitBucket, and then submitting it
-directly to the Hub.
-
-This is one of the best ways to get involved in the community! We would love
-to have more examples that show complex or advanced behavior -- and if you have
-used such scripts to write a paper, that too would be an amazing contribution.
-
-Documentation
--------------
-
-The yt documentation -- which you are reading right now -- is constantly being
-updated, and it is a task we would very much appreciate assistance with.
-Whether that is adding a section, updating an outdated section, contributing
-typo or grammatical fixes, adding a FAQ, or increasing coverage of
-functionality, it would be very helpful if you wanted to help out.
-
-The easiest way to help out is to fork the main yt repository (where the
-documentation lives in the ``doc`` directory in the root of the yt mercurial
-repository) and then make your changes in your own fork. When you are done,
-issue a pull request through the website for your new fork, and we can comment
-back and forth and eventually accept your changes.
-
-Gallery Images and Videos
--------------------------
-
-If you have an image or video you'd like to display in the image or video
-galleries, getting it included it easy! You can either fork the `yt homepage
-repository <http://bitbucket.org/yt_analysis/website>`_ and add it there, or
-email it to us and we'll add it to the `Gallery
-<http://yt-project.org/gallery.html>`_.
-
-We're eager to show off the images and movies you make with yt, so please feel
-free to drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
-a line and let us know if you've got something great!
-
-Technical Contributions
------------------------
-
-Contributing code is another excellent way to participate -- whether it's
-bug fixes, new features, analysis modules, or a new code frontend. See
-:ref:`creating_frontend` for more details.
-
-The process is pretty simple: fork on BitBucket, make changes, issue a pull
-request. We can then go back and forth with comments in the pull request, but
-usually we end up accepting.
-
-For more information, see :ref:`contributing-code`, where we spell out how to
-get up and running with a development environment, how to commit, and how to
-use BitBucket.
-
-Online Presence
----------------
-
-Some of these fall under the other items, but if you'd like to help out with
-the website or any of the other ways yt is presented online, please feel free!
-Almost everything is kept in hg repositories on BitBucket, and it is very easy
-to fork and contribute back changes.
-
-Please feel free to dig in and contribute changes.
-
-Word of Mouth
--------------
-
-If you're using yt and it has increased your productivity, please feel
-encouraged to share that information. Cite our `paper
-<http://adsabs.harvard.edu/abs/2011ApJS..192....9T>`_, tell your colleagues,
-and just spread word of mouth. By telling people about your successes, you'll
-help bring more eyes and hands to the table -- in this manner, by increasing
-participation, collaboration, and simply spreading the limits of what the code
-is asked to do, we hope to help scale the utility and capability of yt with the
-community size.
-
-Feel free to `blog <http://blog.yt-project.org/>`_ about, `tweet
-<http://twitter.com/yt_astro>`_ about and talk about what you are up to!
-
-Long-Term Projects
-------------------
-
-There are some wild-eyed, out-there ideas that have been bandied about for the
-future directions of yt -- some of them even written into the mission
-statement. The ultimate goal is to move past simple analysis and visualization
-of data and begin to approach it from the other side, of generating data,
-running solvers. We also hope to increase its ability to act as an in situ
-analysis code, by presenting a unified protocol. Other projects include
-interfacing with ParaView and VisIt, creating a web GUI for running
-simulations, creating a run-tracker that follows simulations in progress, a
-federated database for simulation outputs, and so on and so forth.
-
-yt is an ambitious project. Let's be ambitious together.
-
-yt Community Code of Conduct
-----------------------------
-
-The community of participants in open source
-Scientific projects is made up of members from around the
-globe with a diverse set of skills, personalities, and
-experiences. It is through these differences that our
-community experiences success and continued growth. We
-expect everyone in our community to follow these guidelines
-when interacting with others both inside and outside of our
-community. Our goal is to keep ours a positive, inclusive,
-successful, and growing community.
-
-As members of the community,
-
-- We pledge to treat all people with respect and
- provide a harassment- and bullying-free environment,
- regardless of sex, sexual orientation and/or gender
- identity, disability, physical appearance, body size,
- race, nationality, ethnicity, and religion. In
- particular, sexual language and imagery, sexist,
- racist, or otherwise exclusionary jokes are not
- appropriate.
-
-- We pledge to respect the work of others by
- recognizing acknowledgment/citation requests of
- original authors. As authors, we pledge to be explicit
- about how we want our own work to be cited or
- acknowledged.
-
-- We pledge to welcome those interested in joining the
- community, and realize that including people with a
- variety of opinions and backgrounds will only serve to
- enrich our community. In particular, discussions
- relating to pros/cons of various technologies,
- programming languages, and so on are welcome, but
- these should be done with respect, taking proactive
- measure to ensure that all participants are heard and
- feel confident that they can freely express their
- opinions.
-
-- We pledge to welcome questions and answer them
- respectfully, paying particular attention to those new
- to the community. We pledge to provide respectful
- criticisms and feedback in forums, especially in
- discussion threads resulting from code
- contributions.
-
-- We pledge to be conscientious of the perceptions of
- the wider community and to respond to criticism
- respectfully. We will strive to model behaviors that
- encourage productive debate and disagreement, both
- within our community and where we are criticized. We
- will treat those outside our community with the same
- respect as people within our community.
-
-- We pledge to help the entire community follow the
- code of conduct, and to not remain silent when we see
- violations of the code of conduct. We will take action
- when members of our community violate this code such as
- contacting confidential at yt-project.org (all emails sent to
- this address will be treated with the strictest
- confidence) or talking privately with the person.
-
-This code of conduct applies to all
-community situations online and offline, including mailing
-lists, forums, social media, conferences, meetings,
-associated social events, and one-to-one interactions.
-
-The yt Community Code of Conduct was adapted from the
-`Astropy Community Code of Conduct
-<http://www.astropy.org/about.html#codeofconduct>`_,
-which was partially inspired by the PSF code of conduct.
https://bitbucket.org/yt_analysis/yt/commits/ddee190fe850/
Changeset: ddee190fe850
Branch: yt
User: ngoldbaum
Date: 2015-11-21 04:13:49+00:00
Summary: Rearranging, adding some discussion of open issues, and updating mercurial command advice.
Affected #: 2 files
diff -r 8ed1165917d7a1ca16d011e7b05f4e5bc7a28506 -r ddee190fe850bbb6212683091e687c8a6e89f9ff CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -231,362 +231,42 @@
Keep in touch, and happy hacking!
-Code of Conduct
----------------
+.. _open-issues:
-All contributors to yt are bound by the yt community `code of conduct
-<http://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0023.html>`_.
+Open Issues
+-----------
-The code code of conduct recognizes that open source Scientific projects are made
-up of members from around the globe with a diverse set of skills, personalities,
-and experiences. It is through these differences that our community experiences
-success and continued growth. We expect everyone in our community to follow
-the code of conduct when interacting with others both inside and outside of our
-community. Our goal is to keep ours a positive, inclusive, successful, and
-growing community.
-
-Harrassment of any kind for any reason is expressly forbidden. All community
-interactions should be done with a tone of respect and while acknowledging that
-contributors come from diverse backgrounds. Criticism about code must never be
-personal and must be done with respect.
-
-If you feel that the code of conduct has been violated, please send an e-mail to
-confidential at yt-project.org, where we will begin a formal process to resolve the
-issue
-
-.. _bootstrap-dev:
+If you're interested in participating in yt development, take a look at the
+`issue tracker on bitbucket
+<https://bitbucket.org/yt_analysis/yt/issues?milestone=easy?status=new>`_.
+Issues are marked with a milestone of "easy", "moderate", or "difficult"
+depending on the estimated level of difficulty for fixing the issue. While we
+try to triage the issue tracker regularly, it may be the case that issues marked
+"moderate" are actually easier than their milestone label indicates since that
+is the default value.
Submitting Changes
------------------
We provide a brief introduction to submitting changes here. yt thrives on the
-strength of its communities ( http://arxiv.org/abs/1301.7064 has further
+strength of its communities (http://arxiv.org/abs/1301.7064 has further
discussion) and we encourage contributions from any user. While we do not
-discuss in detail version control, mercurial or the advanced usage of
-BitBucket, we do provide an outline of how to submit changes and we are happy
-to provide further assistance or guidance.
+discuss version control, mercurial or the advanced usage of BitBucket in detail
+here, we do provide an outline of how to submit changes and we are happy to
+provide further assistance or guidance.
Licensing
+++++++++
-yt has, with the 2.6 release, been `relicensed
-<http://blog.yt-project.org/post/Relicensing.html>`_ under the BSD 3-clause
-license. Previously versions were released under the GPLv3.
+yt is `licensed <http://blog.yt-project.org/post/Relicensing.html>`_ under the
+BSD 3-clause license. Versions previous to yt-2.6 were released under the GPLv3.
All contributed code must be BSD-compatible. If you'd rather not license in
this manner, but still want to contribute, please consider creating an external
package, which we'll happily link to.
-.. _requirements-for-code-submission:
-
-Requirements for Code Submission
-++++++++++++++++++++++++++++++++
-
-Modifications to the code typically fall into one of three categories, each of
-which have different requirements for acceptance into the code base. These
-requirements are in place for a few reasons -- to make sure that the code is
-maintainable, testable, and that we can easily include information about
-changes in changelogs during the release procedure. (See `YTEP-0008
-<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
-detail.)
-
-* New Features
-
- * New unit tests (possibly new answer tests) (See :ref:`testing`)
- * Docstrings in the source code for the public API
- * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
- * Addition of cookbook recipe (See :ref:`writing_documentation`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Extension or Breakage of API in Existing Features
-
- * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
- * Update existing cookbook recipes (See :ref:`writing_documentation`)
- * Modify of create new unit tests (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Bug fixes
-
- * Unit test is encouraged, to ensure breakage does not happen again in the
- future. (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-When submitting, you will be asked to make sure that your changes meet all of
-these requirements. They are pretty easy to meet, and we're also happy to help
-out with them. In :ref:`code-style-guide` there is a list of handy tips for
-how to structure and write your code.
-
-.. _mercurial-with-yt:
-
-How to Use Mercurial with yt
-++++++++++++++++++++++++++++
-
-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-scm.org/
-* http://mercurial-scm.org/wiki
-
-The commands that are essential for using mercurial include:
-
-* ``hg commit`` which commits changes in the working directory to the
- repository, creating a new "changeset object."
-* ``hg add`` which adds a new file to be tracked by mercurial. This does
- not change the working directory.
-* ``hg pull`` which pulls (from an optional path specifier) changeset
- objects from a remote source. The working directory is not modified.
-* ``hg push`` which sends (to an optional path specifier) changeset objects
- to a remote source. The working directory is not modified.
-* ``hg log`` which shows a log of all changeset objects in the current
- repository. Use ``-G`` to show a graph of changeset objects and their
- relationship.
-* ``hg update`` which (with an optional "revision" specifier) updates the
- state of the working directory to match a changeset object in the
- repository.
-* ``hg merge`` which combines two changesets to make a union of their lines
- of development. This updates the working directory.
-* ``hg help`` which provides help for any mercurial command. For example, you
- can learn more about the ``log`` command by doing ``hg help log``. Other useful
- topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
- ``hg help extensions``, and ``hg help revsets``.
-
-We are happy to asnswers questions about mercurial use on our IRC or slack
-channels or on the mailing list to walk you through any troubles you might have.
-Here are some general suggestions for using mercurial with yt:
-
-* Named branches are to be avoided. Try using bookmarks (``hg bookmark``) to
- track work. (`More <http://mercurial-scm.org/wiki/Bookmarks>`_)
-* Make sure you set a username in your ``~/.hgrc`` before you commit any
- changes! All of the tutorials above will describe how to do this as one of
- the very first steps.
-* When contributing changes, you might be asked to make a handful of
- modifications to your source code. We'll work through how to do this with
- you, and try to make it as painless as possible.
-* Please avoid deleting your yt forks, as that eliminates the code review
- process from BitBucket's website.
-* In all likelihood, you only need one fork. To keep it in sync, you can
- sync from the website. (See Bitbucket's `Blog Post
- <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
- about this.)
-* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
- list.
-
-.. _building-yt:
-
-Building yt
-+++++++++++
-
-If you have made changes to any C or Cython (``.pyx``) modules, you have to
-rebuild yt. If your changes have exclusively been to Python modules, you will
-not need to re-build, but (see below) you may need to re-install.
-
-If you are running from a clone that is executable in-place (i.e., has been
-installed via the installation script or you have run ``setup.py develop``) you
-can rebuild these modules by executing:
-
-.. code-block:: bash
-
- $ python2.7 setup.py develop
-
-If you have previously "installed" via ``setup.py install`` you have to
-re-install:
-
-.. code-block:: bash
-
- $ python2.7 setup.py install
-
-Only one of these two options is needed.
-
-.. _windows-developing:
-
-Developing yt on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you plan to develop yt on Windows, it is necessary to use the `MinGW
-<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
-Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
-installed from Anaconda as well. These can both be installed with a single command:
-
-.. code-block:: bash
-
- $ conda install libpython mingw
-
-Additionally, the syntax for the setup command is slightly different; you must type:
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 develop
-
-or
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 install
-
-.. _sharing-changes:
-
-Making and Sharing Changes
-++++++++++++++++++++++++++
-
-The simplest way to submit changes to yt is to do the following:
-
-* Build yt from the mercurial repository
-* Navigate to the root of the yt repository
-* Make some changes and commit them
-* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
-* Push the changesets to your fork
-* Issue a pull request.
-
-Here's a more detailed flowchart of how to submit changes.
-
-#. If you have used the installation script, the source code for yt can be
- found in ``$YT_DEST/src/yt-hg``. Alternatively see
- :ref:`source-installation` for instructions on how to build yt from the
- mercurial repository. (Below, in :ref:`reading-source`, we describe how to
- find items of interest.)
-#. Edit the source file you are interested in and
- test your changes. (See :ref:`testing` for more information.)
-#. Fork yt on BitBucket. (This step only has to be done once.) You can do
- this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
- yt.
-#. Commit these changes, using ``hg commit``. This can take an argument
- which is a series of filenames, if you have some changes you do not want
- to commit.
-#. Remember that this is a large development effort and to keep the code
- accessible to everyone, good documentation is a must. Add in source code
- comments for what you are doing. Add in docstrings
- if you are adding a new function or class or keyword to a function.
- Add documentation to the appropriate section of the online docs so that
- people other than yourself know how to use your new code.
-#. If your changes include new functionality or cover an untested area of the
- code, add a test. (See :ref:`testing` for more information.) Commit
- these changes as well.
-#. Push your changes to your new fork using the command::
-
- hg push -r . https://bitbucket.org/YourUsername/yt/
-
- If you end up doing considerable development, you can set an alias in the
- file ``.hg/hgrc`` to point to this path.
-
- .. note::
- Note that the above approach uses HTTPS as the transfer protocol
- between your machine and BitBucket. If you prefer to use SSH - or
- perhaps you're behind a proxy that doesn't play well with SSL via
- HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
- the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
- place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
- For consistency, all commands we list in this document will use the HTTPS
- protocol.
-
- .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
-
-#. Issue a pull request at
- https://bitbucket.org/YourUsername/yt/pull-request/new
- A pull request is essentially just asking people to review and accept the
- modifications you have made to your personal version of the code.
-
-
-During the course of your pull request you may be asked to make changes. These
-changes may be related to style issues, correctness issues, or even requesting
-tests. The process for responding to pull request code review is relatively
-straightforward.
-
-#. Make requested changes, or leave a comment indicating why you don't think
- they should be made.
-#. Commit those changes to your local repository.
-#. Push the changes to your fork:
-
- hg push https://bitbucket.org/YourUsername/yt/
-
-#. Your pull request will be automatically updated.
-
-.. _multiple-PRs:
-
-Working with Multiple BitBucket Pull Requests
-+++++++++++++++++++++++++++++++++++++++++++++
-
-Once you become active developing for yt, you may be working on
-various aspects of the code or bugfixes at the same time. Currently,
-BitBucket's *modus operandi* for pull requests automatically updates
-your active pull request with every ``hg push`` of commits that are a
-descendant of the head of your pull request. In a normal workflow,
-this means that if you have an active pull request, make some changes
-locally for, say, an unrelated bugfix, then push those changes back to
-your fork in the hopes of creating a *new* pull request, you'll
-actually end up updating your current pull request!
-
-There are a few ways around this feature of BitBucket that will allow
-for multiple pull requests to coexist; we outline one such method
-below. We assume that you have a fork of yt at
-``http://bitbucket.org/YourUsername/Your_yt`` (see
-:ref:`sharing-changes` for instructions on creating a fork) and that
-you have an active pull request to the main repository.
-
-The main issue with starting another pull request is to make sure that
-your push to BitBucket doesn't go to the same head as your
-existing pull request and trigger BitBucket's auto-update feature.
-Here's how to get your local repository away from your current pull
-request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
-and your ``hgrc`` file:
-
-#. Set up a Mercurial path for the main yt repository (note this is a convenience
- step and only needs to be done once). Add the following to your
- ``Your_yt/.hg/hgrc``::
-
- [paths]
- upstream = https://bitbucket.org/yt_analysis/yt
-
- This will create a path called ``upstream`` that is aliased to the URL of the
- main yt repository.
-#. Now we'll use revsets_ to update your local repository to the tip of the
- ``upstream`` path:
-
- .. code-block:: bash
-
- $ hg pull upstream
- $ hg update -r "remote(yt, 'upstream')"
-
-After the above steps, your local repository should be at the current head of
-the ``yt`` branch in the main yt repository. If you find yourself doing this a
-lot, it may be worth aliasing this task in your ``hgrc`` file by adding
-something like::
-
- [alias]
- ytupdate = update -r "remote(yt, 'upstream')"
-
-And then you can just issue ``hg ytupdate`` to get at the current head of the
-``yt`` branch on main yt repository.
-
-Make sure you are on the branch you want to be on, and then you can make changes
-and ``hg commit`` them. If you prefer working with `bookmarks
-<http://mercurial-scm.org/wiki/Bookmarks>`_, you may want to make a bookmark
-before committing your changes, such as ``hg bookmark mybookmark``.
-
-To push to your fork on BitBucket if you didn't use a bookmark, you issue the following:
-
-.. code-block:: bash
-
- $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
-
-The ``-r .`` means "push only the commit I'm standing on and any ancestors." The
-``-f`` is to force Mecurial to do the push since we are creating a new remote head.
-
-Note that if you *did* use a bookmark, you don't have to force the push, but you do
-need to push the bookmark; in other words do the following instead of the above:
-
-.. code-block:: bash
-
- $ hg push -B mybookmark https://bitbucket.org/YourUsername/Your_yt
-
-The ``-B`` means "publish my bookmark and any relevant changesets to the remote server."
-
-You can then go to the BitBucket interface and issue a new pull request based on
-your last changes, as usual.
-
How To Get The Source Code For Editing
---------------------------------------
+++++++++++++++++++++++++++++++++++++++
yt is hosted on BitBucket, and you can see all of the yt repositories at
http://bitbucket.org/yt_analysis/. With the yt installation script you should have a
@@ -647,13 +327,13 @@
.. _reading-source:
How To Read The Source Code
----------------------------
++++++++++++++++++++++++++++
If you just want to *look* at the source code, you may already have it on your
computer. If you build yt using the install script, the source is available at
``$YT_DEST/src/yt-hg``. See :ref:`source-installation` for more details about
to obtain the yt source code if you did not build yt using the install
-script.
+script.
The root directory of the yt mercurial repository contains a number of
subdirectories with different components of the code. Most of the yt source
@@ -675,7 +355,7 @@
``fields``
This is where all of the derived fields that ship with yt are defined.
-``geometry``
+``geometry``
This is where geometric helpler routines are defined. Handlers
for grid and oct data, as well as helpers for coordinate transformations
can be found here.
@@ -705,7 +385,7 @@
All broadly useful code that doesn't clearly fit in one of the other
categories goes here.
-``extern``
+``extern``
Bundled external modules (i.e. code that was not written by one of
the yt authors but that yt depends on) lives here.
@@ -727,20 +407,334 @@
This can be very useful for tracking down functions in the yt source.
-Testing
--------
+.. _building-yt:
-When adding new features or fixing bugs, please make sure that you add
-tests. When fixing bugs, this ensures the bug cannot reappear in the future, and
-also helps if we want to make major changes to yt internals.
+Building yt
++++++++++++
-To learn more details about yt tests, see `the yt testing guide
-<http://yt-project.org/doc/developing/testing.html>`_.
+If you have made changes to any C or Cython (``.pyx``) modules, you have to
+rebuild yt. If your changes have exclusively been to Python modules, you will
+not need to re-build, but (see below) you may need to re-install.
+
+If you are running from a clone that is executable in-place (i.e., has been
+installed via the installation script or you have run ``setup.py develop``) you
+can rebuild these modules by executing:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py develop
+
+If you have previously "installed" via ``setup.py install`` you have to
+re-install:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py install
+
+Only one of these two options is needed.
+
+.. _windows-developing:
+
+Developing yt on Windows
+------------------------
+
+If you plan to develop yt on Windows, it is necessary to use the `MinGW
+<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
+Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
+installed from Anaconda as well. These can both be installed with a single command:
+
+.. code-block:: bash
+
+ $ conda install libpython mingw
+
+Additionally, the syntax for the setup command is slightly different; you must type:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 develop
+
+or
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 install
+
+.. _requirements-for-code-submission:
+
+Requirements for Code Submission
+--------------------------------
+
+Modifications to the code typically fall into one of three categories, each of
+which have different requirements for acceptance into the code base. These
+requirements are in place for a few reasons -- to make sure that the code is
+maintainable, testable, and that we can easily include information about
+changes in changelogs during the release procedure. (See `YTEP-0008
+<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
+detail.)
+
+* New Features
+
+ * New unit tests (possibly new answer tests) (See :ref:`testing`)
+ * Docstrings in the source code for the public API
+ * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
+ * Addition of cookbook recipe (See :ref:`writing_documentation`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Extension or Breakage of API in Existing Features
+
+ * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
+ * Update existing cookbook recipes (See :ref:`writing_documentation`)
+ * Modify of create new unit tests (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Bug fixes
+
+ * Unit test is encouraged, to ensure breakage does not happen again in the
+ future. (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+When submitting, you will be asked to make sure that your changes meet all of
+these requirements. They are pretty easy to meet, and we're also happy to help
+out with them. In :ref:`code-style-guide` there is a list of handy tips for
+how to structure and write your code.
+
+.. _mercurial-with-yt:
+
+How to Use Mercurial with yt
+----------------------------
+
+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-scm.org/
+* http://mercurial-scm.org/wiki
+
+The commands that are essential for using mercurial include:
+
+* ``hg help`` which provides help for any mercurial command. For example, you
+ can learn more about the ``log`` command by doing ``hg help log``. Other useful
+ topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
+ ``hg help extensions``, and ``hg help revsets``.
+* ``hg commit`` which commits changes in the working directory to the
+ repository, creating a new "changeset object."
+* ``hg add`` which adds a new file to be tracked by mercurial. This does
+ not change the working directory.
+* ``hg pull`` which pulls (from an optional path specifier) changeset
+ objects from a remote source. The working directory is not modified.
+* ``hg push`` which sends (to an optional path specifier) changeset objects
+ to a remote source. The working directory is not modified.
+* ``hg log`` which shows a log of all changeset objects in the current
+ repository. Use ``-G`` to show a graph of changeset objects and their
+ relationship.
+* ``hg update`` which (with an optional "revision" specifier) updates the
+ state of the working directory to match a changeset object in the
+ repository.
+* ``hg merge`` which combines two changesets to make a union of their lines
+ of development. This updates the working directory.
+
+We are happy to asnswers questions about mercurial use on our IRC, slack
+chat or on the mailing list to walk you through any troubles you might have.
+Here are some general suggestions for using mercurial with yt:
+
+* Named branches are to be avoided. Try using bookmarks (``see hg help
+ bookmark``) to track work. (`More info about bookmarks is available on the
+ mercurial wiki <http://mercurial-scm.org/wiki/Bookmarks>`_)
+* Make sure you set a username in your ``~/.hgrc`` before you commit any
+ changes! All of the tutorials above will describe how to do this as one of
+ the very first steps.
+* When contributing changes, you might be asked to make a handful of
+ modifications to your source code. We'll work through how to do this with
+ you, and try to make it as painless as possible.
+* Your test may fail automated style checks. See :ref:`code-style-guide` for
+ more information about automatically verifying your code style.
+* Please avoid deleting your yt forks, as that deletes the pull request
+ discussion from process from BitBucket's website, even if your pull request
+ is merged.
+* You should only need one fork. To keep it in sync, you can sync from the
+ website. See Bitbucket's `Blog Post
+ <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
+ about this. See :ref:`sharing-changes` for a description of the basic workflow
+ and :ref:`multiple-PRs` for a discussion about what to do when you want to
+ have multiple open pull requests at the same time.
+* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
+ list.
+
+.. _sharing-changes:
+
+Making and Sharing Changes
+--------------------------
+
+The simplest way to submit changes to yt is to do the following:
+
+* Build yt from the mercurial repository
+* Navigate to the root of the yt repository
+* Make some changes and commit them
+* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
+* Push the changesets to your fork
+* Issue a pull request.
+
+Here's a more detailed flowchart of how to submit changes.
+
+#. If you have used the installation script, the source code for yt can be
+ found in ``$YT_DEST/src/yt-hg``. Alternatively see
+ :ref:`source-installation` for instructions on how to build yt from the
+ mercurial repository. (Below, in :ref:`reading-source`, we describe how to
+ find items of interest.)
+#. Edit the source file you are interested in and
+ test your changes. (See :ref:`testing` for more information.)
+#. Fork yt on BitBucket. (This step only has to be done once.) You can do
+ this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
+ yt.
+#. Create a bookmark to track your work. For example: ``hg bookmark
+ my-first-pull-request``
+#. Commit these changes, using ``hg commit``. This can take an argument
+ which is a series of filenames, if you have some changes you do not want
+ to commit.
+#. Remember that this is a large development effort and to keep the code
+ accessible to everyone, good documentation is a must. Add in source code
+ comments for what you are doing. Add in docstrings
+ if you are adding a new function or class or keyword to a function.
+ Add documentation to the appropriate section of the online docs so that
+ people other than yourself know how to use your new code.
+#. If your changes include new functionality or cover an untested area of the
+ code, add a test. (See :ref:`testing` for more information.) Commit
+ these changes as well.
+#. Push your changes to your new fork using the command::
+
+ hg push -B my-first-pull-request https://bitbucket.org/YourUsername/yt/
+
+ Where you should substitute the name of the bookmark you are working on for
+ ``my-first-pull-request``. If you end up doing considerable development, you
+ can set an alias in the file ``.hg/hgrc`` to point to this path.
+
+ .. note::
+ Note that the above approach uses HTTPS as the transfer protocol
+ between your machine and BitBucket. If you prefer to use SSH - or
+ perhaps you're behind a proxy that doesn't play well with SSL via
+ HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
+ the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
+ place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
+ For consistency, all commands we list in this document will use the HTTPS
+ protocol.
+
+ .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
+
+#. Issue a pull request at
+ https://bitbucket.org/YourUsername/yt/pull-request/new
+ A pull request is essentially just asking people to review and accept the
+ modifications you have made to your personal version of the code.
+
+
+During the course of your pull request you may be asked to make changes. These
+changes may be related to style issues, correctness issues, or even requesting
+tests. The process for responding to pull request code review is relatively
+straightforward.
+
+#. Make requested changes, or leave a comment indicating why you don't think
+ they should be made.
+#. Commit those changes to your local repository.
+#. Push the changes to your fork:
+
+ hg push https://bitbucket.org/YourUsername/yt/
+
+#. Your pull request will be automatically updated.
+
+.. _multiple-PRs:
+
+Working with Multiple BitBucket Pull Requests
++++++++++++++++++++++++++++++++++++++++++++++
+
+Once you become active developing for yt, you may be working on
+various aspects of the code or bugfixes at the same time. Currently,
+BitBucket's *modus operandi* for pull requests automatically updates
+your active pull request with every ``hg push`` of commits that are a
+descendant of the head of your pull request. In a normal workflow,
+this means that if you have an active pull request, make some changes
+locally for, say, an unrelated bugfix, then push those changes back to
+your fork in the hopes of creating a *new* pull request, you'll
+actually end up updating your current pull request!
+
+There are a few ways around this feature of BitBucket that will allow
+for multiple pull requests to coexist; we outline one such method
+below. We assume that you have a fork of yt at
+``http://bitbucket.org/YourUsername/Your_yt`` (see
+:ref:`sharing-changes` for instructions on creating a fork) and that
+you have an active pull request to the main repository.
+
+The main issue with starting another pull request is to make sure that
+your push to BitBucket doesn't go to the same head as your
+existing pull request and trigger BitBucket's auto-update feature.
+Here's how to get your local repository away from your current pull
+request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
+and your ``hgrc`` file:
+
+#. Set up a Mercurial path for the main yt repository (note this is a convenience
+ step and only needs to be done once). Add the following to your
+ ``Your_yt/.hg/hgrc``::
+
+ [paths]
+ upstream = https://bitbucket.org/yt_analysis/yt
+
+ This will create a path called ``upstream`` that is aliased to the URL of the
+ main yt repository.
+#. Now we'll use revsets_ to update your local repository to the tip of the
+ ``upstream`` path:
+
+ .. code-block:: bash
+
+ $ hg pull upstream
+ $ hg update -r "remote(yt, 'upstream')"
+
+After the above steps, your local repository should be at the current head of
+the ``yt`` branch in the main yt repository. If you find yourself doing this a
+lot, it may be worth aliasing this task in your ``hgrc`` file by adding
+something like::
+
+ [alias]
+ ytupdate = update -r "remote(yt, 'upstream')"
+
+And then you can just issue ``hg ytupdate`` to get at the current head of the
+``yt`` branch on main yt repository.
+
+Make sure you are on the branch you want to be on, and then you can make changes
+and ``hg commit`` them. If you prefer working with `bookmarks
+<http://mercurial-scm.org/wiki/Bookmarks>`_, you may want to make a bookmark
+before committing your changes, such as ``hg bookmark mybookmark``.
+
+To push your changes on a bookmark to bitbucket, you can issue the following
+command:
+
+.. code-block:: bash
+
+ $ hg push -B myfeature https://bitbucket.org/YourUsername/Your_yt
+
+The ``-B`` means "publish my bookmark, the changeset the bookmark is pointing
+at, and any ancestors of that changeset that aren't already on the remote
+server".
+
+To push to your fork on BitBucket if you didn't use a bookmark, you issue the
+following:
+
+.. code-block:: bash
+
+ $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
+
+The ``-r .`` means "push only the commit I'm standing on and any ancestors."
+The ``-f`` is to force Mecurial to do the push since we are creating a new
+remote head without a bookmark.
+
+You can then go to the BitBucket interface and issue a new pull request based on
+your last changes, as usual.
.. _code-style-guide:
-Style Guide for Coding in yt
-============================
+Coding Style Guide
+==================
+
+Automatically checking code style
+---------------------------------
Below are a list of rules for coding style in yt. Some of these rules are
suggestions are not explicitly enforced, while some are enforced via automated
@@ -758,13 +752,15 @@
$ flake8 ./yt
This will print out any ``flake8`` errors or warnings that your newly added code
-triggers. The errors in your newly added code because we have already cleaned up
-the yt codebase. Note that this will only trigger a subset of the full
-``flake8`` error and warning list, since we explicitly blacklist a large number
-of the full list of rules that are checked by ``flake8`` by default.
+triggers. The errors will be in your newly added code because we have already
+cleaned up the rest of the yt codebase of the errors and warnings detected by
+the `flake8` tool. Note that this will only trigger a subset of the `full flake8
+error and warning list<http://flake8.readthedocs.org/en/latest/warnings.html>`_,
+since we explicitly blacklist a large number of the full list of rules that are
+checked by ``flake8`` by default.
-Coding Style Guide
-------------------
+Source code style guide
+-----------------------
* In general, follow PEP-8 guidelines.
http://www.python.org/dev/peps/pep-0008/
@@ -805,8 +801,8 @@
* Add tests for new functionality. When fixing a bug, consider adding a test to
prevent the bug from recurring.
-API Guide
----------
+API Style Guide
+---------------
* Do not use ``from some_module import *``
* Internally, only import from source files directly -- instead of:
@@ -921,7 +917,7 @@
--------
These are written in doctest format, and should illustrate how to
use the function. Use the variables 'ds' for the dataset, 'pc' for
- a plot collection, 'c' for a center, and 'L' for a vector.
+ a plot collection, 'c' for a center, and 'L' for a vector.
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
@@ -932,7 +928,6 @@
"""
-
Variable Names and Enzo-isms
----------------------------
Avoid Enzo-isms. This includes but is not limited to:
@@ -959,4 +954,3 @@
everywhere.
* Variable names should be short but descriptive.
* No globals!
-
diff -r 8ed1165917d7a1ca16d011e7b05f4e5bc7a28506 -r ddee190fe850bbb6212683091e687c8a6e89f9ff doc/source/reference/changelog.rst
--- a/doc/source/reference/changelog.rst
+++ b/doc/source/reference/changelog.rst
@@ -644,7 +644,7 @@
* libconfig is now included
* SQLite3 and Forthon now included by default in the install script
* Development guide has been lengthened substantially and a development
- bootstrap script (:ref:`bootstrap-dev`) is now included.
+ bootstrap script is now included.
* Installation script now installs Python 2.7 and HDF5 1.8.6
* iyt now tab-completes field names
* Halos can now be stored on-disk much more easily between HaloFinding runs.
https://bitbucket.org/yt_analysis/yt/commits/32e3c2c88c1a/
Changeset: 32e3c2c88c1a
Branch: yt
User: ngoldbaum
Date: 2015-11-21 04:22:19+00:00
Summary: Break up long line
Affected #: 1 file
diff -r ddee190fe850bbb6212683091e687c8a6e89f9ff -r 32e3c2c88c1a10ea99510dcb82d7c3903a692467 CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -29,7 +29,8 @@
a much lower-traffic mailing list designed to focus on discussions of
improvements to the code, ideas about planning, development issues, and so
on.
- * Many yt developers participate in the yt Slack community. Slack is a free chat service that many teams use to organize development. You can get an
+ * Many yt developers participate in the yt Slack community. Slack is a free
+ chat service that many teams use to organize development. You can get an
invite to yt's Slack organization by clicking the "Join us @ Slack" button
on this page: http://yt-project.org/community.html
* `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
https://bitbucket.org/yt_analysis/yt/commits/9eaf54810bd4/
Changeset: 9eaf54810bd4
Branch: yt
User: ngoldbaum
Date: 2015-11-21 04:48:06+00:00
Summary: Adding sample issue searches
Affected #: 1 file
diff -r 32e3c2c88c1a10ea99510dcb82d7c3903a692467 -r 9eaf54810bd4d8c8c1167d835162a81a3f4ce373 CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -246,6 +246,12 @@
"moderate" are actually easier than their milestone label indicates since that
is the default value.
+Here are some predefined issue searches that might be useful:
+
+* Unresolved issues `marked "easy" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&status=open&status=new>`_.
+* Unresolved issues `marked "easy" or "moderate" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&milestone=moderate&status=open&status=new>`_
+* `All unresolved issues <https://bitbucket.org/yt_analysis/yt/issues?status=open&status=new>`_
+
Submitting Changes
------------------
https://bitbucket.org/yt_analysis/yt/commits/c8987be5e1e2/
Changeset: c8987be5e1e2
Branch: yt
User: ngoldbaum
Date: 2015-11-23 18:53:54+00:00
Summary: Fixing link formatting.
Affected #: 1 file
diff -r 9eaf54810bd4d8c8c1167d835162a81a3f4ce373 -r c8987be5e1e249812640e474363cea5894b18685 CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -762,9 +762,10 @@
triggers. The errors will be in your newly added code because we have already
cleaned up the rest of the yt codebase of the errors and warnings detected by
the `flake8` tool. Note that this will only trigger a subset of the `full flake8
-error and warning list<http://flake8.readthedocs.org/en/latest/warnings.html>`_,
-since we explicitly blacklist a large number of the full list of rules that are
-checked by ``flake8`` by default.
+error and warning list
+<http://flake8.readthedocs.org/en/latest/warnings.html>`_, since we explicitly
+blacklist a large number of the full list of rules that are checked by
+``flake8`` by default.
Source code style guide
-----------------------
https://bitbucket.org/yt_analysis/yt/commits/46d68d42bf02/
Changeset: 46d68d42bf02
Branch: yt
User: ngoldbaum
Date: 2015-11-23 18:58:26+00:00
Summary: Correcting number of communication channels
Affected #: 1 file
diff -r c8987be5e1e249812640e474363cea5894b18685 -r 46d68d42bf02fcd336aa5db0f9ea964b1099648a CONTRIBUTING
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -16,12 +16,16 @@
Communication Channels
----------------------
-There are four main communication channels for yt:
+There are five main communication channels for yt:
* We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
You can connect through our web
gateway without any special client, at http://yt-project.org/irc.html .
*IRC is the first stop for conversation!*
+ * Many yt developers participate in the yt Slack community. Slack is a free
+ chat service that many teams use to organize their work. You can get an
+ invite to yt's Slack organization by clicking the "Join us @ Slack" button
+ on this page: http://yt-project.org/community.html
* `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
is a relatively high-traffic mailing list where people are encouraged to ask
questions about the code, figure things out and so on.
@@ -29,10 +33,6 @@
a much lower-traffic mailing list designed to focus on discussions of
improvements to the code, ideas about planning, development issues, and so
on.
- * Many yt developers participate in the yt Slack community. Slack is a free
- chat service that many teams use to organize development. You can get an
- invite to yt's Slack organization by clicking the "Join us @ Slack" button
- on this page: http://yt-project.org/community.html
* `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
the (now-inaccurately titled) mailing list where all pushes to the primary
repository are sent.
https://bitbucket.org/yt_analysis/yt/commits/bf6e64cbf700/
Changeset: bf6e64cbf700
Branch: yt
User: ngoldbaum
Date: 2015-11-23 19:28:40+00:00
Summary: Making the contributing file an rst file
Affected #: 3 files
diff -r 46d68d42bf02fcd336aa5db0f9ea964b1099648a -r bf6e64cbf7006f9e20136bd440bad66372cf26b0 CONTRIBUTING
--- a/CONTRIBUTING
+++ /dev/null
@@ -1,964 +0,0 @@
-.. This document is rendered in HTML with cross-reference links filled in at
- http://yt-project.org/doc/developing/
-
-.. _getting-involved:
-
-Getting Involved
-================
-
-There are *lots* of ways to get involved with yt, as a community and as a
-technical system -- not all of them just contributing code, but also
-participating in the community, helping us with designing the websites, adding
-documentation, and sharing your scripts with others.
-
-Coding is only one way to be involved!
-
-Communication Channels
-----------------------
-
-There are five main communication channels for yt:
-
- * We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
- You can connect through our web
- gateway without any special client, at http://yt-project.org/irc.html .
- *IRC is the first stop for conversation!*
- * Many yt developers participate in the yt Slack community. Slack is a free
- chat service that many teams use to organize their work. You can get an
- invite to yt's Slack organization by clicking the "Join us @ Slack" button
- on this page: http://yt-project.org/community.html
- * `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
- is a relatively high-traffic mailing list where people are encouraged to ask
- questions about the code, figure things out and so on.
- * `yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_ is
- a much lower-traffic mailing list designed to focus on discussions of
- improvements to the code, ideas about planning, development issues, and so
- on.
- * `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
- the (now-inaccurately titled) mailing list where all pushes to the primary
- repository are sent.
-
-The easiest way to get involved with yt is to read the mailing lists, hang out
-in IRC or slack chat, and participate. If someone asks a question you know the
-answer to (or have your own question about!) write back and answer it.
-
-If you have an idea about something, suggest it! We not only welcome
-participation, we encourage it.
-
-Documentation
--------------
-
-The yt documentation is constantly being updated, and it is a task we would very
-much appreciate assistance with. Whether that is adding a section, updating an
-outdated section, contributing typo or grammatical fixes, adding a FAQ, or
-increasing coverage of functionality, it would be very helpful if you wanted to
-help out.
-
-The easiest way to help out is to fork the main yt repository (where the
-documentation lives in the ``doc`` directory in the root of the yt mercurial
-repository) and then make your changes in your own fork. When you are done,
-issue a pull request through the website for your new fork, and we can comment
-back and forth and eventually accept your changes. See :ref:`sharing-changes` for
-more information about contributing your changes to yt on bitbucket.
-
-Gallery Images and Videos
--------------------------
-
-If you have an image or video you'd like to display in the image or video
-galleries, getting it included it easy! You can either fork the `yt homepage
-repository <http://bitbucket.org/yt_analysis/website>`_ and add it there, or
-email it to us and we'll add it to the `Gallery
-<http://yt-project.org/gallery.html>`_.
-
-We're eager to show off the images and movies you make with yt, so please feel
-free to drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
-a line and let us know if you've got something great!
-
-Technical Contributions
------------------------
-
-Contributing code is another excellent way to participate -- whether it's
-bug fixes, new features, analysis modules, or a new code frontend. See
-:ref:`creating_frontend` for more details.
-
-The process is pretty simple: fork on BitBucket, make changes, issue a pull
-request. We can then go back and forth with comments in the pull request, but
-usually we end up accepting.
-
-For more information, see :ref:`contributing-code`, where we spell out how to
-get up and running with a development environment, how to commit, and how to
-use BitBucket.
-
-Online Presence
----------------
-
-Some of these fall under the other items, but if you'd like to help out with
-the website or any of the other ways yt is presented online, please feel free!
-Almost everything is kept in hg repositories on BitBucket, and it is very easy
-to fork and contribute back changes.
-
-Please feel free to dig in and contribute changes.
-
-Word of Mouth
--------------
-
-If you're using yt and it has increased your productivity, please feel
-encouraged to share that information. Cite our `paper
-<http://adsabs.harvard.edu/abs/2011ApJS..192....9T>`_, tell your colleagues,
-and just spread word of mouth. By telling people about your successes, you'll
-help bring more eyes and hands to the table -- in this manner, by increasing
-participation, collaboration, and simply spreading the limits of what the code
-is asked to do, we hope to help scale the utility and capability of yt with the
-community size.
-
-Feel free to `blog <http://blog.yt-project.org/>`_ about, `tweet
-<http://twitter.com/yt_astro>`_ about and talk about what you are up to!
-
-Long-Term Projects
-------------------
-
-There are some wild-eyed, out-there ideas that have been bandied about for the
-future directions of yt -- some of them even written into the mission
-statement. The ultimate goal is to move past simple analysis and visualization
-of data and begin to approach it from the other side, of generating data,
-running solvers. We also hope to increase its ability to act as an in situ
-analysis code, by presenting a unified protocol. Other projects include
-interfacing with ParaView and VisIt, creating a web GUI for running
-simulations, creating a run-tracker that follows simulations in progress, a
-federated database for simulation outputs, and so on and so forth.
-
-yt is an ambitious project. Let's be ambitious together.
-
-yt Community Code of Conduct
-----------------------------
-
-The community of participants in open source
-Scientific projects is made up of members from around the
-globe with a diverse set of skills, personalities, and
-experiences. It is through these differences that our
-community experiences success and continued growth. We
-expect everyone in our community to follow these guidelines
-when interacting with others both inside and outside of our
-community. Our goal is to keep ours a positive, inclusive,
-successful, and growing community.
-
-As members of the community,
-
-- We pledge to treat all people with respect and
- provide a harassment- and bullying-free environment,
- regardless of sex, sexual orientation and/or gender
- identity, disability, physical appearance, body size,
- race, nationality, ethnicity, and religion. In
- particular, sexual language and imagery, sexist,
- racist, or otherwise exclusionary jokes are not
- appropriate.
-
-- We pledge to respect the work of others by
- recognizing acknowledgment/citation requests of
- original authors. As authors, we pledge to be explicit
- about how we want our own work to be cited or
- acknowledged.
-
-- We pledge to welcome those interested in joining the
- community, and realize that including people with a
- variety of opinions and backgrounds will only serve to
- enrich our community. In particular, discussions
- relating to pros/cons of various technologies,
- programming languages, and so on are welcome, but
- these should be done with respect, taking proactive
- measure to ensure that all participants are heard and
- feel confident that they can freely express their
- opinions.
-
-- We pledge to welcome questions and answer them
- respectfully, paying particular attention to those new
- to the community. We pledge to provide respectful
- criticisms and feedback in forums, especially in
- discussion threads resulting from code
- contributions.
-
-- We pledge to be conscientious of the perceptions of
- the wider community and to respond to criticism
- respectfully. We will strive to model behaviors that
- encourage productive debate and disagreement, both
- within our community and where we are criticized. We
- will treat those outside our community with the same
- respect as people within our community.
-
-- We pledge to help the entire community follow the
- code of conduct, and to not remain silent when we see
- violations of the code of conduct. We will take action
- when members of our community violate this code such as
- contacting confidential at yt-project.org (all emails sent to
- this address will be treated with the strictest
- confidence) or talking privately with the person.
-
-This code of conduct applies to all
-community situations online and offline, including mailing
-lists, forums, social media, conferences, meetings,
-associated social events, and one-to-one interactions.
-
-The yt Community Code of Conduct was adapted from the
-`Astropy Community Code of Conduct
-<http://www.astropy.org/about.html#codeofconduct>`_,
-which was partially inspired by the PSF code of conduct.
-
-.. _contributing-code:
-
-How to Develop yt
-=================
-
-yt is a community project!
-
-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.
-
-.. note:: If you already know how to use the `mercurial version control system
- <http://mercurial-scm.org>`_ and are comfortable with handling it yourself,
- the quickest way to contribute to yt is to `fork us on BitBucket
- <http://bitbucket.org/yt_analysis/yt/fork>`_, make your changes, push the
- changes to your fork and issue a `pull request
- <http://bitbucket.org/yt_analysis/yt/pull-requests>`_. The rest of this
- document is just an explanation of how to do that.
-
-See :ref:`code-style-guide` for more information about coding style in yt and
-:ref:`docstrings` for an example docstring. Please read them before hacking on
-the codebase, and feel free to email any of the mailing lists for help with the
-codebase.
-
-Keep in touch, and happy hacking!
-
-.. _open-issues:
-
-Open Issues
------------
-
-If you're interested in participating in yt development, take a look at the
-`issue tracker on bitbucket
-<https://bitbucket.org/yt_analysis/yt/issues?milestone=easy?status=new>`_.
-Issues are marked with a milestone of "easy", "moderate", or "difficult"
-depending on the estimated level of difficulty for fixing the issue. While we
-try to triage the issue tracker regularly, it may be the case that issues marked
-"moderate" are actually easier than their milestone label indicates since that
-is the default value.
-
-Here are some predefined issue searches that might be useful:
-
-* Unresolved issues `marked "easy" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&status=open&status=new>`_.
-* Unresolved issues `marked "easy" or "moderate" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&milestone=moderate&status=open&status=new>`_
-* `All unresolved issues <https://bitbucket.org/yt_analysis/yt/issues?status=open&status=new>`_
-
-Submitting Changes
-------------------
-
-We provide a brief introduction to submitting changes here. yt thrives on the
-strength of its communities (http://arxiv.org/abs/1301.7064 has further
-discussion) and we encourage contributions from any user. While we do not
-discuss version control, mercurial or the advanced usage of BitBucket in detail
-here, we do provide an outline of how to submit changes and we are happy to
-provide further assistance or guidance.
-
-Licensing
-+++++++++
-
-yt is `licensed <http://blog.yt-project.org/post/Relicensing.html>`_ under the
-BSD 3-clause license. Versions previous to yt-2.6 were released under the GPLv3.
-
-All contributed code must be BSD-compatible. If you'd rather not license in
-this manner, but still want to contribute, please consider creating an external
-package, which we'll happily link to.
-
-How To Get The Source Code For Editing
-++++++++++++++++++++++++++++++++++++++
-
-yt is hosted on BitBucket, and you can see all of the yt repositories at
-http://bitbucket.org/yt_analysis/. With the yt installation script you should have a
-copy of Mercurial for checking out pieces of code. Make sure you have followed
-the steps above for bootstrapping your development (to assure you have a
-bitbucket account, etc.)
-
-In order to modify the source code for yt, we ask that you make a "fork" of the
-main yt repository on bitbucket. A fork is simply an exact copy of the main
-repository (along with its history) that you will now own and can make
-modifications as you please. You can create a personal fork by visiting the yt
-bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in,
-you should see an option near the top right labeled "fork". Click this option,
-and then click the fork repository button on the subsequent page. You now have
-a forked copy of the yt repository for your own personal modification.
-
-This forked copy exists on the bitbucket repository, so in order to access
-it locally, follow the instructions at the top of that webpage for that
-forked repository, namely run at a local command line:
-
-.. code-block:: bash
-
- $ hg clone http://bitbucket.org/<USER>/<REPOSITORY_NAME>
-
-This downloads that new forked repository to your local machine, so that you
-can access it, read it, make modifications, etc. It will put the repository in
-a local directory of the same name as the repository in the current working
-directory. You can see any past state of the code by using the hg log command.
-For example, the following command would show you the last 5 changesets
-(modifications to the code) that were submitted to that repository.
-
-.. code-block:: bash
-
- $ cd <REPOSITORY_NAME>
- $ hg log -l 5
-
-Using the revision specifier (the number or hash identifier next to each
-changeset), you can update the local repository to any past state of the
-code (a previous changeset or version) by executing the command:
-
-.. code-block:: bash
-
- $ hg up revision_specifier
-
-Lastly, if you want to use this new downloaded version of your yt repository as
-the *active* version of yt on your computer (i.e. the one which is executed when
-you run yt from the command line or the one that is loaded when you do ``import
-yt``), then you must "activate" it using the following commands from within the
-repository directory.
-
-.. code-block:: bash
-
- $ cd <REPOSITORY_NAME>
- $ python2.7 setup.py develop
-
-This will rebuild all C modules as well.
-
-.. _reading-source:
-
-How To Read The Source Code
-+++++++++++++++++++++++++++
-
-If you just want to *look* at the source code, you may already have it on your
-computer. If you build yt using the install script, the source is available at
-``$YT_DEST/src/yt-hg``. See :ref:`source-installation` for more details about
-to obtain the yt source code if you did not build yt using the install
-script.
-
-The root directory of the yt mercurial repository contains a number of
-subdirectories with different components of the code. Most of the yt source
-code is contained in the yt subdirectory. This directory its self contains
-the following subdirectories:
-
-``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, Dataset
- and AMRHierarchy are defined.
- * ``io.py``, where a subclass of IOHandler is defined.
- * ``fields.py``, where fields we expect to find in datasets are 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.)
-
-``fields``
- This is where all of the derived fields that ship with yt are defined.
-
-``geometry``
- This is where geometric helpler routines are defined. Handlers
- for grid and oct data, as well as helpers for coordinate transformations
- can be found here.
-
-``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.
-
-``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.
-
-``extern``
- Bundled external modules (i.e. code that was not written by one of
- the yt authors but that yt depends on) lives here.
-
-
-If you're looking for a specific file or function in the yt source code, use
-the unix find command:
-
-.. code-block:: bash
-
- $ find <DIRECTORY_TREE_TO_SEARCH> -name '<FILENAME>'
-
-The above command will find the FILENAME in any subdirectory in the
-DIRECTORY_TREE_TO_SEARCH. Alternatively, if you're looking for a function
-call or a keyword in an unknown file in a directory tree, try:
-
-.. code-block:: bash
-
- $ grep -R <KEYWORD_TO_FIND><DIRECTORY_TREE_TO_SEARCH>
-
-This can be very useful for tracking down functions in the yt source.
-
-.. _building-yt:
-
-Building yt
-+++++++++++
-
-If you have made changes to any C or Cython (``.pyx``) modules, you have to
-rebuild yt. If your changes have exclusively been to Python modules, you will
-not need to re-build, but (see below) you may need to re-install.
-
-If you are running from a clone that is executable in-place (i.e., has been
-installed via the installation script or you have run ``setup.py develop``) you
-can rebuild these modules by executing:
-
-.. code-block:: bash
-
- $ python2.7 setup.py develop
-
-If you have previously "installed" via ``setup.py install`` you have to
-re-install:
-
-.. code-block:: bash
-
- $ python2.7 setup.py install
-
-Only one of these two options is needed.
-
-.. _windows-developing:
-
-Developing yt on Windows
-------------------------
-
-If you plan to develop yt on Windows, it is necessary to use the `MinGW
-<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
-Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
-installed from Anaconda as well. These can both be installed with a single command:
-
-.. code-block:: bash
-
- $ conda install libpython mingw
-
-Additionally, the syntax for the setup command is slightly different; you must type:
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 develop
-
-or
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 install
-
-.. _requirements-for-code-submission:
-
-Requirements for Code Submission
---------------------------------
-
-Modifications to the code typically fall into one of three categories, each of
-which have different requirements for acceptance into the code base. These
-requirements are in place for a few reasons -- to make sure that the code is
-maintainable, testable, and that we can easily include information about
-changes in changelogs during the release procedure. (See `YTEP-0008
-<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
-detail.)
-
-* New Features
-
- * New unit tests (possibly new answer tests) (See :ref:`testing`)
- * Docstrings in the source code for the public API
- * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
- * Addition of cookbook recipe (See :ref:`writing_documentation`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Extension or Breakage of API in Existing Features
-
- * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
- * Update existing cookbook recipes (See :ref:`writing_documentation`)
- * Modify of create new unit tests (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Bug fixes
-
- * Unit test is encouraged, to ensure breakage does not happen again in the
- future. (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-When submitting, you will be asked to make sure that your changes meet all of
-these requirements. They are pretty easy to meet, and we're also happy to help
-out with them. In :ref:`code-style-guide` there is a list of handy tips for
-how to structure and write your code.
-
-.. _mercurial-with-yt:
-
-How to Use Mercurial with yt
-----------------------------
-
-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-scm.org/
-* http://mercurial-scm.org/wiki
-
-The commands that are essential for using mercurial include:
-
-* ``hg help`` which provides help for any mercurial command. For example, you
- can learn more about the ``log`` command by doing ``hg help log``. Other useful
- topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
- ``hg help extensions``, and ``hg help revsets``.
-* ``hg commit`` which commits changes in the working directory to the
- repository, creating a new "changeset object."
-* ``hg add`` which adds a new file to be tracked by mercurial. This does
- not change the working directory.
-* ``hg pull`` which pulls (from an optional path specifier) changeset
- objects from a remote source. The working directory is not modified.
-* ``hg push`` which sends (to an optional path specifier) changeset objects
- to a remote source. The working directory is not modified.
-* ``hg log`` which shows a log of all changeset objects in the current
- repository. Use ``-G`` to show a graph of changeset objects and their
- relationship.
-* ``hg update`` which (with an optional "revision" specifier) updates the
- state of the working directory to match a changeset object in the
- repository.
-* ``hg merge`` which combines two changesets to make a union of their lines
- of development. This updates the working directory.
-
-We are happy to asnswers questions about mercurial use on our IRC, slack
-chat or on the mailing list to walk you through any troubles you might have.
-Here are some general suggestions for using mercurial with yt:
-
-* Named branches are to be avoided. Try using bookmarks (``see hg help
- bookmark``) to track work. (`More info about bookmarks is available on the
- mercurial wiki <http://mercurial-scm.org/wiki/Bookmarks>`_)
-* Make sure you set a username in your ``~/.hgrc`` before you commit any
- changes! All of the tutorials above will describe how to do this as one of
- the very first steps.
-* When contributing changes, you might be asked to make a handful of
- modifications to your source code. We'll work through how to do this with
- you, and try to make it as painless as possible.
-* Your test may fail automated style checks. See :ref:`code-style-guide` for
- more information about automatically verifying your code style.
-* Please avoid deleting your yt forks, as that deletes the pull request
- discussion from process from BitBucket's website, even if your pull request
- is merged.
-* You should only need one fork. To keep it in sync, you can sync from the
- website. See Bitbucket's `Blog Post
- <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
- about this. See :ref:`sharing-changes` for a description of the basic workflow
- and :ref:`multiple-PRs` for a discussion about what to do when you want to
- have multiple open pull requests at the same time.
-* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
- list.
-
-.. _sharing-changes:
-
-Making and Sharing Changes
---------------------------
-
-The simplest way to submit changes to yt is to do the following:
-
-* Build yt from the mercurial repository
-* Navigate to the root of the yt repository
-* Make some changes and commit them
-* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
-* Push the changesets to your fork
-* Issue a pull request.
-
-Here's a more detailed flowchart of how to submit changes.
-
-#. If you have used the installation script, the source code for yt can be
- found in ``$YT_DEST/src/yt-hg``. Alternatively see
- :ref:`source-installation` for instructions on how to build yt from the
- mercurial repository. (Below, in :ref:`reading-source`, we describe how to
- find items of interest.)
-#. Edit the source file you are interested in and
- test your changes. (See :ref:`testing` for more information.)
-#. Fork yt on BitBucket. (This step only has to be done once.) You can do
- this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
- yt.
-#. Create a bookmark to track your work. For example: ``hg bookmark
- my-first-pull-request``
-#. Commit these changes, using ``hg commit``. This can take an argument
- which is a series of filenames, if you have some changes you do not want
- to commit.
-#. Remember that this is a large development effort and to keep the code
- accessible to everyone, good documentation is a must. Add in source code
- comments for what you are doing. Add in docstrings
- if you are adding a new function or class or keyword to a function.
- Add documentation to the appropriate section of the online docs so that
- people other than yourself know how to use your new code.
-#. If your changes include new functionality or cover an untested area of the
- code, add a test. (See :ref:`testing` for more information.) Commit
- these changes as well.
-#. Push your changes to your new fork using the command::
-
- hg push -B my-first-pull-request https://bitbucket.org/YourUsername/yt/
-
- Where you should substitute the name of the bookmark you are working on for
- ``my-first-pull-request``. If you end up doing considerable development, you
- can set an alias in the file ``.hg/hgrc`` to point to this path.
-
- .. note::
- Note that the above approach uses HTTPS as the transfer protocol
- between your machine and BitBucket. If you prefer to use SSH - or
- perhaps you're behind a proxy that doesn't play well with SSL via
- HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
- the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
- place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
- For consistency, all commands we list in this document will use the HTTPS
- protocol.
-
- .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
-
-#. Issue a pull request at
- https://bitbucket.org/YourUsername/yt/pull-request/new
- A pull request is essentially just asking people to review and accept the
- modifications you have made to your personal version of the code.
-
-
-During the course of your pull request you may be asked to make changes. These
-changes may be related to style issues, correctness issues, or even requesting
-tests. The process for responding to pull request code review is relatively
-straightforward.
-
-#. Make requested changes, or leave a comment indicating why you don't think
- they should be made.
-#. Commit those changes to your local repository.
-#. Push the changes to your fork:
-
- hg push https://bitbucket.org/YourUsername/yt/
-
-#. Your pull request will be automatically updated.
-
-.. _multiple-PRs:
-
-Working with Multiple BitBucket Pull Requests
-+++++++++++++++++++++++++++++++++++++++++++++
-
-Once you become active developing for yt, you may be working on
-various aspects of the code or bugfixes at the same time. Currently,
-BitBucket's *modus operandi* for pull requests automatically updates
-your active pull request with every ``hg push`` of commits that are a
-descendant of the head of your pull request. In a normal workflow,
-this means that if you have an active pull request, make some changes
-locally for, say, an unrelated bugfix, then push those changes back to
-your fork in the hopes of creating a *new* pull request, you'll
-actually end up updating your current pull request!
-
-There are a few ways around this feature of BitBucket that will allow
-for multiple pull requests to coexist; we outline one such method
-below. We assume that you have a fork of yt at
-``http://bitbucket.org/YourUsername/Your_yt`` (see
-:ref:`sharing-changes` for instructions on creating a fork) and that
-you have an active pull request to the main repository.
-
-The main issue with starting another pull request is to make sure that
-your push to BitBucket doesn't go to the same head as your
-existing pull request and trigger BitBucket's auto-update feature.
-Here's how to get your local repository away from your current pull
-request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
-and your ``hgrc`` file:
-
-#. Set up a Mercurial path for the main yt repository (note this is a convenience
- step and only needs to be done once). Add the following to your
- ``Your_yt/.hg/hgrc``::
-
- [paths]
- upstream = https://bitbucket.org/yt_analysis/yt
-
- This will create a path called ``upstream`` that is aliased to the URL of the
- main yt repository.
-#. Now we'll use revsets_ to update your local repository to the tip of the
- ``upstream`` path:
-
- .. code-block:: bash
-
- $ hg pull upstream
- $ hg update -r "remote(yt, 'upstream')"
-
-After the above steps, your local repository should be at the current head of
-the ``yt`` branch in the main yt repository. If you find yourself doing this a
-lot, it may be worth aliasing this task in your ``hgrc`` file by adding
-something like::
-
- [alias]
- ytupdate = update -r "remote(yt, 'upstream')"
-
-And then you can just issue ``hg ytupdate`` to get at the current head of the
-``yt`` branch on main yt repository.
-
-Make sure you are on the branch you want to be on, and then you can make changes
-and ``hg commit`` them. If you prefer working with `bookmarks
-<http://mercurial-scm.org/wiki/Bookmarks>`_, you may want to make a bookmark
-before committing your changes, such as ``hg bookmark mybookmark``.
-
-To push your changes on a bookmark to bitbucket, you can issue the following
-command:
-
-.. code-block:: bash
-
- $ hg push -B myfeature https://bitbucket.org/YourUsername/Your_yt
-
-The ``-B`` means "publish my bookmark, the changeset the bookmark is pointing
-at, and any ancestors of that changeset that aren't already on the remote
-server".
-
-To push to your fork on BitBucket if you didn't use a bookmark, you issue the
-following:
-
-.. code-block:: bash
-
- $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
-
-The ``-r .`` means "push only the commit I'm standing on and any ancestors."
-The ``-f`` is to force Mecurial to do the push since we are creating a new
-remote head without a bookmark.
-
-You can then go to the BitBucket interface and issue a new pull request based on
-your last changes, as usual.
-
-.. _code-style-guide:
-
-Coding Style Guide
-==================
-
-Automatically checking code style
----------------------------------
-
-Below are a list of rules for coding style in yt. Some of these rules are
-suggestions are not explicitly enforced, while some are enforced via automated
-testing. The yt project uses a subset of the rules checked by ``flake8`` to
-verify our code. The ``flake8`` tool is a combination of the ``pyflakes`` and
-``pep8`` tools. To check the coding style of your contributions locally you will
-need to install the ``flake8`` tool from ``pip``:
-
- $ pip install flake8
-
-And then navigate to the root of the yt repository and run ``flake8`` on the
-``yt`` folder:
-
- $ cd $YT_HG
- $ flake8 ./yt
-
-This will print out any ``flake8`` errors or warnings that your newly added code
-triggers. The errors will be in your newly added code because we have already
-cleaned up the rest of the yt codebase of the errors and warnings detected by
-the `flake8` tool. Note that this will only trigger a subset of the `full flake8
-error and warning list
-<http://flake8.readthedocs.org/en/latest/warnings.html>`_, since we explicitly
-blacklist a large number of the full list of rules that are checked by
-``flake8`` by default.
-
-Source code style guide
------------------------
-
- * In general, follow PEP-8 guidelines.
- http://www.python.org/dev/peps/pep-0008/
- * Classes are ``ConjoinedCapitals``, methods and functions are
- ``lowercase_with_underscores``.
- * Use 4 spaces, not tabs, to represent indentation.
- * Line widths should not be more than 80 characters.
- * Do not use nested classes unless you have a very good reason to, such as
- requiring a namespace or class-definition modification. Classes should live
- at the top level. ``__metaclass__`` is exempt from this.
- * Do not use unnecessary parenthesis in conditionals. ``if((something) and
- (something_else))`` should be rewritten as
- ``if something and something_else``. Python is more forgiving than C.
- * Avoid copying memory when possible. For example, don't do
- ``a = a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3``
- should be ``np.multiply(a, 3, a)``.
- * In general, avoid all double-underscore method names: ``__something`` is
- usually unnecessary.
- * When writing a subclass, use the super built-in to access the super class,
- rather than explicitly. Ex: ``super(SpecialGridSubclass, self).__init__()``
- rather than ``SpecialGrid.__init__()``.
- * Docstrings should describe input, output, behavior, and any state changes
- that occur on an object. See the file ``doc/docstring_example.txt`` for a
- fiducial example of a docstring.
- * Use only one top-level import per line. Unless there is a good reason not to,
- imports should happen at the top of the file, after the copyright blurb.
- * Never compare with ``True`` or ``False`` using ``==`` or ``!=``, always use
- ``is`` or ``is not``.
- * If you are comparing with a numpy boolean array, just refer to the array.
- Ex: do ``np.all(array)`` instead of ``np.all(array == True)``.
- * Never comapre with None using ``==`` or ``!=``, use ``is None`` or
- ``is not None``.
- * Use ``statement is not True`` instead of ``not statement is True``
- * Only one statement per line, do not use semicolons to put two or more
- statements on a single line.
- * Only declare local variables if they will be used later. If you do not use the
- return value of a function, do not store it in a variable.
- * Add tests for new functionality. When fixing a bug, consider adding a test to
- prevent the bug from recurring.
-
-API Style Guide
----------------
-
- * Do not use ``from some_module import *``
- * Internally, only import from source files directly -- instead of:
-
- ``from yt.visualization.api import ProjectionPlot``
-
- do:
-
- ``from yt.visualization.plot_window import ProjectionPlot``
-
- * Import symbols from the module where they are defined, avoid transitive
- imports.
- * Import standard library modules, functions, and classes from builtins, do not
- import them from other yt files.
- * Numpy is to be imported as ``np``.
- * Do not use too many keyword arguments. If you have a lot of keyword
- arguments, then you are doing too much in ``__init__`` and not enough via
- parameter setting.
- * In function arguments, place spaces before commas. ``def something(a,b,c)``
- should be ``def something(a, b, c)``.
- * Don't create a new class to replicate the functionality of an old class --
- replace the old class. Too many options makes for a confusing user
- experience.
- * Parameter files external to yt are a last resort.
- * The usage of the ``**kwargs`` construction should be avoided. If they cannot
- be avoided, they must be explained, even if they are only to be passed on to
- a nested function.
-
-.. _docstrings
-
-Docstrings
-----------
-
-The following is an example docstring. You can use it as a template for
-docstrings in your code and as a guide for how we expect docstrings to look and
-the level of detail we are looking for. Note that we use NumPy style docstrings
-written in `Sphinx restructured text format <http://sphinx-doc.org/rest.html>`_.
-
- r"""A one-line summary that does not use variable names or the
- function name.
-
- Several sentences providing an extended description. Refer to
- variables using back-ticks, e.g. ``var``.
-
- Parameters
- ----------
- var1 : array_like
- Array_like means all those objects -- lists, nested lists, etc. --
- that can be converted to an array. We can also refer to
- variables like `var1`.
- var2 : int
- The type above can either refer to an actual Python type
- (e.g. ``int``), or describe the type of the variable in more
- detail, e.g. ``(N,) ndarray`` or ``array_like``.
- Long_variable_name : {'hi', 'ho'}, optional
- Choices in brackets, default first when optional.
-
- Returns
- -------
- describe : type
- Explanation
- output : type
- Explanation
- tuple : type
- Explanation
- items : type
- even more explaining
-
- Other Parameters
- ----------------
- only_seldom_used_keywords : type
- Explanation
- common_parameters_listed_above : type
- Explanation
-
- Raises
- ------
- BadException
- Because you shouldn't have done that.
-
- See Also
- --------
- otherfunc : relationship (optional)
- newfunc : Relationship (optional), which could be fairly long, in which
- case the line wraps here.
- thirdfunc, fourthfunc, fifthfunc
-
- Notes
- -----
- Notes about the implementation algorithm (if needed).
-
- This can have multiple paragraphs.
-
- You may include some math:
-
- .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
-
- And even use a greek symbol like :math:`omega` inline.
-
- References
- ----------
- Cite the relevant literature, e.g. [1]_. You may also cite these
- references in the notes section above.
-
- .. [1] O. McNoleg, "The integration of GIS, remote sensing,
- expert systems and adaptive co-kriging for environmental habitat
- modelling of the Highland Haggis using object-oriented, fuzzy-logic
- and neural-network techniques," Computers & Geosciences, vol. 22,
- pp. 585-588, 1996.
-
- Examples
- --------
- These are written in doctest format, and should illustrate how to
- use the function. Use the variables 'ds' for the dataset, 'pc' for
- a plot collection, 'c' for a center, and 'L' for a vector.
-
- >>> a=[1,2,3]
- >>> print [x + 3 for x in a]
- [4, 5, 6]
- >>> print "a\n\nb"
- a
- b
-
- """
-
-Variable Names and Enzo-isms
-----------------------------
-Avoid Enzo-isms. This includes but is not limited to:
-
- * Hard-coding parameter names that are the same as those in Enzo. The
- following translation table should be of some help. Note that the
- parameters are now properties on a ``Dataset`` subclass: you access them
- like ds.refine_by .
-
- - ``RefineBy `` => `` refine_by``
- - ``TopGridRank `` => `` dimensionality``
- - ``TopGridDimensions `` => `` domain_dimensions``
- - ``InitialTime `` => `` current_time``
- - ``DomainLeftEdge `` => `` domain_left_edge``
- - ``DomainRightEdge `` => `` domain_right_edge``
- - ``CurrentTimeIdentifier `` => `` unique_identifier``
- - ``CosmologyCurrentRedshift `` => `` current_redshift``
- - ``ComovingCoordinates `` => `` cosmological_simulation``
- - ``CosmologyOmegaMatterNow `` => `` omega_matter``
- - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
- - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
-
- * Do not assume that the domain runs from 0 .. 1. This is not true
- everywhere.
- * Variable names should be short but descriptive.
- * No globals!
diff -r 46d68d42bf02fcd336aa5db0f9ea964b1099648a -r bf6e64cbf7006f9e20136bd440bad66372cf26b0 CONTRIBUTING.rst
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,964 @@
+.. This document is rendered in HTML with cross-reference links filled in at
+ http://yt-project.org/doc/developing/
+
+.. _getting-involved:
+
+Getting Involved
+================
+
+There are *lots* of ways to get involved with yt, as a community and as a
+technical system -- not all of them just contributing code, but also
+participating in the community, helping us with designing the websites, adding
+documentation, and sharing your scripts with others.
+
+Coding is only one way to be involved!
+
+Communication Channels
+----------------------
+
+There are five main communication channels for yt:
+
+ * We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
+ You can connect through our web
+ gateway without any special client, at http://yt-project.org/irc.html .
+ *IRC is the first stop for conversation!*
+ * Many yt developers participate in the yt Slack community. Slack is a free
+ chat service that many teams use to organize their work. You can get an
+ invite to yt's Slack organization by clicking the "Join us @ Slack" button
+ on this page: http://yt-project.org/community.html
+ * `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
+ is a relatively high-traffic mailing list where people are encouraged to ask
+ questions about the code, figure things out and so on.
+ * `yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_ is
+ a much lower-traffic mailing list designed to focus on discussions of
+ improvements to the code, ideas about planning, development issues, and so
+ on.
+ * `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
+ the (now-inaccurately titled) mailing list where all pushes to the primary
+ repository are sent.
+
+The easiest way to get involved with yt is to read the mailing lists, hang out
+in IRC or slack chat, and participate. If someone asks a question you know the
+answer to (or have your own question about!) write back and answer it.
+
+If you have an idea about something, suggest it! We not only welcome
+participation, we encourage it.
+
+Documentation
+-------------
+
+The yt documentation is constantly being updated, and it is a task we would very
+much appreciate assistance with. Whether that is adding a section, updating an
+outdated section, contributing typo or grammatical fixes, adding a FAQ, or
+increasing coverage of functionality, it would be very helpful if you wanted to
+help out.
+
+The easiest way to help out is to fork the main yt repository (where the
+documentation lives in the ``doc`` directory in the root of the yt mercurial
+repository) and then make your changes in your own fork. When you are done,
+issue a pull request through the website for your new fork, and we can comment
+back and forth and eventually accept your changes. See :ref:`sharing-changes` for
+more information about contributing your changes to yt on bitbucket.
+
+Gallery Images and Videos
+-------------------------
+
+If you have an image or video you'd like to display in the image or video
+galleries, getting it included it easy! You can either fork the `yt homepage
+repository <http://bitbucket.org/yt_analysis/website>`_ and add it there, or
+email it to us and we'll add it to the `Gallery
+<http://yt-project.org/gallery.html>`_.
+
+We're eager to show off the images and movies you make with yt, so please feel
+free to drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
+a line and let us know if you've got something great!
+
+Technical Contributions
+-----------------------
+
+Contributing code is another excellent way to participate -- whether it's
+bug fixes, new features, analysis modules, or a new code frontend. See
+:ref:`creating_frontend` for more details.
+
+The process is pretty simple: fork on BitBucket, make changes, issue a pull
+request. We can then go back and forth with comments in the pull request, but
+usually we end up accepting.
+
+For more information, see :ref:`contributing-code`, where we spell out how to
+get up and running with a development environment, how to commit, and how to
+use BitBucket.
+
+Online Presence
+---------------
+
+Some of these fall under the other items, but if you'd like to help out with
+the website or any of the other ways yt is presented online, please feel free!
+Almost everything is kept in hg repositories on BitBucket, and it is very easy
+to fork and contribute back changes.
+
+Please feel free to dig in and contribute changes.
+
+Word of Mouth
+-------------
+
+If you're using yt and it has increased your productivity, please feel
+encouraged to share that information. Cite our `paper
+<http://adsabs.harvard.edu/abs/2011ApJS..192....9T>`_, tell your colleagues,
+and just spread word of mouth. By telling people about your successes, you'll
+help bring more eyes and hands to the table -- in this manner, by increasing
+participation, collaboration, and simply spreading the limits of what the code
+is asked to do, we hope to help scale the utility and capability of yt with the
+community size.
+
+Feel free to `blog <http://blog.yt-project.org/>`_ about, `tweet
+<http://twitter.com/yt_astro>`_ about and talk about what you are up to!
+
+Long-Term Projects
+------------------
+
+There are some wild-eyed, out-there ideas that have been bandied about for the
+future directions of yt -- some of them even written into the mission
+statement. The ultimate goal is to move past simple analysis and visualization
+of data and begin to approach it from the other side, of generating data,
+running solvers. We also hope to increase its ability to act as an in situ
+analysis code, by presenting a unified protocol. Other projects include
+interfacing with ParaView and VisIt, creating a web GUI for running
+simulations, creating a run-tracker that follows simulations in progress, a
+federated database for simulation outputs, and so on and so forth.
+
+yt is an ambitious project. Let's be ambitious together.
+
+yt Community Code of Conduct
+----------------------------
+
+The community of participants in open source
+Scientific projects is made up of members from around the
+globe with a diverse set of skills, personalities, and
+experiences. It is through these differences that our
+community experiences success and continued growth. We
+expect everyone in our community to follow these guidelines
+when interacting with others both inside and outside of our
+community. Our goal is to keep ours a positive, inclusive,
+successful, and growing community.
+
+As members of the community,
+
+- We pledge to treat all people with respect and
+ provide a harassment- and bullying-free environment,
+ regardless of sex, sexual orientation and/or gender
+ identity, disability, physical appearance, body size,
+ race, nationality, ethnicity, and religion. In
+ particular, sexual language and imagery, sexist,
+ racist, or otherwise exclusionary jokes are not
+ appropriate.
+
+- We pledge to respect the work of others by
+ recognizing acknowledgment/citation requests of
+ original authors. As authors, we pledge to be explicit
+ about how we want our own work to be cited or
+ acknowledged.
+
+- We pledge to welcome those interested in joining the
+ community, and realize that including people with a
+ variety of opinions and backgrounds will only serve to
+ enrich our community. In particular, discussions
+ relating to pros/cons of various technologies,
+ programming languages, and so on are welcome, but
+ these should be done with respect, taking proactive
+ measure to ensure that all participants are heard and
+ feel confident that they can freely express their
+ opinions.
+
+- We pledge to welcome questions and answer them
+ respectfully, paying particular attention to those new
+ to the community. We pledge to provide respectful
+ criticisms and feedback in forums, especially in
+ discussion threads resulting from code
+ contributions.
+
+- We pledge to be conscientious of the perceptions of
+ the wider community and to respond to criticism
+ respectfully. We will strive to model behaviors that
+ encourage productive debate and disagreement, both
+ within our community and where we are criticized. We
+ will treat those outside our community with the same
+ respect as people within our community.
+
+- We pledge to help the entire community follow the
+ code of conduct, and to not remain silent when we see
+ violations of the code of conduct. We will take action
+ when members of our community violate this code such as
+ contacting confidential at yt-project.org (all emails sent to
+ this address will be treated with the strictest
+ confidence) or talking privately with the person.
+
+This code of conduct applies to all
+community situations online and offline, including mailing
+lists, forums, social media, conferences, meetings,
+associated social events, and one-to-one interactions.
+
+The yt Community Code of Conduct was adapted from the
+`Astropy Community Code of Conduct
+<http://www.astropy.org/about.html#codeofconduct>`_,
+which was partially inspired by the PSF code of conduct.
+
+.. _contributing-code:
+
+How to Develop yt
+=================
+
+yt is a community project!
+
+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.
+
+.. note:: If you already know how to use the `mercurial version control system
+ <http://mercurial-scm.org>`_ and are comfortable with handling it yourself,
+ the quickest way to contribute to yt is to `fork us on BitBucket
+ <http://bitbucket.org/yt_analysis/yt/fork>`_, make your changes, push the
+ changes to your fork and issue a `pull request
+ <http://bitbucket.org/yt_analysis/yt/pull-requests>`_. The rest of this
+ document is just an explanation of how to do that.
+
+See :ref:`code-style-guide` for more information about coding style in yt and
+:ref:`docstrings` for an example docstring. Please read them before hacking on
+the codebase, and feel free to email any of the mailing lists for help with the
+codebase.
+
+Keep in touch, and happy hacking!
+
+.. _open-issues:
+
+Open Issues
+-----------
+
+If you're interested in participating in yt development, take a look at the
+`issue tracker on bitbucket
+<https://bitbucket.org/yt_analysis/yt/issues?milestone=easy?status=new>`_.
+Issues are marked with a milestone of "easy", "moderate", or "difficult"
+depending on the estimated level of difficulty for fixing the issue. While we
+try to triage the issue tracker regularly, it may be the case that issues marked
+"moderate" are actually easier than their milestone label indicates since that
+is the default value.
+
+Here are some predefined issue searches that might be useful:
+
+* Unresolved issues `marked "easy" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&status=open&status=new>`_.
+* Unresolved issues `marked "easy" or "moderate" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&milestone=moderate&status=open&status=new>`_
+* `All unresolved issues <https://bitbucket.org/yt_analysis/yt/issues?status=open&status=new>`_
+
+Submitting Changes
+------------------
+
+We provide a brief introduction to submitting changes here. yt thrives on the
+strength of its communities (http://arxiv.org/abs/1301.7064 has further
+discussion) and we encourage contributions from any user. While we do not
+discuss version control, mercurial or the advanced usage of BitBucket in detail
+here, we do provide an outline of how to submit changes and we are happy to
+provide further assistance or guidance.
+
+Licensing
++++++++++
+
+yt is `licensed <http://blog.yt-project.org/post/Relicensing.html>`_ under the
+BSD 3-clause license. Versions previous to yt-2.6 were released under the GPLv3.
+
+All contributed code must be BSD-compatible. If you'd rather not license in
+this manner, but still want to contribute, please consider creating an external
+package, which we'll happily link to.
+
+How To Get The Source Code For Editing
+++++++++++++++++++++++++++++++++++++++
+
+yt is hosted on BitBucket, and you can see all of the yt repositories at
+http://bitbucket.org/yt_analysis/. With the yt installation script you should have a
+copy of Mercurial for checking out pieces of code. Make sure you have followed
+the steps above for bootstrapping your development (to assure you have a
+bitbucket account, etc.)
+
+In order to modify the source code for yt, we ask that you make a "fork" of the
+main yt repository on bitbucket. A fork is simply an exact copy of the main
+repository (along with its history) that you will now own and can make
+modifications as you please. You can create a personal fork by visiting the yt
+bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in,
+you should see an option near the top right labeled "fork". Click this option,
+and then click the fork repository button on the subsequent page. You now have
+a forked copy of the yt repository for your own personal modification.
+
+This forked copy exists on the bitbucket repository, so in order to access
+it locally, follow the instructions at the top of that webpage for that
+forked repository, namely run at a local command line:
+
+.. code-block:: bash
+
+ $ hg clone http://bitbucket.org/<USER>/<REPOSITORY_NAME>
+
+This downloads that new forked repository to your local machine, so that you
+can access it, read it, make modifications, etc. It will put the repository in
+a local directory of the same name as the repository in the current working
+directory. You can see any past state of the code by using the hg log command.
+For example, the following command would show you the last 5 changesets
+(modifications to the code) that were submitted to that repository.
+
+.. code-block:: bash
+
+ $ cd <REPOSITORY_NAME>
+ $ hg log -l 5
+
+Using the revision specifier (the number or hash identifier next to each
+changeset), you can update the local repository to any past state of the
+code (a previous changeset or version) by executing the command:
+
+.. code-block:: bash
+
+ $ hg up revision_specifier
+
+Lastly, if you want to use this new downloaded version of your yt repository as
+the *active* version of yt on your computer (i.e. the one which is executed when
+you run yt from the command line or the one that is loaded when you do ``import
+yt``), then you must "activate" it using the following commands from within the
+repository directory.
+
+.. code-block:: bash
+
+ $ cd <REPOSITORY_NAME>
+ $ python2.7 setup.py develop
+
+This will rebuild all C modules as well.
+
+.. _reading-source:
+
+How To Read The Source Code
++++++++++++++++++++++++++++
+
+If you just want to *look* at the source code, you may already have it on your
+computer. If you build yt using the install script, the source is available at
+``$YT_DEST/src/yt-hg``. See :ref:`source-installation` for more details about
+to obtain the yt source code if you did not build yt using the install
+script.
+
+The root directory of the yt mercurial repository contains a number of
+subdirectories with different components of the code. Most of the yt source
+code is contained in the yt subdirectory. This directory its self contains
+the following subdirectories:
+
+``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, Dataset
+ and AMRHierarchy are defined.
+ * ``io.py``, where a subclass of IOHandler is defined.
+ * ``fields.py``, where fields we expect to find in datasets are 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.)
+
+``fields``
+ This is where all of the derived fields that ship with yt are defined.
+
+``geometry``
+ This is where geometric helpler routines are defined. Handlers
+ for grid and oct data, as well as helpers for coordinate transformations
+ can be found here.
+
+``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.
+
+``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.
+
+``extern``
+ Bundled external modules (i.e. code that was not written by one of
+ the yt authors but that yt depends on) lives here.
+
+
+If you're looking for a specific file or function in the yt source code, use
+the unix find command:
+
+.. code-block:: bash
+
+ $ find <DIRECTORY_TREE_TO_SEARCH> -name '<FILENAME>'
+
+The above command will find the FILENAME in any subdirectory in the
+DIRECTORY_TREE_TO_SEARCH. Alternatively, if you're looking for a function
+call or a keyword in an unknown file in a directory tree, try:
+
+.. code-block:: bash
+
+ $ grep -R <KEYWORD_TO_FIND><DIRECTORY_TREE_TO_SEARCH>
+
+This can be very useful for tracking down functions in the yt source.
+
+.. _building-yt:
+
+Building yt
++++++++++++
+
+If you have made changes to any C or Cython (``.pyx``) modules, you have to
+rebuild yt. If your changes have exclusively been to Python modules, you will
+not need to re-build, but (see below) you may need to re-install.
+
+If you are running from a clone that is executable in-place (i.e., has been
+installed via the installation script or you have run ``setup.py develop``) you
+can rebuild these modules by executing:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py develop
+
+If you have previously "installed" via ``setup.py install`` you have to
+re-install:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py install
+
+Only one of these two options is needed.
+
+.. _windows-developing:
+
+Developing yt on Windows
+------------------------
+
+If you plan to develop yt on Windows, it is necessary to use the `MinGW
+<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
+Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
+installed from Anaconda as well. These can both be installed with a single command:
+
+.. code-block:: bash
+
+ $ conda install libpython mingw
+
+Additionally, the syntax for the setup command is slightly different; you must type:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 develop
+
+or
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 install
+
+.. _requirements-for-code-submission:
+
+Requirements for Code Submission
+--------------------------------
+
+Modifications to the code typically fall into one of three categories, each of
+which have different requirements for acceptance into the code base. These
+requirements are in place for a few reasons -- to make sure that the code is
+maintainable, testable, and that we can easily include information about
+changes in changelogs during the release procedure. (See `YTEP-0008
+<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
+detail.)
+
+* New Features
+
+ * New unit tests (possibly new answer tests) (See :ref:`testing`)
+ * Docstrings in the source code for the public API
+ * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
+ * Addition of cookbook recipe (See :ref:`writing_documentation`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Extension or Breakage of API in Existing Features
+
+ * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
+ * Update existing cookbook recipes (See :ref:`writing_documentation`)
+ * Modify of create new unit tests (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Bug fixes
+
+ * Unit test is encouraged, to ensure breakage does not happen again in the
+ future. (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+When submitting, you will be asked to make sure that your changes meet all of
+these requirements. They are pretty easy to meet, and we're also happy to help
+out with them. In :ref:`code-style-guide` there is a list of handy tips for
+how to structure and write your code.
+
+.. _mercurial-with-yt:
+
+How to Use Mercurial with yt
+----------------------------
+
+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-scm.org/
+* http://mercurial-scm.org/wiki
+
+The commands that are essential for using mercurial include:
+
+* ``hg help`` which provides help for any mercurial command. For example, you
+ can learn more about the ``log`` command by doing ``hg help log``. Other useful
+ topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
+ ``hg help extensions``, and ``hg help revsets``.
+* ``hg commit`` which commits changes in the working directory to the
+ repository, creating a new "changeset object."
+* ``hg add`` which adds a new file to be tracked by mercurial. This does
+ not change the working directory.
+* ``hg pull`` which pulls (from an optional path specifier) changeset
+ objects from a remote source. The working directory is not modified.
+* ``hg push`` which sends (to an optional path specifier) changeset objects
+ to a remote source. The working directory is not modified.
+* ``hg log`` which shows a log of all changeset objects in the current
+ repository. Use ``-G`` to show a graph of changeset objects and their
+ relationship.
+* ``hg update`` which (with an optional "revision" specifier) updates the
+ state of the working directory to match a changeset object in the
+ repository.
+* ``hg merge`` which combines two changesets to make a union of their lines
+ of development. This updates the working directory.
+
+We are happy to asnswers questions about mercurial use on our IRC, slack
+chat or on the mailing list to walk you through any troubles you might have.
+Here are some general suggestions for using mercurial with yt:
+
+* Named branches are to be avoided. Try using bookmarks (``see hg help
+ bookmark``) to track work. (`More info about bookmarks is available on the
+ mercurial wiki <http://mercurial-scm.org/wiki/Bookmarks>`_)
+* Make sure you set a username in your ``~/.hgrc`` before you commit any
+ changes! All of the tutorials above will describe how to do this as one of
+ the very first steps.
+* When contributing changes, you might be asked to make a handful of
+ modifications to your source code. We'll work through how to do this with
+ you, and try to make it as painless as possible.
+* Your test may fail automated style checks. See :ref:`code-style-guide` for
+ more information about automatically verifying your code style.
+* Please avoid deleting your yt forks, as that deletes the pull request
+ discussion from process from BitBucket's website, even if your pull request
+ is merged.
+* You should only need one fork. To keep it in sync, you can sync from the
+ website. See Bitbucket's `Blog Post
+ <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
+ about this. See :ref:`sharing-changes` for a description of the basic workflow
+ and :ref:`multiple-PRs` for a discussion about what to do when you want to
+ have multiple open pull requests at the same time.
+* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
+ list.
+
+.. _sharing-changes:
+
+Making and Sharing Changes
+--------------------------
+
+The simplest way to submit changes to yt is to do the following:
+
+* Build yt from the mercurial repository
+* Navigate to the root of the yt repository
+* Make some changes and commit them
+* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
+* Push the changesets to your fork
+* Issue a pull request.
+
+Here's a more detailed flowchart of how to submit changes.
+
+#. If you have used the installation script, the source code for yt can be
+ found in ``$YT_DEST/src/yt-hg``. Alternatively see
+ :ref:`source-installation` for instructions on how to build yt from the
+ mercurial repository. (Below, in :ref:`reading-source`, we describe how to
+ find items of interest.)
+#. Edit the source file you are interested in and
+ test your changes. (See :ref:`testing` for more information.)
+#. Fork yt on BitBucket. (This step only has to be done once.) You can do
+ this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
+ yt.
+#. Create a bookmark to track your work. For example: ``hg bookmark
+ my-first-pull-request``
+#. Commit these changes, using ``hg commit``. This can take an argument
+ which is a series of filenames, if you have some changes you do not want
+ to commit.
+#. Remember that this is a large development effort and to keep the code
+ accessible to everyone, good documentation is a must. Add in source code
+ comments for what you are doing. Add in docstrings
+ if you are adding a new function or class or keyword to a function.
+ Add documentation to the appropriate section of the online docs so that
+ people other than yourself know how to use your new code.
+#. If your changes include new functionality or cover an untested area of the
+ code, add a test. (See :ref:`testing` for more information.) Commit
+ these changes as well.
+#. Push your changes to your new fork using the command::
+
+ hg push -B my-first-pull-request https://bitbucket.org/YourUsername/yt/
+
+ Where you should substitute the name of the bookmark you are working on for
+ ``my-first-pull-request``. If you end up doing considerable development, you
+ can set an alias in the file ``.hg/hgrc`` to point to this path.
+
+ .. note::
+ Note that the above approach uses HTTPS as the transfer protocol
+ between your machine and BitBucket. If you prefer to use SSH - or
+ perhaps you're behind a proxy that doesn't play well with SSL via
+ HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
+ the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
+ place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
+ For consistency, all commands we list in this document will use the HTTPS
+ protocol.
+
+ .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
+
+#. Issue a pull request at
+ https://bitbucket.org/YourUsername/yt/pull-request/new
+ A pull request is essentially just asking people to review and accept the
+ modifications you have made to your personal version of the code.
+
+
+During the course of your pull request you may be asked to make changes. These
+changes may be related to style issues, correctness issues, or even requesting
+tests. The process for responding to pull request code review is relatively
+straightforward.
+
+#. Make requested changes, or leave a comment indicating why you don't think
+ they should be made.
+#. Commit those changes to your local repository.
+#. Push the changes to your fork:
+
+ hg push https://bitbucket.org/YourUsername/yt/
+
+#. Your pull request will be automatically updated.
+
+.. _multiple-PRs:
+
+Working with Multiple BitBucket Pull Requests
++++++++++++++++++++++++++++++++++++++++++++++
+
+Once you become active developing for yt, you may be working on
+various aspects of the code or bugfixes at the same time. Currently,
+BitBucket's *modus operandi* for pull requests automatically updates
+your active pull request with every ``hg push`` of commits that are a
+descendant of the head of your pull request. In a normal workflow,
+this means that if you have an active pull request, make some changes
+locally for, say, an unrelated bugfix, then push those changes back to
+your fork in the hopes of creating a *new* pull request, you'll
+actually end up updating your current pull request!
+
+There are a few ways around this feature of BitBucket that will allow
+for multiple pull requests to coexist; we outline one such method
+below. We assume that you have a fork of yt at
+``http://bitbucket.org/YourUsername/Your_yt`` (see
+:ref:`sharing-changes` for instructions on creating a fork) and that
+you have an active pull request to the main repository.
+
+The main issue with starting another pull request is to make sure that
+your push to BitBucket doesn't go to the same head as your
+existing pull request and trigger BitBucket's auto-update feature.
+Here's how to get your local repository away from your current pull
+request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
+and your ``hgrc`` file:
+
+#. Set up a Mercurial path for the main yt repository (note this is a convenience
+ step and only needs to be done once). Add the following to your
+ ``Your_yt/.hg/hgrc``::
+
+ [paths]
+ upstream = https://bitbucket.org/yt_analysis/yt
+
+ This will create a path called ``upstream`` that is aliased to the URL of the
+ main yt repository.
+#. Now we'll use revsets_ to update your local repository to the tip of the
+ ``upstream`` path:
+
+ .. code-block:: bash
+
+ $ hg pull upstream
+ $ hg update -r "remote(yt, 'upstream')"
+
+After the above steps, your local repository should be at the current head of
+the ``yt`` branch in the main yt repository. If you find yourself doing this a
+lot, it may be worth aliasing this task in your ``hgrc`` file by adding
+something like::
+
+ [alias]
+ ytupdate = update -r "remote(yt, 'upstream')"
+
+And then you can just issue ``hg ytupdate`` to get at the current head of the
+``yt`` branch on main yt repository.
+
+Make sure you are on the branch you want to be on, and then you can make changes
+and ``hg commit`` them. If you prefer working with `bookmarks
+<http://mercurial-scm.org/wiki/Bookmarks>`_, you may want to make a bookmark
+before committing your changes, such as ``hg bookmark mybookmark``.
+
+To push your changes on a bookmark to bitbucket, you can issue the following
+command:
+
+.. code-block:: bash
+
+ $ hg push -B myfeature https://bitbucket.org/YourUsername/Your_yt
+
+The ``-B`` means "publish my bookmark, the changeset the bookmark is pointing
+at, and any ancestors of that changeset that aren't already on the remote
+server".
+
+To push to your fork on BitBucket if you didn't use a bookmark, you issue the
+following:
+
+.. code-block:: bash
+
+ $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
+
+The ``-r .`` means "push only the commit I'm standing on and any ancestors."
+The ``-f`` is to force Mecurial to do the push since we are creating a new
+remote head without a bookmark.
+
+You can then go to the BitBucket interface and issue a new pull request based on
+your last changes, as usual.
+
+.. _code-style-guide:
+
+Coding Style Guide
+==================
+
+Automatically checking code style
+---------------------------------
+
+Below are a list of rules for coding style in yt. Some of these rules are
+suggestions are not explicitly enforced, while some are enforced via automated
+testing. The yt project uses a subset of the rules checked by ``flake8`` to
+verify our code. The ``flake8`` tool is a combination of the ``pyflakes`` and
+``pep8`` tools. To check the coding style of your contributions locally you will
+need to install the ``flake8`` tool from ``pip``:
+
+ $ pip install flake8
+
+And then navigate to the root of the yt repository and run ``flake8`` on the
+``yt`` folder:
+
+ $ cd $YT_HG
+ $ flake8 ./yt
+
+This will print out any ``flake8`` errors or warnings that your newly added code
+triggers. The errors will be in your newly added code because we have already
+cleaned up the rest of the yt codebase of the errors and warnings detected by
+the `flake8` tool. Note that this will only trigger a subset of the `full flake8
+error and warning list
+<http://flake8.readthedocs.org/en/latest/warnings.html>`_, since we explicitly
+blacklist a large number of the full list of rules that are checked by
+``flake8`` by default.
+
+Source code style guide
+-----------------------
+
+ * In general, follow PEP-8 guidelines.
+ http://www.python.org/dev/peps/pep-0008/
+ * Classes are ``ConjoinedCapitals``, methods and functions are
+ ``lowercase_with_underscores``.
+ * Use 4 spaces, not tabs, to represent indentation.
+ * Line widths should not be more than 80 characters.
+ * Do not use nested classes unless you have a very good reason to, such as
+ requiring a namespace or class-definition modification. Classes should live
+ at the top level. ``__metaclass__`` is exempt from this.
+ * Do not use unnecessary parenthesis in conditionals. ``if((something) and
+ (something_else))`` should be rewritten as
+ ``if something and something_else``. Python is more forgiving than C.
+ * Avoid copying memory when possible. For example, don't do
+ ``a = a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3``
+ should be ``np.multiply(a, 3, a)``.
+ * In general, avoid all double-underscore method names: ``__something`` is
+ usually unnecessary.
+ * When writing a subclass, use the super built-in to access the super class,
+ rather than explicitly. Ex: ``super(SpecialGridSubclass, self).__init__()``
+ rather than ``SpecialGrid.__init__()``.
+ * Docstrings should describe input, output, behavior, and any state changes
+ that occur on an object. See the file ``doc/docstring_example.txt`` for a
+ fiducial example of a docstring.
+ * Use only one top-level import per line. Unless there is a good reason not to,
+ imports should happen at the top of the file, after the copyright blurb.
+ * Never compare with ``True`` or ``False`` using ``==`` or ``!=``, always use
+ ``is`` or ``is not``.
+ * If you are comparing with a numpy boolean array, just refer to the array.
+ Ex: do ``np.all(array)`` instead of ``np.all(array == True)``.
+ * Never comapre with None using ``==`` or ``!=``, use ``is None`` or
+ ``is not None``.
+ * Use ``statement is not True`` instead of ``not statement is True``
+ * Only one statement per line, do not use semicolons to put two or more
+ statements on a single line.
+ * Only declare local variables if they will be used later. If you do not use the
+ return value of a function, do not store it in a variable.
+ * Add tests for new functionality. When fixing a bug, consider adding a test to
+ prevent the bug from recurring.
+
+API Style Guide
+---------------
+
+ * Do not use ``from some_module import *``
+ * Internally, only import from source files directly -- instead of:
+
+ ``from yt.visualization.api import ProjectionPlot``
+
+ do:
+
+ ``from yt.visualization.plot_window import ProjectionPlot``
+
+ * Import symbols from the module where they are defined, avoid transitive
+ imports.
+ * Import standard library modules, functions, and classes from builtins, do not
+ import them from other yt files.
+ * Numpy is to be imported as ``np``.
+ * Do not use too many keyword arguments. If you have a lot of keyword
+ arguments, then you are doing too much in ``__init__`` and not enough via
+ parameter setting.
+ * In function arguments, place spaces before commas. ``def something(a,b,c)``
+ should be ``def something(a, b, c)``.
+ * Don't create a new class to replicate the functionality of an old class --
+ replace the old class. Too many options makes for a confusing user
+ experience.
+ * Parameter files external to yt are a last resort.
+ * The usage of the ``**kwargs`` construction should be avoided. If they cannot
+ be avoided, they must be explained, even if they are only to be passed on to
+ a nested function.
+
+.. _docstrings
+
+Docstrings
+----------
+
+The following is an example docstring. You can use it as a template for
+docstrings in your code and as a guide for how we expect docstrings to look and
+the level of detail we are looking for. Note that we use NumPy style docstrings
+written in `Sphinx restructured text format <http://sphinx-doc.org/rest.html>`_.
+
+ r"""A one-line summary that does not use variable names or the
+ function name.
+
+ Several sentences providing an extended description. Refer to
+ variables using back-ticks, e.g. ``var``.
+
+ Parameters
+ ----------
+ var1 : array_like
+ Array_like means all those objects -- lists, nested lists, etc. --
+ that can be converted to an array. We can also refer to
+ variables like `var1`.
+ var2 : int
+ The type above can either refer to an actual Python type
+ (e.g. ``int``), or describe the type of the variable in more
+ detail, e.g. ``(N,) ndarray`` or ``array_like``.
+ Long_variable_name : {'hi', 'ho'}, optional
+ Choices in brackets, default first when optional.
+
+ Returns
+ -------
+ describe : type
+ Explanation
+ output : type
+ Explanation
+ tuple : type
+ Explanation
+ items : type
+ even more explaining
+
+ Other Parameters
+ ----------------
+ only_seldom_used_keywords : type
+ Explanation
+ common_parameters_listed_above : type
+ Explanation
+
+ Raises
+ ------
+ BadException
+ Because you shouldn't have done that.
+
+ See Also
+ --------
+ otherfunc : relationship (optional)
+ newfunc : Relationship (optional), which could be fairly long, in which
+ case the line wraps here.
+ thirdfunc, fourthfunc, fifthfunc
+
+ Notes
+ -----
+ Notes about the implementation algorithm (if needed).
+
+ This can have multiple paragraphs.
+
+ You may include some math:
+
+ .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+ And even use a greek symbol like :math:`omega` inline.
+
+ References
+ ----------
+ Cite the relevant literature, e.g. [1]_. You may also cite these
+ references in the notes section above.
+
+ .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+ expert systems and adaptive co-kriging for environmental habitat
+ modelling of the Highland Haggis using object-oriented, fuzzy-logic
+ and neural-network techniques," Computers & Geosciences, vol. 22,
+ pp. 585-588, 1996.
+
+ Examples
+ --------
+ These are written in doctest format, and should illustrate how to
+ use the function. Use the variables 'ds' for the dataset, 'pc' for
+ a plot collection, 'c' for a center, and 'L' for a vector.
+
+ >>> a=[1,2,3]
+ >>> print [x + 3 for x in a]
+ [4, 5, 6]
+ >>> print "a\n\nb"
+ a
+ b
+
+ """
+
+Variable Names and Enzo-isms
+----------------------------
+Avoid Enzo-isms. This includes but is not limited to:
+
+ * Hard-coding parameter names that are the same as those in Enzo. The
+ following translation table should be of some help. Note that the
+ parameters are now properties on a ``Dataset`` subclass: you access them
+ like ds.refine_by .
+
+ - ``RefineBy `` => `` refine_by``
+ - ``TopGridRank `` => `` dimensionality``
+ - ``TopGridDimensions `` => `` domain_dimensions``
+ - ``InitialTime `` => `` current_time``
+ - ``DomainLeftEdge `` => `` domain_left_edge``
+ - ``DomainRightEdge `` => `` domain_right_edge``
+ - ``CurrentTimeIdentifier `` => `` unique_identifier``
+ - ``CosmologyCurrentRedshift `` => `` current_redshift``
+ - ``ComovingCoordinates `` => `` cosmological_simulation``
+ - ``CosmologyOmegaMatterNow `` => `` omega_matter``
+ - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
+ - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
+
+ * Do not assume that the domain runs from 0 .. 1. This is not true
+ everywhere.
+ * Variable names should be short but descriptive.
+ * No globals!
diff -r 46d68d42bf02fcd336aa5db0f9ea964b1099648a -r bf6e64cbf7006f9e20136bd440bad66372cf26b0 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -1,1 +1,1 @@
-.. include:: ../../../CONTRIBUTING
+.. include:: ../../../CONTRIBUTING.rst
https://bitbucket.org/yt_analysis/yt/commits/94b347d82a50/
Changeset: 94b347d82a50
Branch: yt
User: ngoldbaum
Date: 2015-11-23 19:44:58+00:00
Summary: Minor updates for formatting in CONTRIBUTING file
Affected #: 1 file
diff -r bf6e64cbf7006f9e20136bd440bad66372cf26b0 -r 94b347d82a50422c74a5d6a54fb105ce248d045d CONTRIBUTING.rst
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -750,11 +750,15 @@
``pep8`` tools. To check the coding style of your contributions locally you will
need to install the ``flake8`` tool from ``pip``:
+.. code-block:: bash
+
$ pip install flake8
And then navigate to the root of the yt repository and run ``flake8`` on the
``yt`` folder:
+.. code-block:: bash
+
$ cd $YT_HG
$ flake8 ./yt
@@ -849,6 +853,8 @@
the level of detail we are looking for. Note that we use NumPy style docstrings
written in `Sphinx restructured text format <http://sphinx-doc.org/rest.html>`_.
+.. code-block:: rest
+
r"""A one-line summary that does not use variable names or the
function name.
@@ -860,7 +866,7 @@
var1 : array_like
Array_like means all those objects -- lists, nested lists, etc. --
that can be converted to an array. We can also refer to
- variables like `var1`.
+ variables like ``var1``.
var2 : int
The type above can either refer to an actual Python type
(e.g. ``int``), or describe the type of the variable in more
https://bitbucket.org/yt_analysis/yt/commits/5b5389c150b9/
Changeset: 5b5389c150b9
Branch: yt
User: ngoldbaum
Date: 2015-11-23 19:46:00+00:00
Summary: Merged in ngoldbaum/yt (pull request #1878)
Developer guide updates
Affected #: 7 files
diff -r 057c8b0cf0634b0d010426b23f7275ab84d67fe9 -r 5b5389c150b9d9ae33a8e36b03f6626f78b8da53 CONTRIBUTING.rst
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,970 @@
+.. This document is rendered in HTML with cross-reference links filled in at
+ http://yt-project.org/doc/developing/
+
+.. _getting-involved:
+
+Getting Involved
+================
+
+There are *lots* of ways to get involved with yt, as a community and as a
+technical system -- not all of them just contributing code, but also
+participating in the community, helping us with designing the websites, adding
+documentation, and sharing your scripts with others.
+
+Coding is only one way to be involved!
+
+Communication Channels
+----------------------
+
+There are five main communication channels for yt:
+
+ * We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
+ You can connect through our web
+ gateway without any special client, at http://yt-project.org/irc.html .
+ *IRC is the first stop for conversation!*
+ * Many yt developers participate in the yt Slack community. Slack is a free
+ chat service that many teams use to organize their work. You can get an
+ invite to yt's Slack organization by clicking the "Join us @ Slack" button
+ on this page: http://yt-project.org/community.html
+ * `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
+ is a relatively high-traffic mailing list where people are encouraged to ask
+ questions about the code, figure things out and so on.
+ * `yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_ is
+ a much lower-traffic mailing list designed to focus on discussions of
+ improvements to the code, ideas about planning, development issues, and so
+ on.
+ * `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
+ the (now-inaccurately titled) mailing list where all pushes to the primary
+ repository are sent.
+
+The easiest way to get involved with yt is to read the mailing lists, hang out
+in IRC or slack chat, and participate. If someone asks a question you know the
+answer to (or have your own question about!) write back and answer it.
+
+If you have an idea about something, suggest it! We not only welcome
+participation, we encourage it.
+
+Documentation
+-------------
+
+The yt documentation is constantly being updated, and it is a task we would very
+much appreciate assistance with. Whether that is adding a section, updating an
+outdated section, contributing typo or grammatical fixes, adding a FAQ, or
+increasing coverage of functionality, it would be very helpful if you wanted to
+help out.
+
+The easiest way to help out is to fork the main yt repository (where the
+documentation lives in the ``doc`` directory in the root of the yt mercurial
+repository) and then make your changes in your own fork. When you are done,
+issue a pull request through the website for your new fork, and we can comment
+back and forth and eventually accept your changes. See :ref:`sharing-changes` for
+more information about contributing your changes to yt on bitbucket.
+
+Gallery Images and Videos
+-------------------------
+
+If you have an image or video you'd like to display in the image or video
+galleries, getting it included it easy! You can either fork the `yt homepage
+repository <http://bitbucket.org/yt_analysis/website>`_ and add it there, or
+email it to us and we'll add it to the `Gallery
+<http://yt-project.org/gallery.html>`_.
+
+We're eager to show off the images and movies you make with yt, so please feel
+free to drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
+a line and let us know if you've got something great!
+
+Technical Contributions
+-----------------------
+
+Contributing code is another excellent way to participate -- whether it's
+bug fixes, new features, analysis modules, or a new code frontend. See
+:ref:`creating_frontend` for more details.
+
+The process is pretty simple: fork on BitBucket, make changes, issue a pull
+request. We can then go back and forth with comments in the pull request, but
+usually we end up accepting.
+
+For more information, see :ref:`contributing-code`, where we spell out how to
+get up and running with a development environment, how to commit, and how to
+use BitBucket.
+
+Online Presence
+---------------
+
+Some of these fall under the other items, but if you'd like to help out with
+the website or any of the other ways yt is presented online, please feel free!
+Almost everything is kept in hg repositories on BitBucket, and it is very easy
+to fork and contribute back changes.
+
+Please feel free to dig in and contribute changes.
+
+Word of Mouth
+-------------
+
+If you're using yt and it has increased your productivity, please feel
+encouraged to share that information. Cite our `paper
+<http://adsabs.harvard.edu/abs/2011ApJS..192....9T>`_, tell your colleagues,
+and just spread word of mouth. By telling people about your successes, you'll
+help bring more eyes and hands to the table -- in this manner, by increasing
+participation, collaboration, and simply spreading the limits of what the code
+is asked to do, we hope to help scale the utility and capability of yt with the
+community size.
+
+Feel free to `blog <http://blog.yt-project.org/>`_ about, `tweet
+<http://twitter.com/yt_astro>`_ about and talk about what you are up to!
+
+Long-Term Projects
+------------------
+
+There are some wild-eyed, out-there ideas that have been bandied about for the
+future directions of yt -- some of them even written into the mission
+statement. The ultimate goal is to move past simple analysis and visualization
+of data and begin to approach it from the other side, of generating data,
+running solvers. We also hope to increase its ability to act as an in situ
+analysis code, by presenting a unified protocol. Other projects include
+interfacing with ParaView and VisIt, creating a web GUI for running
+simulations, creating a run-tracker that follows simulations in progress, a
+federated database for simulation outputs, and so on and so forth.
+
+yt is an ambitious project. Let's be ambitious together.
+
+yt Community Code of Conduct
+----------------------------
+
+The community of participants in open source
+Scientific projects is made up of members from around the
+globe with a diverse set of skills, personalities, and
+experiences. It is through these differences that our
+community experiences success and continued growth. We
+expect everyone in our community to follow these guidelines
+when interacting with others both inside and outside of our
+community. Our goal is to keep ours a positive, inclusive,
+successful, and growing community.
+
+As members of the community,
+
+- We pledge to treat all people with respect and
+ provide a harassment- and bullying-free environment,
+ regardless of sex, sexual orientation and/or gender
+ identity, disability, physical appearance, body size,
+ race, nationality, ethnicity, and religion. In
+ particular, sexual language and imagery, sexist,
+ racist, or otherwise exclusionary jokes are not
+ appropriate.
+
+- We pledge to respect the work of others by
+ recognizing acknowledgment/citation requests of
+ original authors. As authors, we pledge to be explicit
+ about how we want our own work to be cited or
+ acknowledged.
+
+- We pledge to welcome those interested in joining the
+ community, and realize that including people with a
+ variety of opinions and backgrounds will only serve to
+ enrich our community. In particular, discussions
+ relating to pros/cons of various technologies,
+ programming languages, and so on are welcome, but
+ these should be done with respect, taking proactive
+ measure to ensure that all participants are heard and
+ feel confident that they can freely express their
+ opinions.
+
+- We pledge to welcome questions and answer them
+ respectfully, paying particular attention to those new
+ to the community. We pledge to provide respectful
+ criticisms and feedback in forums, especially in
+ discussion threads resulting from code
+ contributions.
+
+- We pledge to be conscientious of the perceptions of
+ the wider community and to respond to criticism
+ respectfully. We will strive to model behaviors that
+ encourage productive debate and disagreement, both
+ within our community and where we are criticized. We
+ will treat those outside our community with the same
+ respect as people within our community.
+
+- We pledge to help the entire community follow the
+ code of conduct, and to not remain silent when we see
+ violations of the code of conduct. We will take action
+ when members of our community violate this code such as
+ contacting confidential at yt-project.org (all emails sent to
+ this address will be treated with the strictest
+ confidence) or talking privately with the person.
+
+This code of conduct applies to all
+community situations online and offline, including mailing
+lists, forums, social media, conferences, meetings,
+associated social events, and one-to-one interactions.
+
+The yt Community Code of Conduct was adapted from the
+`Astropy Community Code of Conduct
+<http://www.astropy.org/about.html#codeofconduct>`_,
+which was partially inspired by the PSF code of conduct.
+
+.. _contributing-code:
+
+How to Develop yt
+=================
+
+yt is a community project!
+
+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.
+
+.. note:: If you already know how to use the `mercurial version control system
+ <http://mercurial-scm.org>`_ and are comfortable with handling it yourself,
+ the quickest way to contribute to yt is to `fork us on BitBucket
+ <http://bitbucket.org/yt_analysis/yt/fork>`_, make your changes, push the
+ changes to your fork and issue a `pull request
+ <http://bitbucket.org/yt_analysis/yt/pull-requests>`_. The rest of this
+ document is just an explanation of how to do that.
+
+See :ref:`code-style-guide` for more information about coding style in yt and
+:ref:`docstrings` for an example docstring. Please read them before hacking on
+the codebase, and feel free to email any of the mailing lists for help with the
+codebase.
+
+Keep in touch, and happy hacking!
+
+.. _open-issues:
+
+Open Issues
+-----------
+
+If you're interested in participating in yt development, take a look at the
+`issue tracker on bitbucket
+<https://bitbucket.org/yt_analysis/yt/issues?milestone=easy?status=new>`_.
+Issues are marked with a milestone of "easy", "moderate", or "difficult"
+depending on the estimated level of difficulty for fixing the issue. While we
+try to triage the issue tracker regularly, it may be the case that issues marked
+"moderate" are actually easier than their milestone label indicates since that
+is the default value.
+
+Here are some predefined issue searches that might be useful:
+
+* Unresolved issues `marked "easy" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&status=open&status=new>`_.
+* Unresolved issues `marked "easy" or "moderate" <https://bitbucket.org/yt_analysis/yt/issues?milestone=easy&milestone=moderate&status=open&status=new>`_
+* `All unresolved issues <https://bitbucket.org/yt_analysis/yt/issues?status=open&status=new>`_
+
+Submitting Changes
+------------------
+
+We provide a brief introduction to submitting changes here. yt thrives on the
+strength of its communities (http://arxiv.org/abs/1301.7064 has further
+discussion) and we encourage contributions from any user. While we do not
+discuss version control, mercurial or the advanced usage of BitBucket in detail
+here, we do provide an outline of how to submit changes and we are happy to
+provide further assistance or guidance.
+
+Licensing
++++++++++
+
+yt is `licensed <http://blog.yt-project.org/post/Relicensing.html>`_ under the
+BSD 3-clause license. Versions previous to yt-2.6 were released under the GPLv3.
+
+All contributed code must be BSD-compatible. If you'd rather not license in
+this manner, but still want to contribute, please consider creating an external
+package, which we'll happily link to.
+
+How To Get The Source Code For Editing
+++++++++++++++++++++++++++++++++++++++
+
+yt is hosted on BitBucket, and you can see all of the yt repositories at
+http://bitbucket.org/yt_analysis/. With the yt installation script you should have a
+copy of Mercurial for checking out pieces of code. Make sure you have followed
+the steps above for bootstrapping your development (to assure you have a
+bitbucket account, etc.)
+
+In order to modify the source code for yt, we ask that you make a "fork" of the
+main yt repository on bitbucket. A fork is simply an exact copy of the main
+repository (along with its history) that you will now own and can make
+modifications as you please. You can create a personal fork by visiting the yt
+bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in,
+you should see an option near the top right labeled "fork". Click this option,
+and then click the fork repository button on the subsequent page. You now have
+a forked copy of the yt repository for your own personal modification.
+
+This forked copy exists on the bitbucket repository, so in order to access
+it locally, follow the instructions at the top of that webpage for that
+forked repository, namely run at a local command line:
+
+.. code-block:: bash
+
+ $ hg clone http://bitbucket.org/<USER>/<REPOSITORY_NAME>
+
+This downloads that new forked repository to your local machine, so that you
+can access it, read it, make modifications, etc. It will put the repository in
+a local directory of the same name as the repository in the current working
+directory. You can see any past state of the code by using the hg log command.
+For example, the following command would show you the last 5 changesets
+(modifications to the code) that were submitted to that repository.
+
+.. code-block:: bash
+
+ $ cd <REPOSITORY_NAME>
+ $ hg log -l 5
+
+Using the revision specifier (the number or hash identifier next to each
+changeset), you can update the local repository to any past state of the
+code (a previous changeset or version) by executing the command:
+
+.. code-block:: bash
+
+ $ hg up revision_specifier
+
+Lastly, if you want to use this new downloaded version of your yt repository as
+the *active* version of yt on your computer (i.e. the one which is executed when
+you run yt from the command line or the one that is loaded when you do ``import
+yt``), then you must "activate" it using the following commands from within the
+repository directory.
+
+.. code-block:: bash
+
+ $ cd <REPOSITORY_NAME>
+ $ python2.7 setup.py develop
+
+This will rebuild all C modules as well.
+
+.. _reading-source:
+
+How To Read The Source Code
++++++++++++++++++++++++++++
+
+If you just want to *look* at the source code, you may already have it on your
+computer. If you build yt using the install script, the source is available at
+``$YT_DEST/src/yt-hg``. See :ref:`source-installation` for more details about
+to obtain the yt source code if you did not build yt using the install
+script.
+
+The root directory of the yt mercurial repository contains a number of
+subdirectories with different components of the code. Most of the yt source
+code is contained in the yt subdirectory. This directory its self contains
+the following subdirectories:
+
+``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, Dataset
+ and AMRHierarchy are defined.
+ * ``io.py``, where a subclass of IOHandler is defined.
+ * ``fields.py``, where fields we expect to find in datasets are 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.)
+
+``fields``
+ This is where all of the derived fields that ship with yt are defined.
+
+``geometry``
+ This is where geometric helpler routines are defined. Handlers
+ for grid and oct data, as well as helpers for coordinate transformations
+ can be found here.
+
+``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.
+
+``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.
+
+``extern``
+ Bundled external modules (i.e. code that was not written by one of
+ the yt authors but that yt depends on) lives here.
+
+
+If you're looking for a specific file or function in the yt source code, use
+the unix find command:
+
+.. code-block:: bash
+
+ $ find <DIRECTORY_TREE_TO_SEARCH> -name '<FILENAME>'
+
+The above command will find the FILENAME in any subdirectory in the
+DIRECTORY_TREE_TO_SEARCH. Alternatively, if you're looking for a function
+call or a keyword in an unknown file in a directory tree, try:
+
+.. code-block:: bash
+
+ $ grep -R <KEYWORD_TO_FIND><DIRECTORY_TREE_TO_SEARCH>
+
+This can be very useful for tracking down functions in the yt source.
+
+.. _building-yt:
+
+Building yt
++++++++++++
+
+If you have made changes to any C or Cython (``.pyx``) modules, you have to
+rebuild yt. If your changes have exclusively been to Python modules, you will
+not need to re-build, but (see below) you may need to re-install.
+
+If you are running from a clone that is executable in-place (i.e., has been
+installed via the installation script or you have run ``setup.py develop``) you
+can rebuild these modules by executing:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py develop
+
+If you have previously "installed" via ``setup.py install`` you have to
+re-install:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py install
+
+Only one of these two options is needed.
+
+.. _windows-developing:
+
+Developing yt on Windows
+------------------------
+
+If you plan to develop yt on Windows, it is necessary to use the `MinGW
+<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
+Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
+installed from Anaconda as well. These can both be installed with a single command:
+
+.. code-block:: bash
+
+ $ conda install libpython mingw
+
+Additionally, the syntax for the setup command is slightly different; you must type:
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 develop
+
+or
+
+.. code-block:: bash
+
+ $ python2.7 setup.py build --compiler=mingw32 install
+
+.. _requirements-for-code-submission:
+
+Requirements for Code Submission
+--------------------------------
+
+Modifications to the code typically fall into one of three categories, each of
+which have different requirements for acceptance into the code base. These
+requirements are in place for a few reasons -- to make sure that the code is
+maintainable, testable, and that we can easily include information about
+changes in changelogs during the release procedure. (See `YTEP-0008
+<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
+detail.)
+
+* New Features
+
+ * New unit tests (possibly new answer tests) (See :ref:`testing`)
+ * Docstrings in the source code for the public API
+ * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
+ * Addition of cookbook recipe (See :ref:`writing_documentation`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Extension or Breakage of API in Existing Features
+
+ * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
+ * Update existing cookbook recipes (See :ref:`writing_documentation`)
+ * Modify of create new unit tests (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+* Bug fixes
+
+ * Unit test is encouraged, to ensure breakage does not happen again in the
+ future. (See :ref:`testing`)
+ * Issue created on issue tracker, to ensure this is added to the changelog
+
+When submitting, you will be asked to make sure that your changes meet all of
+these requirements. They are pretty easy to meet, and we're also happy to help
+out with them. In :ref:`code-style-guide` there is a list of handy tips for
+how to structure and write your code.
+
+.. _mercurial-with-yt:
+
+How to Use Mercurial with yt
+----------------------------
+
+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-scm.org/
+* http://mercurial-scm.org/wiki
+
+The commands that are essential for using mercurial include:
+
+* ``hg help`` which provides help for any mercurial command. For example, you
+ can learn more about the ``log`` command by doing ``hg help log``. Other useful
+ topics to use with ``hg help`` are ``hg help glossary``, ``hg help config``,
+ ``hg help extensions``, and ``hg help revsets``.
+* ``hg commit`` which commits changes in the working directory to the
+ repository, creating a new "changeset object."
+* ``hg add`` which adds a new file to be tracked by mercurial. This does
+ not change the working directory.
+* ``hg pull`` which pulls (from an optional path specifier) changeset
+ objects from a remote source. The working directory is not modified.
+* ``hg push`` which sends (to an optional path specifier) changeset objects
+ to a remote source. The working directory is not modified.
+* ``hg log`` which shows a log of all changeset objects in the current
+ repository. Use ``-G`` to show a graph of changeset objects and their
+ relationship.
+* ``hg update`` which (with an optional "revision" specifier) updates the
+ state of the working directory to match a changeset object in the
+ repository.
+* ``hg merge`` which combines two changesets to make a union of their lines
+ of development. This updates the working directory.
+
+We are happy to asnswers questions about mercurial use on our IRC, slack
+chat or on the mailing list to walk you through any troubles you might have.
+Here are some general suggestions for using mercurial with yt:
+
+* Named branches are to be avoided. Try using bookmarks (``see hg help
+ bookmark``) to track work. (`More info about bookmarks is available on the
+ mercurial wiki <http://mercurial-scm.org/wiki/Bookmarks>`_)
+* Make sure you set a username in your ``~/.hgrc`` before you commit any
+ changes! All of the tutorials above will describe how to do this as one of
+ the very first steps.
+* When contributing changes, you might be asked to make a handful of
+ modifications to your source code. We'll work through how to do this with
+ you, and try to make it as painless as possible.
+* Your test may fail automated style checks. See :ref:`code-style-guide` for
+ more information about automatically verifying your code style.
+* Please avoid deleting your yt forks, as that deletes the pull request
+ discussion from process from BitBucket's website, even if your pull request
+ is merged.
+* You should only need one fork. To keep it in sync, you can sync from the
+ website. See Bitbucket's `Blog Post
+ <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
+ about this. See :ref:`sharing-changes` for a description of the basic workflow
+ and :ref:`multiple-PRs` for a discussion about what to do when you want to
+ have multiple open pull requests at the same time.
+* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
+ list.
+
+.. _sharing-changes:
+
+Making and Sharing Changes
+--------------------------
+
+The simplest way to submit changes to yt is to do the following:
+
+* Build yt from the mercurial repository
+* Navigate to the root of the yt repository
+* Make some changes and commit them
+* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
+* Push the changesets to your fork
+* Issue a pull request.
+
+Here's a more detailed flowchart of how to submit changes.
+
+#. If you have used the installation script, the source code for yt can be
+ found in ``$YT_DEST/src/yt-hg``. Alternatively see
+ :ref:`source-installation` for instructions on how to build yt from the
+ mercurial repository. (Below, in :ref:`reading-source`, we describe how to
+ find items of interest.)
+#. Edit the source file you are interested in and
+ test your changes. (See :ref:`testing` for more information.)
+#. Fork yt on BitBucket. (This step only has to be done once.) You can do
+ this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
+ yt.
+#. Create a bookmark to track your work. For example: ``hg bookmark
+ my-first-pull-request``
+#. Commit these changes, using ``hg commit``. This can take an argument
+ which is a series of filenames, if you have some changes you do not want
+ to commit.
+#. Remember that this is a large development effort and to keep the code
+ accessible to everyone, good documentation is a must. Add in source code
+ comments for what you are doing. Add in docstrings
+ if you are adding a new function or class or keyword to a function.
+ Add documentation to the appropriate section of the online docs so that
+ people other than yourself know how to use your new code.
+#. If your changes include new functionality or cover an untested area of the
+ code, add a test. (See :ref:`testing` for more information.) Commit
+ these changes as well.
+#. Push your changes to your new fork using the command::
+
+ hg push -B my-first-pull-request https://bitbucket.org/YourUsername/yt/
+
+ Where you should substitute the name of the bookmark you are working on for
+ ``my-first-pull-request``. If you end up doing considerable development, you
+ can set an alias in the file ``.hg/hgrc`` to point to this path.
+
+ .. note::
+ Note that the above approach uses HTTPS as the transfer protocol
+ between your machine and BitBucket. If you prefer to use SSH - or
+ perhaps you're behind a proxy that doesn't play well with SSL via
+ HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
+ the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
+ place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
+ For consistency, all commands we list in this document will use the HTTPS
+ protocol.
+
+ .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
+
+#. Issue a pull request at
+ https://bitbucket.org/YourUsername/yt/pull-request/new
+ A pull request is essentially just asking people to review and accept the
+ modifications you have made to your personal version of the code.
+
+
+During the course of your pull request you may be asked to make changes. These
+changes may be related to style issues, correctness issues, or even requesting
+tests. The process for responding to pull request code review is relatively
+straightforward.
+
+#. Make requested changes, or leave a comment indicating why you don't think
+ they should be made.
+#. Commit those changes to your local repository.
+#. Push the changes to your fork:
+
+ hg push https://bitbucket.org/YourUsername/yt/
+
+#. Your pull request will be automatically updated.
+
+.. _multiple-PRs:
+
+Working with Multiple BitBucket Pull Requests
++++++++++++++++++++++++++++++++++++++++++++++
+
+Once you become active developing for yt, you may be working on
+various aspects of the code or bugfixes at the same time. Currently,
+BitBucket's *modus operandi* for pull requests automatically updates
+your active pull request with every ``hg push`` of commits that are a
+descendant of the head of your pull request. In a normal workflow,
+this means that if you have an active pull request, make some changes
+locally for, say, an unrelated bugfix, then push those changes back to
+your fork in the hopes of creating a *new* pull request, you'll
+actually end up updating your current pull request!
+
+There are a few ways around this feature of BitBucket that will allow
+for multiple pull requests to coexist; we outline one such method
+below. We assume that you have a fork of yt at
+``http://bitbucket.org/YourUsername/Your_yt`` (see
+:ref:`sharing-changes` for instructions on creating a fork) and that
+you have an active pull request to the main repository.
+
+The main issue with starting another pull request is to make sure that
+your push to BitBucket doesn't go to the same head as your
+existing pull request and trigger BitBucket's auto-update feature.
+Here's how to get your local repository away from your current pull
+request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
+and your ``hgrc`` file:
+
+#. Set up a Mercurial path for the main yt repository (note this is a convenience
+ step and only needs to be done once). Add the following to your
+ ``Your_yt/.hg/hgrc``::
+
+ [paths]
+ upstream = https://bitbucket.org/yt_analysis/yt
+
+ This will create a path called ``upstream`` that is aliased to the URL of the
+ main yt repository.
+#. Now we'll use revsets_ to update your local repository to the tip of the
+ ``upstream`` path:
+
+ .. code-block:: bash
+
+ $ hg pull upstream
+ $ hg update -r "remote(yt, 'upstream')"
+
+After the above steps, your local repository should be at the current head of
+the ``yt`` branch in the main yt repository. If you find yourself doing this a
+lot, it may be worth aliasing this task in your ``hgrc`` file by adding
+something like::
+
+ [alias]
+ ytupdate = update -r "remote(yt, 'upstream')"
+
+And then you can just issue ``hg ytupdate`` to get at the current head of the
+``yt`` branch on main yt repository.
+
+Make sure you are on the branch you want to be on, and then you can make changes
+and ``hg commit`` them. If you prefer working with `bookmarks
+<http://mercurial-scm.org/wiki/Bookmarks>`_, you may want to make a bookmark
+before committing your changes, such as ``hg bookmark mybookmark``.
+
+To push your changes on a bookmark to bitbucket, you can issue the following
+command:
+
+.. code-block:: bash
+
+ $ hg push -B myfeature https://bitbucket.org/YourUsername/Your_yt
+
+The ``-B`` means "publish my bookmark, the changeset the bookmark is pointing
+at, and any ancestors of that changeset that aren't already on the remote
+server".
+
+To push to your fork on BitBucket if you didn't use a bookmark, you issue the
+following:
+
+.. code-block:: bash
+
+ $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
+
+The ``-r .`` means "push only the commit I'm standing on and any ancestors."
+The ``-f`` is to force Mecurial to do the push since we are creating a new
+remote head without a bookmark.
+
+You can then go to the BitBucket interface and issue a new pull request based on
+your last changes, as usual.
+
+.. _code-style-guide:
+
+Coding Style Guide
+==================
+
+Automatically checking code style
+---------------------------------
+
+Below are a list of rules for coding style in yt. Some of these rules are
+suggestions are not explicitly enforced, while some are enforced via automated
+testing. The yt project uses a subset of the rules checked by ``flake8`` to
+verify our code. The ``flake8`` tool is a combination of the ``pyflakes`` and
+``pep8`` tools. To check the coding style of your contributions locally you will
+need to install the ``flake8`` tool from ``pip``:
+
+.. code-block:: bash
+
+ $ pip install flake8
+
+And then navigate to the root of the yt repository and run ``flake8`` on the
+``yt`` folder:
+
+.. code-block:: bash
+
+ $ cd $YT_HG
+ $ flake8 ./yt
+
+This will print out any ``flake8`` errors or warnings that your newly added code
+triggers. The errors will be in your newly added code because we have already
+cleaned up the rest of the yt codebase of the errors and warnings detected by
+the `flake8` tool. Note that this will only trigger a subset of the `full flake8
+error and warning list
+<http://flake8.readthedocs.org/en/latest/warnings.html>`_, since we explicitly
+blacklist a large number of the full list of rules that are checked by
+``flake8`` by default.
+
+Source code style guide
+-----------------------
+
+ * In general, follow PEP-8 guidelines.
+ http://www.python.org/dev/peps/pep-0008/
+ * Classes are ``ConjoinedCapitals``, methods and functions are
+ ``lowercase_with_underscores``.
+ * Use 4 spaces, not tabs, to represent indentation.
+ * Line widths should not be more than 80 characters.
+ * Do not use nested classes unless you have a very good reason to, such as
+ requiring a namespace or class-definition modification. Classes should live
+ at the top level. ``__metaclass__`` is exempt from this.
+ * Do not use unnecessary parenthesis in conditionals. ``if((something) and
+ (something_else))`` should be rewritten as
+ ``if something and something_else``. Python is more forgiving than C.
+ * Avoid copying memory when possible. For example, don't do
+ ``a = a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3``
+ should be ``np.multiply(a, 3, a)``.
+ * In general, avoid all double-underscore method names: ``__something`` is
+ usually unnecessary.
+ * When writing a subclass, use the super built-in to access the super class,
+ rather than explicitly. Ex: ``super(SpecialGridSubclass, self).__init__()``
+ rather than ``SpecialGrid.__init__()``.
+ * Docstrings should describe input, output, behavior, and any state changes
+ that occur on an object. See the file ``doc/docstring_example.txt`` for a
+ fiducial example of a docstring.
+ * Use only one top-level import per line. Unless there is a good reason not to,
+ imports should happen at the top of the file, after the copyright blurb.
+ * Never compare with ``True`` or ``False`` using ``==`` or ``!=``, always use
+ ``is`` or ``is not``.
+ * If you are comparing with a numpy boolean array, just refer to the array.
+ Ex: do ``np.all(array)`` instead of ``np.all(array == True)``.
+ * Never comapre with None using ``==`` or ``!=``, use ``is None`` or
+ ``is not None``.
+ * Use ``statement is not True`` instead of ``not statement is True``
+ * Only one statement per line, do not use semicolons to put two or more
+ statements on a single line.
+ * Only declare local variables if they will be used later. If you do not use the
+ return value of a function, do not store it in a variable.
+ * Add tests for new functionality. When fixing a bug, consider adding a test to
+ prevent the bug from recurring.
+
+API Style Guide
+---------------
+
+ * Do not use ``from some_module import *``
+ * Internally, only import from source files directly -- instead of:
+
+ ``from yt.visualization.api import ProjectionPlot``
+
+ do:
+
+ ``from yt.visualization.plot_window import ProjectionPlot``
+
+ * Import symbols from the module where they are defined, avoid transitive
+ imports.
+ * Import standard library modules, functions, and classes from builtins, do not
+ import them from other yt files.
+ * Numpy is to be imported as ``np``.
+ * Do not use too many keyword arguments. If you have a lot of keyword
+ arguments, then you are doing too much in ``__init__`` and not enough via
+ parameter setting.
+ * In function arguments, place spaces before commas. ``def something(a,b,c)``
+ should be ``def something(a, b, c)``.
+ * Don't create a new class to replicate the functionality of an old class --
+ replace the old class. Too many options makes for a confusing user
+ experience.
+ * Parameter files external to yt are a last resort.
+ * The usage of the ``**kwargs`` construction should be avoided. If they cannot
+ be avoided, they must be explained, even if they are only to be passed on to
+ a nested function.
+
+.. _docstrings
+
+Docstrings
+----------
+
+The following is an example docstring. You can use it as a template for
+docstrings in your code and as a guide for how we expect docstrings to look and
+the level of detail we are looking for. Note that we use NumPy style docstrings
+written in `Sphinx restructured text format <http://sphinx-doc.org/rest.html>`_.
+
+.. code-block:: rest
+
+ r"""A one-line summary that does not use variable names or the
+ function name.
+
+ Several sentences providing an extended description. Refer to
+ variables using back-ticks, e.g. ``var``.
+
+ Parameters
+ ----------
+ var1 : array_like
+ Array_like means all those objects -- lists, nested lists, etc. --
+ that can be converted to an array. We can also refer to
+ variables like ``var1``.
+ var2 : int
+ The type above can either refer to an actual Python type
+ (e.g. ``int``), or describe the type of the variable in more
+ detail, e.g. ``(N,) ndarray`` or ``array_like``.
+ Long_variable_name : {'hi', 'ho'}, optional
+ Choices in brackets, default first when optional.
+
+ Returns
+ -------
+ describe : type
+ Explanation
+ output : type
+ Explanation
+ tuple : type
+ Explanation
+ items : type
+ even more explaining
+
+ Other Parameters
+ ----------------
+ only_seldom_used_keywords : type
+ Explanation
+ common_parameters_listed_above : type
+ Explanation
+
+ Raises
+ ------
+ BadException
+ Because you shouldn't have done that.
+
+ See Also
+ --------
+ otherfunc : relationship (optional)
+ newfunc : Relationship (optional), which could be fairly long, in which
+ case the line wraps here.
+ thirdfunc, fourthfunc, fifthfunc
+
+ Notes
+ -----
+ Notes about the implementation algorithm (if needed).
+
+ This can have multiple paragraphs.
+
+ You may include some math:
+
+ .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+ And even use a greek symbol like :math:`omega` inline.
+
+ References
+ ----------
+ Cite the relevant literature, e.g. [1]_. You may also cite these
+ references in the notes section above.
+
+ .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+ expert systems and adaptive co-kriging for environmental habitat
+ modelling of the Highland Haggis using object-oriented, fuzzy-logic
+ and neural-network techniques," Computers & Geosciences, vol. 22,
+ pp. 585-588, 1996.
+
+ Examples
+ --------
+ These are written in doctest format, and should illustrate how to
+ use the function. Use the variables 'ds' for the dataset, 'pc' for
+ a plot collection, 'c' for a center, and 'L' for a vector.
+
+ >>> a=[1,2,3]
+ >>> print [x + 3 for x in a]
+ [4, 5, 6]
+ >>> print "a\n\nb"
+ a
+ b
+
+ """
+
+Variable Names and Enzo-isms
+----------------------------
+Avoid Enzo-isms. This includes but is not limited to:
+
+ * Hard-coding parameter names that are the same as those in Enzo. The
+ following translation table should be of some help. Note that the
+ parameters are now properties on a ``Dataset`` subclass: you access them
+ like ds.refine_by .
+
+ - ``RefineBy `` => `` refine_by``
+ - ``TopGridRank `` => `` dimensionality``
+ - ``TopGridDimensions `` => `` domain_dimensions``
+ - ``InitialTime `` => `` current_time``
+ - ``DomainLeftEdge `` => `` domain_left_edge``
+ - ``DomainRightEdge `` => `` domain_right_edge``
+ - ``CurrentTimeIdentifier `` => `` unique_identifier``
+ - ``CosmologyCurrentRedshift `` => `` current_redshift``
+ - ``ComovingCoordinates `` => `` cosmological_simulation``
+ - ``CosmologyOmegaMatterNow `` => `` omega_matter``
+ - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
+ - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
+
+ * Do not assume that the domain runs from 0 .. 1. This is not true
+ everywhere.
+ * Variable names should be short but descriptive.
+ * No globals!
diff -r 057c8b0cf0634b0d010426b23f7275ab84d67fe9 -r 5b5389c150b9d9ae33a8e36b03f6626f78b8da53 coding_styleguide.txt
--- a/coding_styleguide.txt
+++ /dev/null
@@ -1,101 +0,0 @@
-Style Guide for Coding in yt
-============================
-
-Coding Style Guide
-------------------
-
- * In general, follow PEP-8 guidelines.
- http://www.python.org/dev/peps/pep-0008/
- * Classes are ``ConjoinedCapitals``, methods and functions are
- ``lowercase_with_underscores``.
- * Use 4 spaces, not tabs, to represent indentation.
- * Line widths should not be more than 80 characters.
- * Do not use nested classes unless you have a very good reason to, such as
- requiring a namespace or class-definition modification. Classes should live
- at the top level. ``__metaclass__`` is exempt from this.
- * Do not use unnecessary parenthesis in conditionals. ``if((something) and
- (something_else))`` should be rewritten as
- ``if something and something_else``. Python is more forgiving than C.
- * Avoid copying memory when possible. For example, don't do
- ``a = a.reshape(3,4)`` when ``a.shape = (3,4)`` will do, and ``a = a * 3``
- should be ``np.multiply(a, 3, a)``.
- * In general, avoid all double-underscore method names: ``__something`` is
- usually unnecessary.
- * When writing a subclass, use the super built-in to access the super class,
- rather than explicitly. Ex: ``super(SpecialGridSubclass, self).__init__()``
- rather than ``SpecialGrid.__init__()``.
- * Docstrings should describe input, output, behavior, and any state changes
- that occur on an object. See the file ``doc/docstring_example.txt`` for a
- fiducial example of a docstring.
- * Use only one top-level import per line. Unless there is a good reason not to,
- imports should happen at the top of the file, after the copyright blurb.
- * Never compare with ``True`` or ``False`` using ``==`` or ``!=``, always use
- ``is`` or ``is not``.
- * If you are comparing with a numpy boolean array, just refer to the array.
- Ex: do ``np.all(array)`` instead of ``np.all(array == True)``.
- * Never comapre with None using ``==`` or ``!=``, use ``is None`` or
- ``is not None``.
- * Use ``statement is not True`` instead of ``not statement is True``
- * Only one statement per line, do not use semicolons to put two or more
- statements on a single line.
- * Only declare local variables if they will be used later. If you do not use the
- return value of a function, do not store it in a variable.
- * Add tests for new functionality. When fixing a bug, consider adding a test to
- prevent the bug from recurring.
-
-API Guide
----------
-
- * Do not use ``from some_module import *``
- * Internally, only import from source files directly -- instead of:
-
- ``from yt.visualization.api import ProjectionPlot``
-
- do:
-
- ``from yt.visualization.plot_window import ProjectionPlot``
-
- * Import symbols from the module where they are defined, avoid transitive
- imports.
- * Import standard library modules, functions, and classes from builtins, do not
- import them from other yt files.
- * Numpy is to be imported as ``np``.
- * Do not use too many keyword arguments. If you have a lot of keyword
- arguments, then you are doing too much in ``__init__`` and not enough via
- parameter setting.
- * In function arguments, place spaces before commas. ``def something(a,b,c)``
- should be ``def something(a, b, c)``.
- * Don't create a new class to replicate the functionality of an old class --
- replace the old class. Too many options makes for a confusing user
- experience.
- * Parameter files external to yt are a last resort.
- * The usage of the ``**kwargs`` construction should be avoided. If they cannot
- be avoided, they must be explained, even if they are only to be passed on to
- a nested function.
-
-Variable Names and Enzo-isms
-----------------------------
-Avoid Enzo-isms. This includes but is not limited to:
-
- * Hard-coding parameter names that are the same as those in Enzo. The
- following translation table should be of some help. Note that the
- parameters are now properties on a ``Dataset`` subclass: you access them
- like ds.refine_by .
-
- - ``RefineBy `` => `` refine_by``
- - ``TopGridRank `` => `` dimensionality``
- - ``TopGridDimensions `` => `` domain_dimensions``
- - ``InitialTime `` => `` current_time``
- - ``DomainLeftEdge `` => `` domain_left_edge``
- - ``DomainRightEdge `` => `` domain_right_edge``
- - ``CurrentTimeIdentifier `` => `` unique_identifier``
- - ``CosmologyCurrentRedshift `` => `` current_redshift``
- - ``ComovingCoordinates `` => `` cosmological_simulation``
- - ``CosmologyOmegaMatterNow `` => `` omega_matter``
- - ``CosmologyOmegaLambdaNow `` => `` omega_lambda``
- - ``CosmologyHubbleConstantNow `` => `` hubble_constant``
-
- * Do not assume that the domain runs from 0 .. 1. This is not true
- everywhere.
- * Variable names should be short but descriptive.
- * No globals!
diff -r 057c8b0cf0634b0d010426b23f7275ab84d67fe9 -r 5b5389c150b9d9ae33a8e36b03f6626f78b8da53 doc/docstring_example.txt
--- a/doc/docstring_example.txt
+++ b/doc/docstring_example.txt
@@ -1,86 +0,0 @@
- r"""A one-line summary that does not use variable names or the
- function name.
-
- Several sentences providing an extended description. Refer to
- variables using back-ticks, e.g. `var`.
-
- Parameters
- ----------
- var1 : array_like
- Array_like means all those objects -- lists, nested lists, etc. --
- that can be converted to an array. We can also refer to
- variables like `var1`.
- var2 : int
- The type above can either refer to an actual Python type
- (e.g. ``int``), or describe the type of the variable in more
- detail, e.g. ``(N,) ndarray`` or ``array_like``.
- Long_variable_name : {'hi', 'ho'}, optional
- Choices in brackets, default first when optional.
-
- Returns
- -------
- describe : type
- Explanation
- output : type
- Explanation
- tuple : type
- Explanation
- items : type
- even more explaining
-
- Other Parameters
- ----------------
- only_seldom_used_keywords : type
- Explanation
- common_parameters_listed_above : type
- Explanation
-
- Raises
- ------
- BadException
- Because you shouldn't have done that.
-
- See Also
- --------
- otherfunc : relationship (optional)
- newfunc : Relationship (optional), which could be fairly long, in which
- case the line wraps here.
- thirdfunc, fourthfunc, fifthfunc
-
- Notes
- -----
- Notes about the implementation algorithm (if needed).
-
- This can have multiple paragraphs.
-
- You may include some math:
-
- .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
-
- And even use a greek symbol like :math:`omega` inline.
-
- References
- ----------
- Cite the relevant literature, e.g. [1]_. You may also cite these
- references in the notes section above.
-
- .. [1] O. McNoleg, "The integration of GIS, remote sensing,
- expert systems and adaptive co-kriging for environmental habitat
- modelling of the Highland Haggis using object-oriented, fuzzy-logic
- and neural-network techniques," Computers & Geosciences, vol. 22,
- pp. 585-588, 1996.
-
- Examples
- --------
- These are written in doctest format, and should illustrate how to
- use the function. Use the variables 'ds' for the dataset, 'pc' for
- a plot collection, 'c' for a center, and 'L' for a vector.
-
- >>> a=[1,2,3]
- >>> print [x + 3 for x in a]
- [4, 5, 6]
- >>> print "a\n\nb"
- a
- b
-
- """
diff -r 057c8b0cf0634b0d010426b23f7275ab84d67fe9 -r 5b5389c150b9d9ae33a8e36b03f6626f78b8da53 doc/source/developing/developing.rst
--- a/doc/source/developing/developing.rst
+++ b/doc/source/developing/developing.rst
@@ -1,497 +1,1 @@
-.. _contributing-code:
-
-How to Develop yt
-=================
-
-.. note:: If you already know how to use version control and are comfortable
- with handling it yourself, the quickest way to contribute to yt is to `fork
- us on BitBucket <http://bitbucket.org/yt_analysis/yt/fork>`_, `make your changes
- <http://mercurial.selenic.com/>`_, and issue a `pull request
- <http://bitbucket.org/yt_analysis/yt/pull-requests>`_. The rest of this document is just an
- explanation of how to do that.
-
-yt is a community project!
-
-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/
-
-The commands that are essential for using mercurial include:
-
-* ``hg commit`` which commits changes in the working directory to the
- repository, creating a new "changeset object."
-* ``hg add`` which adds a new file to be tracked by mercurial. This does
- not change the working directory.
-* ``hg pull`` which pulls (from an optional path specifier) changeset
- objects from a remote source. The working directory is not modified.
-* ``hg push`` which sends (to an optional path specifier) changeset objects
- to a remote source. The working directory is not modified.
-* ``hg log`` which shows a log of all changeset objects in the current
- repository. Use ``-g`` to show a graph of changeset objects and their
- relationship.
-* ``hg update`` which (with an optional "revision" specifier) updates the
- state of the working directory to match a changeset object in the
- repository.
-* ``hg merge`` which combines two changesets to make a union of their lines
- of development. This updates the working directory.
-
-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.
-
-.. _bootstrap-dev:
-
-Submitting Changes
-------------------
-
-We provide a brief introduction to submitting changes here. yt thrives on the
-strength of its communities ( http://arxiv.org/abs/1301.7064 has further
-discussion) and we encourage contributions from any user. While we do not
-discuss in detail version control, mercurial or the advanced usage of
-BitBucket, we do provide an outline of how to submit changes and we are happy
-to provide further assistance or guidance.
-
-Licensing
-+++++++++
-
-yt has, with the 2.6 release, been `relicensed
-<http://blog.yt-project.org/post/Relicensing.html>`_ under the BSD 3-clause
-license. Previously versions were released under the GPLv3.
-
-All contributed code must be BSD-compatible. If you'd rather not license in
-this manner, but still want to contribute, please consider creating an external
-package, which we'll happily link to.
-
-.. _requirements-for-code-submission:
-
-Requirements for Code Submission
-++++++++++++++++++++++++++++++++
-
-Modifications to the code typically fall into one of three categories, each of
-which have different requirements for acceptance into the code base. These
-requirements are in place for a few reasons -- to make sure that the code is
-maintainable, testable, and that we can easily include information about
-changes in changelogs during the release procedure. (See `YTEP-0008
-<https://ytep.readthedocs.org/en/latest/YTEPs/YTEP-0008.html>`_ for more
-detail.)
-
-* New Features
-
- * New unit tests (possibly new answer tests) (See :ref:`testing`)
- * Docstrings in the source code for the public API
- * Addition of new feature to the narrative documentation (See :ref:`writing_documentation`)
- * Addition of cookbook recipe (See :ref:`writing_documentation`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Extension or Breakage of API in Existing Features
-
- * Update existing narrative docs and docstrings (See :ref:`writing_documentation`)
- * Update existing cookbook recipes (See :ref:`writing_documentation`)
- * Modify of create new unit tests (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-* Bug fixes
-
- * Unit test is encouraged, to ensure breakage does not happen again in the
- future. (See :ref:`testing`)
- * Issue created on issue tracker, to ensure this is added to the changelog
-
-When submitting, you will be asked to make sure that your changes meet all of
-these requirements. They are pretty easy to meet, and we're also happy to help
-out with them. In :ref:`code-style-guide` there is a list of handy tips for
-how to structure and write your code.
-
-.. _mercurial-with-yt:
-
-How to Use Mercurial with yt
-++++++++++++++++++++++++++++
-
-This document doesn't cover detailed mercurial use, but on IRC we are happy to
-walk you through any troubles you might have. Here are some suggestions
-for using mercurial with yt:
-
-* Named branches are to be avoided. Try using bookmarks (``hg bookmark``) to
- track work. (`More <http://mercurial.selenic.com/wiki/Bookmarks>`_)
-* Make sure you set a username in your ``~/.hgrc`` before you commit any
- changes! All of the tutorials above will describe how to do this as one of
- the very first steps.
-* When contributing changes, you might be asked to make a handful of
- modifications to your source code. We'll work through how to do this with
- you, and try to make it as painless as possible.
-* Please avoid deleting your yt forks, as that eliminates the code review
- process from BitBucket's website.
-* In all likelihood, you only need one fork. To keep it in sync, you can
- sync from the website. (See Bitbucket's `Blog Post
- <https://blog.bitbucket.org/2013/02/04/syncing-and-merging-come-to-bitbucket/>`_
- about this.)
-* If you run into any troubles, stop by IRC (see :ref:`irc`) or the mailing
- list.
-
-.. _building-yt:
-
-Building yt
-+++++++++++
-
-If you have made changes to any C or Cython (``.pyx``) modules, you have to
-rebuild yt. If your changes have exclusively been to Python modules, you will
-not need to re-build, but (see below) you may need to re-install.
-
-If you are running from a clone that is executable in-place (i.e., has been
-installed via the installation script or you have run ``setup.py develop``) you
-can rebuild these modules by executing:
-
-.. code-block:: bash
-
- $ python2.7 setup.py develop
-
-If you have previously "installed" via ``setup.py install`` you have to
-re-install:
-
-.. code-block:: bash
-
- $ python2.7 setup.py install
-
-Only one of these two options is needed.
-
-.. _windows-developing:
-
-Developing yt on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you plan to develop yt on Windows, it is necessary to use the `MinGW
-<http://www.mingw.org/>`_ gcc compiler that can be installed using the `Anaconda
-Python Distribution <https://store.continuum.io/cshop/anaconda/>`_. The libpython package must be
-installed from Anaconda as well. These can both be installed with a single command:
-
-.. code-block:: bash
-
- $ conda install libpython mingw
-
-Additionally, the syntax for the setup command is slightly different; you must type:
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 develop
-
-or
-
-.. code-block:: bash
-
- $ python2.7 setup.py build --compiler=mingw32 install
-
-.. _sharing-changes:
-
-Making and Sharing Changes
-++++++++++++++++++++++++++
-
-The simplest way to submit changes to yt is to do the following:
-
-* Build yt from the mercurial repository
-* Navigate to the root of the yt repository
-* Make some changes and commit them
-* Fork the `yt repository on BitBucket <https://bitbucket.org/yt_analysis/yt>`_
-* Push the changesets to your fork
-* Issue a pull request.
-
-Here's a more detailed flowchart of how to submit changes.
-
-#. If you have used the installation script, the source code for yt can be
- found in ``$YT_DEST/src/yt-hg``. Alternatively see
- :ref:`source-installation` for instructions on how to build yt from the
- mercurial repository. (Below, in :ref:`reading-source`, we describe how to
- find items of interest.)
-#. Edit the source file you are interested in and
- test your changes. (See :ref:`testing` for more information.)
-#. Fork yt on BitBucket. (This step only has to be done once.) You can do
- this at: https://bitbucket.org/yt_analysis/yt/fork. Call this repository
- yt.
-#. Commit these changes, using ``hg commit``. This can take an argument
- which is a series of filenames, if you have some changes you do not want
- to commit.
-#. Remember that this is a large development effort and to keep the code
- accessible to everyone, good documentation is a must. Add in source code
- comments for what you are doing. Add in docstrings
- if you are adding a new function or class or keyword to a function.
- Add documentation to the appropriate section of the online docs so that
- people other than yourself know how to use your new code.
-#. If your changes include new functionality or cover an untested area of the
- code, add a test. (See :ref:`testing` for more information.) Commit
- these changes as well.
-#. Push your changes to your new fork using the command::
-
- hg push -r . https://bitbucket.org/YourUsername/yt/
-
- If you end up doing considerable development, you can set an alias in the
- file ``.hg/hgrc`` to point to this path.
-
- .. note::
- Note that the above approach uses HTTPS as the transfer protocol
- between your machine and BitBucket. If you prefer to use SSH - or
- perhaps you're behind a proxy that doesn't play well with SSL via
- HTTPS - you may want to set up an `SSH key`_ on BitBucket. Then, you use
- the syntax ``ssh://hg@bitbucket.org/YourUsername/yt``, or equivalent, in
- place of ``https://bitbucket.org/YourUsername/yt`` in Mercurial commands.
- For consistency, all commands we list in this document will use the HTTPS
- protocol.
-
- .. _SSH key: https://confluence.atlassian.com/display/BITBUCKET/Set+up+SSH+for+Mercurial
-
-#. Issue a pull request at
- https://bitbucket.org/YourUsername/yt/pull-request/new
- A pull request is essentially just asking people to review and accept the
- modifications you have made to your personal version of the code.
-
-
-During the course of your pull request you may be asked to make changes. These
-changes may be related to style issues, correctness issues, or even requesting
-tests. The process for responding to pull request code review is relatively
-straightforward.
-
-#. Make requested changes, or leave a comment indicating why you don't think
- they should be made.
-#. Commit those changes to your local repository.
-#. Push the changes to your fork:
-
- hg push https://bitbucket.org/YourUsername/yt/
-
-#. Your pull request will be automatically updated.
-
-.. _multiple-PRs:
-
-Working with Multiple BitBucket Pull Requests
-+++++++++++++++++++++++++++++++++++++++++++++
-
-Once you become active developing for yt, you may be working on
-various aspects of the code or bugfixes at the same time. Currently,
-BitBucket's *modus operandi* for pull requests automatically updates
-your active pull request with every ``hg push`` of commits that are a
-descendant of the head of your pull request. In a normal workflow,
-this means that if you have an active pull request, make some changes
-locally for, say, an unrelated bugfix, then push those changes back to
-your fork in the hopes of creating a *new* pull request, you'll
-actually end up updating your current pull request!
-
-There are a few ways around this feature of BitBucket that will allow
-for multiple pull requests to coexist; we outline one such method
-below. We assume that you have a fork of yt at
-``http://bitbucket.org/YourUsername/Your_yt`` (see
-:ref:`sharing-changes` for instructions on creating a fork) and that
-you have an active pull request to the main repository.
-
-The main issue with starting another pull request is to make sure that
-your push to BitBucket doesn't go to the same head as your
-existing pull request and trigger BitBucket's auto-update feature.
-Here's how to get your local repository away from your current pull
-request head using `revsets <http://www.selenic.com/hg/help/revsets>`_
-and your ``hgrc`` file:
-
-#. Set up a Mercurial path for the main yt repository (note this is a convenience
- step and only needs to be done once). Add the following to your
- ``Your_yt/.hg/hgrc``::
-
- [paths]
- upstream = https://bitbucket.org/yt_analysis/yt
-
- This will create a path called ``upstream`` that is aliased to the URL of the
- main yt repository.
-#. Now we'll use revsets_ to update your local repository to the tip of the
- ``upstream`` path:
-
- .. code-block:: bash
-
- $ hg pull upstream
- $ hg update -r "remote(tip,'upstream')"
-
-After the above steps, your local repository should be at the tip of
-the main yt repository. If you find yourself doing this a lot, it may
-be worth aliasing this task in your ``hgrc`` file by adding something like::
-
- [alias]
- myupdate = update -r "remote(tip,'upstream')"
-
-And then you can just issue ``hg myupdate`` to get at the tip of the main yt repository.
-
-Make sure you are on the branch you want to be on, and then you can
-make changes and ``hg commit`` them. If you prefer working with
-`bookmarks <http://mercurial.selenic.com/wiki/Bookmarks>`_, you may
-want to make a bookmark before committing your changes, such as ``hg
-bookmark mybookmark``.
-
-To push to your fork on BitBucket if you didn't use a bookmark, you issue the following:
-
-.. code-block:: bash
-
- $ hg push -r . -f https://bitbucket.org/YourUsername/Your_yt
-
-The ``-r .`` means "push only the commit I'm standing on and any ancestors." The
-``-f`` is to force Mecurial to do the push since we are creating a new remote head.
-
-Note that if you *did* use a bookmark, you don't have to force the push, but you do
-need to push the bookmark; in other words do the following instead of the above:
-
-.. code-block:: bash
-
- $ hg push -B mybookmark https://bitbucket.org/YourUsername/Your_yt
-
-The ``-B`` means "publish my bookmark and any relevant changesets to the remote server."
-
-You can then go to the BitBucket interface and issue a new pull request based on
-your last changes, as usual.
-
-How To Get The Source Code For Editing
---------------------------------------
-
-yt is hosted on BitBucket, and you can see all of the yt repositories at
-http://bitbucket.org/yt_analysis/. With the yt installation script you should have a
-copy of Mercurial for checking out pieces of code. Make sure you have followed
-the steps above for bootstrapping your development (to assure you have a
-bitbucket account, etc.)
-
-In order to modify the source code for yt, we ask that you make a "fork" of the
-main yt repository on bitbucket. A fork is simply an exact copy of the main
-repository (along with its history) that you will now own and can make
-modifications as you please. You can create a personal fork by visiting the yt
-bitbucket webpage at https://bitbucket.org/yt_analysis/yt/ . After logging in,
-you should see an option near the top right labeled "fork". Click this option,
-and then click the fork repository button on the subsequent page. You now have
-a forked copy of the yt repository for your own personal modification.
-
-This forked copy exists on the bitbucket repository, so in order to access
-it locally, follow the instructions at the top of that webpage for that
-forked repository, namely run at a local command line:
-
-.. code-block:: bash
-
- $ hg clone http://bitbucket.org/<USER>/<REPOSITORY_NAME>
-
-This downloads that new forked repository to your local machine, so that you
-can access it, read it, make modifications, etc. It will put the repository in
-a local directory of the same name as the repository in the current working
-directory. You can see any past state of the code by using the hg log command.
-For example, the following command would show you the last 5 changesets
-(modifications to the code) that were submitted to that repository.
-
-.. code-block:: bash
-
- $ cd <REPOSITORY_NAME>
- $ hg log -l 5
-
-Using the revision specifier (the number or hash identifier next to each
-changeset), you can update the local repository to any past state of the
-code (a previous changeset or version) by executing the command:
-
-.. code-block:: bash
-
- $ hg up revision_specifier
-
-Lastly, if you want to use this new downloaded version of your yt repository as
-the *active* version of yt on your computer (i.e. the one which is executed when
-you run yt from the command line or the one that is loaded when you do ``import
-yt``), then you must "activate" it using the following commands from within the
-repository directory.
-
-.. code-block:: bash
-
- $ cd <REPOSITORY_NAME>
- $ python2.7 setup.py develop
-
-This will rebuild all C modules as well.
-
-.. _reading-source:
-
-How To Read The Source Code
----------------------------
-
-If you just want to *look* at the source code, you may already have it on your
-computer. If you build yt using the install script, the source is available at
-``$YT_DEST/src/yt-hg``. See :ref:`source-installation` for more details about
-to obtain the yt source code if you did not build yt using the install
-script.
-
-The root directory of the yt mercurial repository contains a number of
-subdirectories with different components of the code. Most of the yt source
-code is contained in the yt subdirectory. This directory its self contains
-the following subdirectories:
-
-``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, Dataset
- and AMRHierarchy are defined.
- * ``io.py``, where a subclass of IOHandler is defined.
- * ``fields.py``, where fields we expect to find in datasets are 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.)
-
-``fields``
- This is where all of the derived fields that ship with yt are defined.
-
-``geometry``
- This is where geometric helpler routines are defined. Handlers
- for grid and oct data, as well as helpers for coordinate transformations
- can be found here.
-
-``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.
-
-``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.
-
-``extern``
- Bundled external modules (i.e. code that was not written by one of
- the yt authors but that yt depends on) lives here.
-
-
-If you're looking for a specific file or function in the yt source code, use
-the unix find command:
-
-.. code-block:: bash
-
- $ find <DIRECTORY_TREE_TO_SEARCH> -name '<FILENAME>'
-
-The above command will find the FILENAME in any subdirectory in the
-DIRECTORY_TREE_TO_SEARCH. Alternatively, if you're looking for a function
-call or a keyword in an unknown file in a directory tree, try:
-
-.. code-block:: bash
-
- $ grep -R <KEYWORD_TO_FIND><DIRECTORY_TREE_TO_SEARCH>
-
-This can be very useful for tracking down functions in the yt source.
-
-.. _code-style-guide:
-
-.. include:: ../../../coding_styleguide.txt
+.. include:: ../../../CONTRIBUTING.rst
diff -r 057c8b0cf0634b0d010426b23f7275ab84d67fe9 -r 5b5389c150b9d9ae33a8e36b03f6626f78b8da53 doc/source/developing/index.rst
--- a/doc/source/developing/index.rst
+++ b/doc/source/developing/index.rst
@@ -16,7 +16,6 @@
.. toctree::
:maxdepth: 2
- intro
developing
building_the_docs
testing
diff -r 057c8b0cf0634b0d010426b23f7275ab84d67fe9 -r 5b5389c150b9d9ae33a8e36b03f6626f78b8da53 doc/source/developing/intro.rst
--- a/doc/source/developing/intro.rst
+++ /dev/null
@@ -1,218 +0,0 @@
-.. _getting-involved:
-
-Getting Involved
-================
-
-There are *lots* of ways to get involved with yt, as a community and as a
-technical system -- not all of them just contributing code, but also
-participating in the community, helping us with designing the websites, adding
-documentation, and sharing your scripts with others.
-
-Coding is only one way to be involved!
-
-Communication Channels
-----------------------
-
-There are four main communication channels for yt:
-
- * We have an IRC channel, on ``irc.freenode.net`` in ``#yt``.
- You can connect through our web
- gateway without any special client, at http://yt-project.org/irc.html .
- *IRC is the first stop for conversation!*
- * `yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_
- is a relatively high-traffic mailing list where people are encouraged to ask
- questions about the code, figure things out and so on.
- * `yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_ is
- a much lower-traffic mailing list designed to focus on discussions of
- improvements to the code, ideas about planning, development issues, and so
- on.
- * `yt-svn <http://lists.spacepope.org/listinfo.cgi/yt-svn-spacepope.org>`_ is
- the (now-inaccurately titled) mailing list where all pushes to the primary
- repository are sent.
-
-The easiest way to get involved with yt is to read the mailing lists, hang out
-in IRC, and participate. If someone asks a question you know the answer to (or
-have your own question about!) write back and answer it.
-
-If you have an idea about something, suggest it! We not only welcome
-participation, we encourage it.
-
-.. _share-your-scripts:
-
-Share Your Scripts
-------------------
-
-.. warning:: The yt Hub is currently offline due to some hosting problems. We
- hope to have it back up online soon.
-
-The next easiest way to get involved with yt is to participate in the `yt Hub
-<http://hub.yt-project.org/>`_. This is a place where scripts, paper
-repositories, documents and so on can be submitted to share with the broader
-community.
-
-If you have a repository on `BitBucket <https://bitbucket.org/>`_ then you can
-simply submit it through the ytHub submit link. Otherwise, we provide the
-``yt hubsubmit`` command, which will guide you through the process of creating
-a mercurial repository, uploading it to BitBucket, and then submitting it
-directly to the Hub.
-
-This is one of the best ways to get involved in the community! We would love
-to have more examples that show complex or advanced behavior -- and if you have
-used such scripts to write a paper, that too would be an amazing contribution.
-
-Documentation
--------------
-
-The yt documentation -- which you are reading right now -- is constantly being
-updated, and it is a task we would very much appreciate assistance with.
-Whether that is adding a section, updating an outdated section, contributing
-typo or grammatical fixes, adding a FAQ, or increasing coverage of
-functionality, it would be very helpful if you wanted to help out.
-
-The easiest way to help out is to fork the main yt repository (where the
-documentation lives in the ``doc`` directory in the root of the yt mercurial
-repository) and then make your changes in your own fork. When you are done,
-issue a pull request through the website for your new fork, and we can comment
-back and forth and eventually accept your changes.
-
-Gallery Images and Videos
--------------------------
-
-If you have an image or video you'd like to display in the image or video
-galleries, getting it included it easy! You can either fork the `yt homepage
-repository <http://bitbucket.org/yt_analysis/website>`_ and add it there, or
-email it to us and we'll add it to the `Gallery
-<http://yt-project.org/gallery.html>`_.
-
-We're eager to show off the images and movies you make with yt, so please feel
-free to drop `us <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_
-a line and let us know if you've got something great!
-
-Technical Contributions
------------------------
-
-Contributing code is another excellent way to participate -- whether it's
-bug fixes, new features, analysis modules, or a new code frontend. See
-:ref:`creating_frontend` for more details.
-
-The process is pretty simple: fork on BitBucket, make changes, issue a pull
-request. We can then go back and forth with comments in the pull request, but
-usually we end up accepting.
-
-For more information, see :ref:`contributing-code`, where we spell out how to
-get up and running with a development environment, how to commit, and how to
-use BitBucket.
-
-Online Presence
----------------
-
-Some of these fall under the other items, but if you'd like to help out with
-the website or any of the other ways yt is presented online, please feel free!
-Almost everything is kept in hg repositories on BitBucket, and it is very easy
-to fork and contribute back changes.
-
-Please feel free to dig in and contribute changes.
-
-Word of Mouth
--------------
-
-If you're using yt and it has increased your productivity, please feel
-encouraged to share that information. Cite our `paper
-<http://adsabs.harvard.edu/abs/2011ApJS..192....9T>`_, tell your colleagues,
-and just spread word of mouth. By telling people about your successes, you'll
-help bring more eyes and hands to the table -- in this manner, by increasing
-participation, collaboration, and simply spreading the limits of what the code
-is asked to do, we hope to help scale the utility and capability of yt with the
-community size.
-
-Feel free to `blog <http://blog.yt-project.org/>`_ about, `tweet
-<http://twitter.com/yt_astro>`_ about and talk about what you are up to!
-
-Long-Term Projects
-------------------
-
-There are some wild-eyed, out-there ideas that have been bandied about for the
-future directions of yt -- some of them even written into the mission
-statement. The ultimate goal is to move past simple analysis and visualization
-of data and begin to approach it from the other side, of generating data,
-running solvers. We also hope to increase its ability to act as an in situ
-analysis code, by presenting a unified protocol. Other projects include
-interfacing with ParaView and VisIt, creating a web GUI for running
-simulations, creating a run-tracker that follows simulations in progress, a
-federated database for simulation outputs, and so on and so forth.
-
-yt is an ambitious project. Let's be ambitious together.
-
-yt Community Code of Conduct
-----------------------------
-
-The community of participants in open source
-Scientific projects is made up of members from around the
-globe with a diverse set of skills, personalities, and
-experiences. It is through these differences that our
-community experiences success and continued growth. We
-expect everyone in our community to follow these guidelines
-when interacting with others both inside and outside of our
-community. Our goal is to keep ours a positive, inclusive,
-successful, and growing community.
-
-As members of the community,
-
-- We pledge to treat all people with respect and
- provide a harassment- and bullying-free environment,
- regardless of sex, sexual orientation and/or gender
- identity, disability, physical appearance, body size,
- race, nationality, ethnicity, and religion. In
- particular, sexual language and imagery, sexist,
- racist, or otherwise exclusionary jokes are not
- appropriate.
-
-- We pledge to respect the work of others by
- recognizing acknowledgment/citation requests of
- original authors. As authors, we pledge to be explicit
- about how we want our own work to be cited or
- acknowledged.
-
-- We pledge to welcome those interested in joining the
- community, and realize that including people with a
- variety of opinions and backgrounds will only serve to
- enrich our community. In particular, discussions
- relating to pros/cons of various technologies,
- programming languages, and so on are welcome, but
- these should be done with respect, taking proactive
- measure to ensure that all participants are heard and
- feel confident that they can freely express their
- opinions.
-
-- We pledge to welcome questions and answer them
- respectfully, paying particular attention to those new
- to the community. We pledge to provide respectful
- criticisms and feedback in forums, especially in
- discussion threads resulting from code
- contributions.
-
-- We pledge to be conscientious of the perceptions of
- the wider community and to respond to criticism
- respectfully. We will strive to model behaviors that
- encourage productive debate and disagreement, both
- within our community and where we are criticized. We
- will treat those outside our community with the same
- respect as people within our community.
-
-- We pledge to help the entire community follow the
- code of conduct, and to not remain silent when we see
- violations of the code of conduct. We will take action
- when members of our community violate this code such as
- contacting confidential at yt-project.org (all emails sent to
- this address will be treated with the strictest
- confidence) or talking privately with the person.
-
-This code of conduct applies to all
-community situations online and offline, including mailing
-lists, forums, social media, conferences, meetings,
-associated social events, and one-to-one interactions.
-
-The yt Community Code of Conduct was adapted from the
-`Astropy Community Code of Conduct
-<http://www.astropy.org/about.html#codeofconduct>`_,
-which was partially inspired by the PSF code of conduct.
diff -r 057c8b0cf0634b0d010426b23f7275ab84d67fe9 -r 5b5389c150b9d9ae33a8e36b03f6626f78b8da53 doc/source/reference/changelog.rst
--- a/doc/source/reference/changelog.rst
+++ b/doc/source/reference/changelog.rst
@@ -644,7 +644,7 @@
* libconfig is now included
* SQLite3 and Forthon now included by default in the install script
* Development guide has been lengthened substantially and a development
- bootstrap script (:ref:`bootstrap-dev`) is now included.
+ bootstrap script is now included.
* Installation script now installs Python 2.7 and HDF5 1.8.6
* iyt now tab-completes field names
* Halos can now be stored on-disk much more easily between HaloFinding runs.
Repository URL: https://bitbucket.org/yt_analysis/yt/
--
This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.
More information about the yt-svn
mailing list