developers.txt

Structure
=========

Build scripts are located in the root directory, the package source code is in
`/src/` with examples in `src/openbandaprams/examples/` and tests in
`/src/openbandarams/tests/`. Documentation is in `/doc/`.

Documentation
=============

Documentation is generated with Sphinx, by basically following
[this tutorial](http://matplotlib.org/sampledoc/). The `build_doc.py` script
can be used to build the documentation automatically (and generate the example
results).

Uploading the documentation to github ph-pages is described in
[[How To Release a New Version]].

Git Branching Model
===================
I'm using the Git branching model described
[here](http://nvie.com/posts/a-successful-git-branching-model/).

Design
======

A somewhat unusual approach was required to get the desired API.

Here's the problem: some of the parameters depend on temperature, and some
don't. The ones that depend on temperature have to be functions, while the
ones that don't are not functions. The user has no clear way of knowing which
parameters are functions, and which are not, until an exception is thrown. I
could have either made all parameters functions of temperature, even if they
aren't really, or I could make them all functions with keyword arguments, and
only use T values if needed (and show in the docstring if it's used). The
latter approach is the one I settled on.

The next question was how to best store the parameters. Should they be
hardcoded in, with references in comments? This is the most runtime efficient.
If I have a separate wiki for maintaining the most up-to-date values, then I
could just do periodic releases with the changes from the wiki incorporated by
looking at the wiki change history. This would be a fairly manual approach, as
apposed to automated. However, in this case I think requiring a human in the
loop isn't necessarily a bad thing, since the human can sanity check the
changes. Apparently Linus still does merges to the Linux kernal by hand.

It's important that the user interface is easy to understand and use.
Ultimately it doesn't matter how complex the implementation is (as long as it
works). Thus, I'm designing the interface, and only then figuring out how to
implement it.

How To Release a New Version
============================

When you want release a new version, follow these directions. First, bump the
version number on the develop branch, if it hasn't already been bumped. From
the root of the git repository run these commands (substitute the
appropriate version number): 

    git checkout develop
    echo "__version__ = '0.9'" > src/openbandparams/version.py
    git commit -am "Bump version to 0.9"
    
Next, create a release branch by branching off of the develop branch (again,
substituting the appropriate version number):

    git checkout -b release-0.9 develop

Now is a good time to run the unit tests and examples, to make sure you haven't
missed any bugs:

    python test.py
    python build_doc.py clean

Also build, install, and test in a virtualenv:

    virtualenv venv
    source venv/bin/activate
    python setup.py build
    python setup.py install
    python -m openbandparams.tests
    deactivate
    rm -rf venv

Go ahead and fix any bugs you find in the release branch, and we'll merge them
back into the develop branch later.

If everything checks out, and you're sure the release is bug free and ready to
go, now is a good time to upload the documentation, since you have it built.
The easiest way to do this is to have a separate clone of the git repository
that always remains on the `gh-pages` branch. So, you're directory structure
might look something like this:

    code
    |-- openbandparams
    |   |-- doc
    |   |   `-- _build
    |   |       `-- html
    |   `-- src
    `-- openbandparams-gh-pages
        |-- 0.6
        |   |-- [html files]
        |   `-- index.html
        |-- 0.7
        |   |-- [html files]
        |   `-- index.html
        `-- index.html

Starting from the `code` directory, execute these commands to copy the html
files from `openbandparams` into `openbandparams-gh-pages/0.9`:

    rm -rf openbandparams-gh-pages/0.9
    cp -R openbandparams/doc/_build/html openbandparams-gh-pages/0.9

Now, if 0.9 didn't exist yet, we need to add it to the front page index.
Open `openbandparams-gh-pages/index.html` and find the following line:

    <li class="toctree-l1"><a class="reference internal" href="0.8">0.8</a></li>

Copy and paste this line just above it:

    <li class="toctree-l1"><a class="reference internal" href="0.9">0.9</a></li>

Now, commit the changes and push them to github:

    cd openbandparams-gh-pages
    git add .
    git commit -m "added v0.9 documentation"
    git push origin gh-pages
    cd ../openbandparams

Next, merge the changes from the release branch into the master branch, and
tag the release:

    git checkout master
    git merge --no-ff release-0.9
    git tag -a v0.9
    git push origin

Then run the following commands from the root of the git repository to build
and upload the release to PyPI:

    python setup.py build sdist bdist_egg
    python setup.py register sdist bdist_egg upload

Now go to the github page to "create a release" and upload the 'egg', 'zip',
and 'tar.gz' files from the 'dist' directory.

Congratulations, you're done releasing the new version of openbandparams!
If any changes were made during the release branche, merge the release branch
into the develop branch, and then delete the release branch:

    git checkout develop
    git merge --no-ff release-0.9
    git branch -d release-0.9

You might want to make a doc-0.9 branch, in case you find errors in the
documentation you want to correct.

    git branch doc-0.9 develop

You can also go ahead and bump the version number now, so that future builds
of the documentation already have the correct version number:

    echo "__version__ = '0.10'" > src/openbandparams/version.py
    git commit -am "Bumbed version number to 0.10"