The people working on PUDL are distributed all over North America. Collaboration takes place online. We make extensive use of Github’s build int project management tools and we work in public. You can follow our progress in our GitHub Projects
Issues and Project Tracking#
We use Github issues to track bugs, enhancements, support requests, and just about any other work that goes into the project. Try to make sure that issues have informative tags so we can find them easily.
Our GitHub Workflow#
We have 3 persistent branches:
main(the default branch),
We create temporary feature branches off of
mainand make pull requests into
mainthroughout our 2 week long sprints. All code that’s merged into
mainshould have passed our CI tests and been reviewed by at least one other person.
Every night the
mainbranch is used to run the Nightly Data Builds. If the builds are successful, then the
nightlybranch is automatically updated to point to the latest commit on
main. If the builds fail, then the
nightlybranch is left unchanged.
Every time we do a versioned data release, the
stablebranch is updated to point to the commit associated with the most recent release.
Before making a PR, make sure the tests run and pass locally, including the code linters and pre-commit hooks. See Set Up Code Linting for details.
Don’t forget to merge any new commits to the
mainbranch into your feature branch before making a PR.
If for some reason the continuous integration tests fail for your PR, try and figure out why and fix it, or ask for help. If the tests fail, we don’t want to merge it into
main. You can see the status of the CI builds in the GitHub Actions for the PUDL repo.
Please don’t decrease the overall test coverage – if you introduce new code, it also needs to be exercised by the tests. See Testing PUDL for details.
Write good docstrings using the Google format
Pull Requests should update the documentation to reflect changes to the code, especially if it changes something user-facing, like how one of the command line scripts works.
The PUDL data processing pipeline isn’t intended to be used as a library that other Python packages depend on. Rather, it’s an end-use application that produces data which other applications and analyses can consume. Because of this, we no longer release installable packages on PyPI or
Periodically, we tag a versioned release on
mainusing a calendar based version, like
v2023.07.15. This triggers a snapshot of the repository being archived on Zenodo.
We don’t (yet) have funding to do user support, so it’s currently all community and volunteer based. In order to ensure that others can find the answers to questions that have already been asked, we try to do all support in public using Github Discussions.