1 2.. highlight: console 3 4============ 5Contributing 6============ 7 8Contributions are welcome, and they are greatly appreciated! Every 9little bit helps, and credit will always be given. 10 11Please note, that we have hooked a CLA assistant to this GitHub Repo. Please accept the contributors license agreement to allow us to keep a legal track of contributions and keep this package open source for the future. 12 13You can contribute in many ways: 14 15Types of Contributions 16---------------------- 17 18Report Bugs 19~~~~~~~~~~~ 20 21Report bugs at https://github.com/ecmwf/eccodes-python/issues 22 23If you are reporting a bug, please include: 24 25* Your operating system name and version. 26* Installation method and version of all dependencies. 27* Any details about your local setup that might be helpful in troubleshooting. 28* Detailed steps to reproduce the bug, including a sample file. 29 30Fix Bugs 31~~~~~~~~ 32 33Look through the GitHub issues for bugs. Anything tagged with "bug" 34and "help wanted" is open to whoever wants to implement a fix for it. 35 36Implement Features 37~~~~~~~~~~~~~~~~~~ 38 39Look through the GitHub issues for features. Anything tagged with "enhancement" 40and "help wanted" is open to whoever wants to implement it. 41 42Get Started! 43------------ 44 45Ready to contribute? Here's how to set up `eccodes-python` for local development. Please note this documentation assumes 46you already have `virtualenv` and `Git` installed and ready to go. 47 481. Fork the `eccodes-python` repo on GitHub. 492. Clone your fork locally:: 50 51 $ cd path_for_the_repo 52 $ git clone https://github.com/YOUR_NAME/eccodes-python.git 53 $ cd eccodes-python 54 553. Assuming you have virtualenv installed (If you have Python3.5 this should already be there), you can create a new environment for your local development by typing:: 56 57 $ virtualenv ../eccodes-python-env 58 $ source ../eccodes-python-env/bin/activate 59 60 This should change the shell to look something like 61 (eccodes-python-env) $ 62 634. Install system dependencies as described in the README.rst file then install a known-good set of python dependencies and the your local copy with:: 64 65 $ pip install -r ci/requirements-tests.txt 66 $ pip install -e . 67 685. Create a branch for local development:: 69 70 $ git checkout -b name-of-your-bugfix-or-feature 71 72 Now you can make your changes locally. 73 746. The next step would be to run the test cases. `eccodes-python` uses py.test, you can run PyTest. Before you run pytest you should ensure all dependencies are installed:: 75 76 $ pip install -r ci/requirements-dev.txt 77 $ pytest -v --flakes 78 797. Before raising a pull request you should also run tox. This will run the tests across different versions of Python:: 80 81 $ tox 82 838. If your contribution is a bug fix or new feature, you should add a test to the existing test suite. 84 859. Format your Python code with the Black auto-formatter, to ensure the code is uses the library's style. We use the default Black configuration (88 lines per character and `"` instead of `'` for string encapsulation):: 86 87 $ black . 88 8910. Commit your changes and push your branch to GitHub:: 90 91 $ git add . 92 $ git commit -m "Your detailed description of your changes." 93 $ git push origin name-of-your-bugfix-or-feature 94 9511. Submit a pull request through the GitHub website. 96 97Pull Request Guidelines 98----------------------- 99 100Before you submit a pull request, check that it meets these guidelines: 101 1021. The pull request should include tests. 103 1042. If the pull request adds functionality, the docs should be updated. Put 105 your new functionality into a function with a docstring, and add the 106 feature to the list in README.rst. 107 1083. The pull request should work for Python 2.7, 3.5, 3.6, 3.7 and 3.8, and for PyPy2 and Pypy3. 109 Check the tox results and make sure that the tests pass for all supported Python versions. 110 111 112Testing CDS data 113---------------- 114 115You can test the CF-GRIB driver on a set of products downloaded from the Climate Data Store 116of the `Copernicus Climate Change Service <https://climate.copernicus.eu>`_. 117If you are not register to the CDS portal register at: 118 119 https://cds.climate.copernicus.eu/user/register 120 121In order to automatically download and test the GRIB files install and configure the `cdsapi` package:: 122 123 $ pip install cdsapi 124 $ pip install netcdf4 125 126The log into the CDS portal and setup the CDS API key as described in: 127 128 https://cds.climate.copernicus.eu/api-how-to 129 130Then you can run:: 131 132 $ pytest -vv tests/cds_test_*.py 133 134 135.. eccodes-python: https://github.com/ecmwf/eccodes-python 136.. virtualenv: https://virtualenv.pypa.io/en/stable/installation 137.. git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git 138