We welcome and encourage your contributions to the Solar Forecast Arbiter. This guide aims to provide potential contributors with a better idea of how to prepare their code for the solarforecastarbiter-core and what to expect from the project maintainers.
This guide focuses on code contributions, but we equally value contributions such as issue reports, code review, and documentation suggestions.
Contributors should review the glossary of terms and the guidance for variable names.
solarforecastarbiter-core follows the PEP 8 – Style Guide for Python Code. Maximum line length for code is 79 characters.
Code must be compatible with Python 3.7 and above.
Set your editor to strip extra whitespace from line endings. This prevents the git commit history from becoming cluttered with whitespace changes.
The majority of the solarforecastarbiter-core code consists of
functions that accept primitives or pandas.Series. Some higher-level
Avoid writing new classes and methods.
Code should raise an exception if a problem occurs and a solution is not certain to be correct in all situations.
Logging is encouraged in higher-level functions.
DataFrames and Series¶
The solarforecastarbiter-core repository focuses on analyses of time series data. The code makes extensive use of pandas objects with DatetimeIndexes. In most cases, code should expect and return one or more pandas.Series rather than a pandas.DataFrame. A function that requires multiple Series is self-documenting by virtue of the names of the parameters. Providing or expecting the wrong data from such a function raises an exception at the API level, where it belongs. A function that expects a single DataFrame must carefully document the required keys, providing the wrong data will result in a problem deep within the function, and expecting the wrong data will result in a problem far away from the function.
The exceptions to the “use Series instead of DataFrames” rule are:
- observation data may be packaged into a DataFrame with ‘value’ and ‘quality_flag’ columns.
- probabilistic forecasts.
Documentation must be written in numpydoc format format which is rendered using the Sphinx Napoleon extension.
To build the docs locally, install the dependencies specified in the
file. After installing the dependencies, run
make -C docs html from
the root of the repository.
The vast majority of new or modified code requires contributors to write new tests.
A pull request will automatically run the tests for you. However, it is typically more efficient to run and debug the tests in your own local environment. See Installation for instructions to set up and use an environment.
To run the tests locally, install the
test dependencies specified in the
file. The unit tests may be run using:
Pull request review¶
The solarforecastarbiter-core maintainers and community members will review pull requests for all of the topics discussed above. GitHub will provide a checklist when creating a pull request. Feel free to submit a pull request before the work is complete.
Please keep each contribution to as few lines of code as possible. We’d much rather review many short pull requests than one long pull request.
See GitHub’s About pull requests guide for more on the mechanics of the process.