Contributing to PUDL#
Welcome! We’re excited that you’re interested in contributing to the Public Utility Data Liberation effort! The work is currently being coordinated by the members of the Catalyst Cooperative. PUDL is meant to serve a wide variety of public interests including academic research, climate advocacy, data journalism, and public policy making. This open source project has been supported by a combination of volunteer contributions, grant funding from the Alfred P. Sloan Foundation, and reinvestment of net income from the cooperative’s client projects.
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.
How to Get Involved#
We welcome just about any kind of contribution to the project. Alone, we’ll never be able to understand every use case or integrate all the available data. The project will serve the community better if other folks get involved.
There are lots of ways to contribute – it’s not all about code!
If you need help, someone else might need it too - ask for help in Github Discussions and maybe the ensuing discussion will be useful to other people too!
Suggest new data and features that would be useful.
File bug reports on Github.
Help expand and improve the documentation, or create new example notebooks
Help us create more and better software test cases.
Give us feedback on overall usability using GitHub Discussions – what’s confusing?
Tell us a story about how you’re using of the data.
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.
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.
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.
Contribute code via pull requests. See the developer setup for more details.
And of course… we also appreciate financial contributions.
Development Setup for instructions on how to set up the PUDL development environment.
Find us on GitHub#
Github is the primary platform we use to manage the project, integrate contributions, write and publish documentation, answer user questions, automate testing & deployment, etc. Signing up for a GitHub account (even if you don’t intend to write code) will allow you to participate in online discussions and track projects that you’re interested in.
Asking (and answering) questions is a valuable contribution! As noted in How to support open-source software and stay sane, it’s much more efficient to ask and answer questions in a public forum because then other users and contributors who are having the same problem can find answers without having to re-ask the same question. The forum we’re using is our Github discussions.
Even if you feel like you have a basic question, we want you to feel comfortable asking for help in public – we (Catalyst) only recently came to this data work from being activists and policy wonks – so it’s easy for us to remember when it all seemed frustrating and alien! Sometimes it still does. We want people to use the software and data to do good things in the world. We want you to be able to access it. Using a public forum also enables the community of users to help each other!
Don’t hesitate to post a discussion with a feature request, a pointer to energy data that needs liberating, or a reference to documentation that’s out of date, unclear, or missing. Understanding how people are using the software, and how they would like to be using the software, is very valuable and will help us make it more useful and usable.
Our design process#
We do our technical design out in the open, so that community members can weigh in. Here’s the process we usually follow:
Someone has a problem they’d like to solve. They post in the Ideas forum with their problem and some context.
When the open questions are answered, we create an issue from the discussion, which holds the conclusions of the discussion.