Contributing

Interested in contributing to Edward? We appreciate all kinds of help!

Community

For general discussion about Edward, use Edward’s Gitter channel. For example, it is used to get help with installation, coding and debugging in Edward, and probabilistic modeling. (We also plan to have a mailing list-like option in the future.)

For development discussion about Edward, use Edward’s Github issues tracker. For example, it is used to submit bug reports and feature requests.

Pull requests

We gladly welcome pull requests.

Before making any changes, we recommend opening an issue (if it doesn’t already exist) and discussing your proposed changes. This will let us give you feedback on whether the changes should be made and advice on how they should be made. If the changes are minor, then feel free to make them without discussion.

Want to contribute but not sure what to contribute? Here are two suggestions:

  1. Add a new example or tutorial. New scripts in the examples/ directory are easy to add. They can also get you acquainted with Edward’s developer process. Alternatively, add new tutorials to the website from the docs/tex/ directory.
  2. Solve one of Edward’s existing Github issues. They range from low-level software bugs to higher-level design problems. One or two may pique your interest!

To make changes, fork the repo. Write code in this fork with the following guidelines in mind:

Style guide. Follow TensorFlow’s style guide for writing code, which more or less follows PEP 8. Follow NumPy’s documentation guide for writing documention, and follow TensorFlow’s documentation guide for describing TensorFlow tensors in the documentation.

Unit testing. Unit testing is awesome. It’s useful not only for checking code after having written it, but also in checking code as you are developing it. Most pull requests require unit tests. Follow TensorFlow’s testing guide. To run the unit tests, we use py.test: run py.test tests/. To run specific unit tests, call py.test individually, e.g., py.test tests/test_metrics.py.

Submit the pull request whenever you’re ready. You can also submit an incomplete pull request to get intermediate feedback.

Suggested developer workflow

If you’re developing in Edward, we recommend downloading and installing Edward locally. This enables any local changes you make to Edward to appear any time you import Edward in a Python session. To install locally, run the following:

git clone git@github.com:blei-lab/edward.git
pip install -e edward

We recommend not installing with sudo but with virtualenv. In fact, we recommend virtualenvwrapper, which is a light wrapper on top of virtualenv. Here is a guide on how to set it up.

All code should be compatible with both Python 2 and 3. virtualenvwrapper makes it easy to develop in both Python versions and let them manage their own packages. If you set up virtualenvwrapper from the above guide, here is a guide on how to setup a virtualenv with Python 3. Now we need only work on the corresponding virtualenv to ensure Python 2 and 3 compatibility.

Suggested private developer workflow

Sometimes it’s useful to work privately on Edward, such as for developing unpublished experiments. To do this, we suggest using a private repo that maintains the master branch from the Edward repo. Development happens on the private repo’s branch, and when it is finished, you can push it to a public repo’s branch and then submit a pull request. We describe this in detail.

Clone the private repo so you can work on it (create a repo if it does not exist).

git clone https://github.com/blei-lab/edward-private.git

Pull changes from the public repo. This will let the private repo have the latest code from the public repo on its master branch.

cd edward-private
git remote add public https://github.com/blei-lab/edward.git
git pull public master # Creates a merge commit
git push origin master

Now create your branch on the private repo, develop stuff, and pull any latest changes from the public repo as you develop (git pull public master).

Finally, to create a pull request from a private repo’s branch to the public repo, push the private branch to the public repo.

git clone https://github.com/blei-lab/edward.git
cd edward
git remote add private https://github.com/blei-lab/edward-private.git
git checkout -b pull_request_yourname
git pull private master
git push origin pull_request_yourname

Now simply create a pull request via the Github UI on the public repo. Once project owners review the pull request, they can merge it. Source