-
-
Notifications
You must be signed in to change notification settings - Fork 119
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Reorganize contributing docs + add process description.
- Loading branch information
Showing
1 changed file
with
82 additions
and
68 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -20,93 +20,107 @@ 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 several areas in which we would welcome your help! Many of these | ||
| require a GitHub account, since that is where we manage the project. `Signing | ||
| up for a GitHub account <https://github.com/join>`__ (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. | ||
|
|
||
| There are lots of ways to contribute -- it's not all about code! | ||
| First is *user feedback* - if you use PUDL, we would love to talk to you and | ||
| understand what your use cases and problems are. This helps us steer the | ||
| project towards greater usefulness! Here are some avenues to get in touch: | ||
|
|
||
| * If you need help, someone else might need it too - ask for help in `Github | ||
| Discussions | ||
| <https://github.com/orgs/catalyst-cooperative/discussions/categories/help-me>`__ | ||
| and maybe the ensuing discussion will be useful to other people too! | ||
| * `Suggest new data and features <https://github.com/catalyst-cooperative/pudl/issues/new?template=feature_request.md>`__ that would be useful. | ||
| * `File bug reports <https://github.com/catalyst-cooperative/pudl/issues/new?template=bug_report.md>`__ on Github. | ||
| * Help expand and improve the documentation, or create new | ||
| `example notebooks <https://github.com/catalyst-cooperative/pudl-examples/>`__ | ||
| * Help us create more and better software :doc:`test cases <dev/testing>`. | ||
| * Give us feedback on overall usability using `GitHub Discussions | ||
| <https://github.com/orgs/catalyst-cooperative/discussions/categories/ideas>`__ | ||
| -- 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 <https://zenodo.org/communities/catalyst-cooperative/>`__ | ||
| if you use the software or data in your own published work. | ||
| * Suggest new features, dataset integrations, structural changes, or just give | ||
| us feedback on overall usability using `GitHub Discussions | ||
| <https://github.com/orgs/catalyst-cooperative/discussions/categories/ideas>`__. | ||
| * If something went wrong, `file a bug report | ||
| <https://github.com/catalyst-cooperative/pudl/issues/new?template=bug_report.md>`__ | ||
| on Github. | ||
|
|
||
| * Help us plan the future of PUDL by telling us what you're using it for! | ||
| [email protected] works great to get in touch. | ||
|
|
||
| Second is *networking/growth* - for PUDL to be a go-to source of public | ||
| information about the US energy system, and help advocates with the clean | ||
| energy transition, we need to grow our community and business. Here's how you | ||
| can help: | ||
|
|
||
| * Cite PUDL using `DOIs from Zenodo | ||
| <https://zenodo.org/communities/catalyst-cooperative/>`__ 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 <https://catalyst.coop/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 <https://help.github.com/en/articles/about-pull-requests>`__. | ||
| See the :doc:`developer setup <dev/dev_setup>` for more details. | ||
| * And of course... we also appreciate | ||
| `financial contributions <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=PZBZDFNKBJW5E&source=url>`__. | ||
| * And of course... we also appreciate `financial contributions | ||
| <https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=PZBZDFNKBJW5E&source=url>`__. | ||
|
|
||
| .. seealso:: | ||
| Third is *direct contributions to the technical system* - code and | ||
| documentation! This is the most hands-on, in-the-weeds way to contribute, and | ||
| obviously helps us make the whole system more capable! | ||
|
|
||
| * :doc:`dev/dev_setup` for instructions on how to set up the PUDL | ||
| development environment. | ||
| * Check out the `Code contribution process`_ section below for a process | ||
| overview. | ||
| * See the :doc:`developer setup <dev/dev_setup>` for technical details | ||
| * We also welcome documentation updates, which follow the general code | ||
| contribution process! | ||
|
|
||
| ------------------------------------------------------------------------------- | ||
| 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 <https://github.com/join>`__ | ||
| (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 | ||
| <https://www.nature.com/articles/d41586-019-02046-0>`__, 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 | ||
| <https://github.com/catalyst-cooperative/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 | ||
| <https://github.com/catalyst-cooperative/discussions/categories/ideas>`__, | ||
| 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 | ||
| Code contribution process | ||
| ------------------------------------------------------------------------------- | ||
|
|
||
| We do our technical design out in the open, so that community members can weigh | ||
| in. Here's the process we usually follow: | ||
| Our goals for you are: | ||
|
|
||
| * contribute to something important | ||
| * not accidentally end up on the critical path for a time-sensitive task and | ||
| end up working a second shift to finish something | ||
| * not flounder in a sea of high-context tasks | ||
|
|
||
| To support this, we've set up a `GitHub Projects view | ||
| <https://github.com/orgs/catalyst-cooperative/projects/9/views/19>`__ which we | ||
| update on a rolling basis. It includes a handful of tasks that are: | ||
|
|
||
| * important and non-urgent | ||
| * clearly scoped | ||
| * owned by a Catalyst employee who can be your buddy | ||
|
|
||
| If you have an idea for some work you'd like to do that's not on the board, you | ||
| should absolutely find/create a new issue or post a Github Discussion - then we | ||
| can talk about how Catalyst can support that work! | ||
|
|
||
| We envision a flow like this: | ||
|
|
||
| 1. You go to the GitHub Projects "community" view and poke around at the | ||
| backlog until you find something you find interesting. | ||
| 2. You ask some questions about the scope and we attempt to clarify what needs | ||
| doing. | ||
| 3. If you still want to take the task on, assign the issue to yourself and | ||
| you're off to the races! We'll probably bother you for updates occasionally. | ||
| 4. You put up an early draft PR for feedback. | ||
| 5. Eventually, you convert the draft to a standard PR, we do a thorough review, | ||
| and it gets merged! Go back to #1. | ||
|
|
||
| Some guidelines: | ||
|
|
||
| 1. Someone has a problem they'd like to solve. They post in the `Ideas | ||
| <https://github.com/orgs/catalyst-cooperative/discussions/categories/ideas>`__ | ||
| forum with their problem and some context. | ||
| * small PRs: we understand that stuff happens, and one's bandwidth for | ||
| volunteer work can fluctuate frequently. One way to make that feel a little | ||
| better for both the contributor and the project is to ship many small | ||
| changes, so there's never a ton of dangling work. | ||
|
|
||
| 2. Discussion ensues. | ||
| * early drafts: our system has evolved over several years and can be quite | ||
| confusing. Pushing up an early draft PR will help Catalyst members guide you | ||
| gently away from pitfalls. | ||
|
|
||
| 3. When the open questions are answered, we create an issue from the discussion, | ||
| which holds the conclusions of the discussion. | ||
| * write tests and documentation: this is critical for expressing what | ||
| the software "should" do, which is helpful both in development and in | ||
| maintenance. If you haven't done much of this before, we can help! | ||