Skip to content

Latest commit

 

History

History
121 lines (87 loc) · 6.39 KB

code.md

File metadata and controls

121 lines (87 loc) · 6.39 KB
Raw

Contributing to the Code

Encouraging more people to help develop lori is essential to the project's success. Therefore, we want to make it easy and straight forward for you to contribute.

There is a lot of material in this section, aimed at a variety of contributors from novice to expert. Don't worry if you don't (yet) understand parts of it.

How to contribute new code

The basics

Contributors to lori use GitHub's pull requests to add/modify its source code. The GitHub pull request process can be intimidating for new users, but you'll find that it becomes straightforward once you use it a few times. Please let us know if you get stuck at any point in the process. Here's an outline of the process:

  • Create a GitHub issue and get initial feedback from users and maintainers.
    If the issue is a bug report, please take a look at how to report bugs.
  • Obtain the latest version of lori: Fork the lori project to your GitHub account, git clone your fork to your computer.
  • Make some or all of your changes/additions and git commit them to your local repository.
  • Share your changes with us via a pull request: git push your local changes to your GitHub fork, then go to GitHub make a pull request.

The Pandas project maintains an excellent Contributing Page that goes into detail on each of these steps and also provides great Contribution Guidelines. Also see GitHub's Set Up Git and Using Pull Requests.

We strongly recommend using virtual environments for development. Virtual environments make it trivial to switch between different versions of software. This Astropy Guide is a good reference for virtual environments. If this is your first pull request, don't worry about using a virtual environment.

You must include documentation for any new or improved code. We can provide help and advice on this after you start the pull request. See the documentation section below

When should I submit a pull request?

The short answer: anytime.

The long answer: it depends. If in doubt, go ahead and submit. You do not need to make all of your changes before creating a pull request. Your pull requests will automatically be updated when you commit new changes and push them to GitHub.

There are pros and cons to submitting incomplete pull-requests. On the plus side, it gives everybody an easy way to comment on the code and can make the process more efficient. On the minus side, it's easy for an incomplete pull request to grow into a multi-month saga that leaves everyone unhappy. If you submit an incomplete pull request, please be very clear about what you would like feedback on and what we should ignore. Alternatives to incomplete pull requests include creating a gist or experimental branch and linking to it in the corresponding issue.

The best way to ensure that a pull request will be reviewed and merged in a timely manner is to:

  • Start by creating an issue. The issue should be well-defined and actionable.
  • Ask the maintainers to tag the issue with the appropriate milestone.
  • Make a limited-scope pull request. It can be a lot of work to check all of the boxes in the recommended contribution guidelines especially for pull requests with a lot of new primary code.
  • Tag lori community members or @pvlib when the pull request is ready for review.

Code Style

Lori generally follows the the Python PEP8 code style. Maximum line length for code is 120 characters.
Additionally, the use of Black is aspired to ensure a consistent code style across the code base.

Remove any logging calls and print statements that you added during development. warning is ok.

Documentation

The use of descriptive docstrings for all lori functions, classes and class methods is mandatory.
Lori has adopted the [Google Docstring Style](https://google.github.io/styleguide/pyguide.html).

Writing code that is easy to understand is a key principle of lori. This is why it is not enough to write code with descriptive variable names and comments. All functions, classes and class methods must be documented with a docstring, similar to this google style example, which is rendered using the Sphinx Napoleon extension. These docstrings are used to automatically generate the lori documentation.

As such, they should form the basis of the documentation of the lori code base.

Building the documentation

Building the documentation locally is useful for testing out changes to the documentation's source code without having to repeatedly update a pull request and have Read the Docs (RTD) build it for you. For the RTD to be built correctly, a Graphviz needs to be accessible in the system path first.
Next, to build the docs locally requires installing lori as an editable library, including the doc dependencies specified in the project's setup configurations. An easy way to do this is with:

pip install lori[doc]    # on Mac:  pip install "lori[doc]"

Once the doc dependencies are installed, navigate to /doc and execute:

make html

Be sure to skim through the output of this command because Sphinx might emit helpful warnings about problems with the documentation source code. If the build succeeds, it will make a new directory doc/_build with the documentation's homepage located at _build/html/index.html. This file can be opened with a web browser to view the local version like any other website. Other output formats are available. Run make help for more information.

Note that Windows users need not have the make utility installed as lori includes a make.bat batch file that emulates its interface.