Contributing to PUDL

Welcome! We’re excited that you’re interested in contributing to the Public Utility Data Liberation effort!

We need lots of help with User feedback, we welcome Code contributions, and it would be great to Connect us with other organizations that we can work with.

Finally, financial donations are welcome too!

Code of Conduct

Please make sure you review our code of conduct, which is based on the Contributor Covenant. We want to make the PUDL project welcoming to contributors with different levels of experience and diverse personal backgrounds.

User feedback

PUDL’s goal is to help people use data to make change in the US energy landscape. As such, it’s critical that we understand our users’ needs! GitHub Discussions is our main forum for all this. Since it’s publicly readable, any conversation here can potentially benefit other users too!

We’d love it if you could:

  • Tell us what problems you’re running into, in the Help Me! discussion board

  • Tell us about what data you’re looking for by opening an issue

  • Tell us what you’re trying to do with PUDL data in this thread

  • File bug reports on Github.

  • Tell us what you’d like to see in PUDL in the Ideas discussion board

Code contributions


Already have a dataset in mind?

If you need data that’s not in PUDL, open an issue to tell us more about it!

If you’ve already spent a bunch of time wrangling a dataset, we welcome “knowledge contributions” in our pudl-knowledge repository!

If you’re looking to help us integrate a specific dataset into PUDL, find us at office hours and we can talk through next steps.

Your first contribution


You’ll need to fork this repository and get the dev environment set up.

Pick an issue

  • Look for issues with the good first issue tag in our Community Kanban Board. These are issues that don’t require a ton of PUDL-specific context, and are relatively tightly scoped.

  • Comment on the issue and tag @catalyst-cooperative/com-dev (our Community Development Team) to let us know you’re working on it. Feel free to ask any questions you might have!

  • Once you have an idea of how you want to tackle this issue, write out your plan so we can guide you around obstacles in your way! Post a comment outlining: * what steps have you broken this down into? * what is the output of each step? * how will one know that each step is working?

  • Once you’ve talked through your plan with someone from Catalyst, go forth and develop!

Work on it!

  • Make a branch on your fork and open a draft pull request (PR) early so we can discuss concrete code! Set the base branch to ``main``. Please don’t wait until it’s all polished up - it’s much easier for us to help you when we can see the code evolve over time.

  • Please make sure to write tests and documentation for your code - if you run into trouble with writing tests, let us know in the comments and we can help! We automatically run the test suite for all PRs, but some of those will have to be manually approved by Catalyst members for safety reasons.

  • Try to keep your changes relatively small: stuff happens, and one’s bandwidth for volunteer work can fluctuate frequently. If you make a bunch of small changes, it’s much easier to pause on a project without losing a ton of context. We try to keep PRs to less than 500 lines of code.

Get it merged in!

  • Turn the draft PR into a normal PR and tag @catalyst-cooperative/com-dev in a comment. We’ll try to get back to you within a few days - the smaller/simpler the PR, the faster we’ll be able to get back to you.

  • The reviewer will leave comments - if they request changes, address their concerns and re-request review.

  • There will probably be some back-and-forth until your PR is approved - this is normal and a sign of good communication on your part! Don’t be shy about asking us for updates and re-requesting review!

  • Don’t accidentally “start a review” when responding to comments! If this does happen, don’t forget to submit the review you’ve started so the other PR participants can see your comments (they are invisible to others if marked “Pending”).

Next contributions

Hooray! You made your first contribution! To find another issue to tackle, check out the Community Kanban board where we’ve picked out some issues that are

  • useful to work on

  • unlikely to become super time-sensitive

  • have some context, success criteria, and next steps information.

Pick one of these and follow the contribution flow above!

Connect us with other organizations

For PUDL to make a bigger impact, we need to find more people who need the data. Here’s how you can help:

  • Cite PUDL using DOIs from Zenodo if you use the software or data in your own published work.

  • Point us toward appropriate grant funding opportunities and meetings where we might present our work.

  • Point us at interesting publications related to open energy data, open source energy system modeling, how energy policy can be affected by better data, or open source tools we should check out.

  • Share your Jupyter notebooks and other analyses that use PUDL.

  • Hire Catalyst to do analysis for your organization using the PUDL data – contract work helps us self-fund ongoing open source development.