Contributing to CLIMLAB¶
This is an open project, and contributions of all kinds are welcome.
Here are some guidelines for how to get involved.
Usage in publications, teaching, etc.¶
If you use CLIMLAB in any way for published research or theses, online teaching materials, or anything else, we would appreciate hearing about it. Our goal is to maintain a list of links and references to use cases. This is essential information for our funders (NSF) but will also be a great resource for new users looking to find out more about what you can do with CLIMLAB.
For publications, please cite the CLIMLAB description paper in JOSS. The full citation is:
Rose, (2018). CLIMLAB: a Python toolkit for interactive, process-oriented climate modeling. Journal of Open Source Software, 3(24), 659, https://doi.org/10.21105/joss.00659
Reporting bugs, issues, new feature requests, and documentation problems¶
These can all be raised as new issues at <https://github.com/brian-rose/climlab/issues>
If you are reporting a bug, try to include:
- Your operating system name and version
- The Python and CLIMLAB versions you are using
- Minimal code to reproduce the bug
If you aren’t sure about any of this, please just post your issue anyway and we will assist.
Feel free to point out any inaccuracies or omissions in the documentation here as well.
Seeking help and support¶
Although CLIMLAB is offered to the community “as-is”, we are very interested in helping people actually use it for scientific purposes.
Have a question about how to do something with CLIMLAB? First, make sure you’ve perused the documentation and the issue tracker at <https://github.com/brian-rose/climlab/issues>. Also look through published examples including the repository of lecture notes at <https://github.com/brian-rose/ClimateModeling_courseware>.
Then, feel free to ask questions by opening a new issue at <https://github.com/brian-rose/climlab/issues>. This requires a free github account but is the best way to engage the community for answers. We will do our best to respond. If the functionality you’re looking for doesn’t yet exist, we’ll probably encourage you to get involved in developing the next big feature.
Contributing bug fixes and new features¶
We are thrilled to have any and all help. You may want to browse through <https://github.com/brian-rose/climlab/issues> to see if there is any low-hanging fruit already identified.
Contributions will happen through Pull Requests on github. You will need a free github account. Here’s how to get started:
Don’t make any commits on your local master branch. Instead open a feature branch for every new development task:
git checkout -b cool_new_feature
(choose a more descriptive name for your new feature).
Work on your new feature, using
git addto add your changes.
Build and Test your modified code! See Building and Testing CLIMLAB below for instructions. Make sure to add new tests for your cool new feature.
When your feature is complete and tested, commit your changes:
git commit -m 'I made some cool new changes'
and push your branch to github:
git push origin cool_new_feature
At this point, you go find your fork on github and create a pull request. Clearly describe what you have done in the comments. We will gladly merge any pull requests that fix outstanding issues with the code or documentation. If you are adding a new feature, it is important to also add appropriate tests of the new feature to the automated test suite. If you don’t know how to do this, submit your pull request anyway and we will assist.
After your pull request is merged, you can switch back to the master branch, rebase, and delete your feature branch. You will find your improvements are incorporated into CLIMLAB:
git checkout master git fetch upstream git rebase upstream/master git branch -d cool_new_feature
Building and Testing CLIMLAB¶
CLIMLAB has an extensive set of tests designed to work with pytest. The test code is found in the
climlab/tests directory inside the source repo.
To run the full set of tests on the currently installed version of CLIMLAB, you can always do this:
pytest -v --pyargs climlab
All tests should report
CLIMLAB is a mix of pure Python and compiled Fortran. If you are developing new code that does not rely on the compiled components, it is useful to run tests directly from the source code directory. From the
climlab root directory, do the following:
pytest -v -m "not compiled"
which excludes the tests marked as requiring the compiled components. Again, look for all tests to report
PASSED. For more details see the pytest documentation.
If you are interacting with compiled components (e.g. RRTMG radiation), testing is a little more complicated. You will need to rebuild and install a new version. We use (and recommend) conda build to handle the dependencies including Fortran compiler.
To build CLIMLAB, do this from the root directory of the CLIMLAB source repo:
This will automatically install all build dependencies in a temporary new conda environment, build all the Fortran extensions, bundle everything together, install the new pacakge in a temporary test environment, and run a minimal set of tests on the package (only the tests marked as
fast). The whole procedure will take several minutes to run through.
Assuming the tests pass successfully, you will see a message like:
TEST END: /Users/br546577/anaconda3/conda-bld/osx-64/climlab-0.6.5.dev0-py36_5.tar.bz2
(though obviously with different paths and version numbers)
To fully test your new build (including the tests not marked as
fast), you can now install it in a new test environment (with all dependencies) and run the full set of tests:
conda create --name newtest climlab --use-local source activate newtest pytest -v --pyargs climlab
Once you’re happy with this you can safely delete the test environment with:
source deactivate conda remove --name newtest --all
If you encounter problems with the conda build recipe, please raise an issue at <https://github.com/brian-rose/climlab/issues>. You could also take a look at the CLIMLAB recipe used on conda-forge, which might be a little more up-to-date.
Contributing improved documentation¶
Edit doctrings and/or .rst files in
Build the improved docs locally with:
- The new and improved docs should now be available locally in the
climlab/docs/build/htmldirectory. Check them out in your web browser.
- Once you are satisfied, commit changes as described above and submit a new Pull Request describing your changes.