exoplanet
exoplanet
Development of exoplanet is actively happening on GitHub and we would love your contributions.
There are a few different methods of contributing to exoplanet and the details are discussed below.
If you run into issues, bugs, or anything else, it is very useful if you can post an issue on the GitHub repository. When you post an issue, please provide the details to reproduce the issue. For example, if you find a bug, please provide a standalone and executable snippet of code that demonstrates the issue. It’s also useful to include details about your platform and the versions of key packages that your using.
If you’re not familiar with the workflow for contributing code to a GitHub repository, an excellent place to start is the AstroPy developer docs.
After getting some familiarity with the workflow, you should fork the exoplanet repository and clone it to your local machine:
git clone https://github.com/YOURUSERNAME/exoplanet.git
cd exoplanet
git checkout -b BRANCHNAME
for some name BRANCHNAME describing your contribution.
Then you should set up an isolated environment for development using a Conda environment, virtualenv, venv, or similar.
If using conda, you can get the current development environment from the environment.yml file:
conda env create --prefix env -f environment.yml
conda activate ./env
If you have an existing conda environment for exoplanet, you can update it using:
conda env update --prefix ./env -f environment.yml --prune
If you’re using a pip based environment, you can install the developer dependencies as follows:
python -m pip install -U pip
python -m pip install -U -r requirements-dev.txt
After your environment is set up, you can install the current development version of exoplanet:
python -m pip install -U setuptools setuptools_scm pep517
python -m pip uninstall -y exoplanet
python setup.py develop
exoplanet is mostly arranged as a typical Python project with the module root in the src/exoplanet directory.
But there are a few directions that can be useful before diving in:
1. Theano ops: exoplanet comes bundled with a set of custom Theano ops that are implemented in src/exoplanet/theano_ops.
As a user, you’ll rarely interact with these directly and we haven’t put a lot of work into making them user friendly, but if you are interested in diving in, here are some tips.
First, you should check out the Theano docs that describe how to develop new ops in Python and C/C++.
Most of the exoplanet ops are implemented in C++ for speed and we’ve made the design decision to separate the “science” code (which implements the actual operation without any dependency on Theano) and “wrapper” code (which sets up the interface).
The science code is implemented as a header-only C++ library in src/exoplanet/theano_ops/lib/include/exoplanet and then the wrappers are implemented as submodules in src/exoplanet/theano_ops.
A good place to start is the KeplerOp implemented in src/exoplanet/theano_ops/kepler and src/exoplanet/theano_ops/lib/include/exoplanet/kepler.h.
2. Tutorials: It can be a bit confusing to see where the tutorials should be added or updated because there are several copies throughout the repository.
But, if you want to make a change or add a new tutorial, the only directory you should need to touch is docs/notebooks and you must strip the output before committing so that the repository doesn’t get too huge (I use nbstripout).
These will then be automatically executed and saved to the docs/_static/notebooks before the next release.
If you are contributing a new tutorial, you should copy one of the existing ones and try to follow roughly the same format.
If you’re contributing a change to the code (either a new feature or bug fix), make sure that you implement at least one test that checks the behavior of your code. Then, you should run all of the unit tests before submitting a pull request using the following command:
python -m pytest -sv src/exoplanet
We have a pretty strict (but easy to implement!) set of style guidelines for the codebase.
For Python code, we use isort, black, and black_nbconvert (for Jupyter notebooks).
The custom settings for these projects can be found in pyproject.toml.
Before opening a pull request, you can run the formatters as follows:
isort -rc src
black src
black_nbconvert .
Or, you can use pre-commit to automatically apply the formatting whenever you commit:
python -m pip install -U pre-commit
pre-commit install
Note
Most of this build process is based on the October 2019 update to this blog post so you should check that out if you want more info.
This section is mainly internal, but these are the steps that should be executed to produce a new release.
src/exoplanet/citations.py.run_notebooks.sh to make sure that the tutorials all run and merge the updated notebooks on GitHub.HISTORY.rst.After executing these steps, the release can be built as follows:
python -m pip install -U pip pep517 twine setuptools_scm
git pull
rm -rf build dist
python -m pep517.build .
Then you can test that the build installs as expected:
rm -rf venv-test
python -m venv venv-test
venv-test/bin/python -m pip install dist/exoplanet*.tar.gz
venv-test/bin/python -c "import exoplanet;print(exoplanet.__version__)"
This should print the current version number. Similarly you can test the wheel:
rm -rf venv-test
python -m venv venv-test
venv-test/bin/python -m pip install dist/exoplanet*.whl
venv-test/bin/python -c "import exoplanet;print(exoplanet.__version__)"
Once you’re satisfied with this build, you can upload it using twine:
twine upload dist/*