From cfa8eb4f34ed06e099817c51942801ecabbb500d Mon Sep 17 00:00:00 2001 From: Dazhong Xia Date: Sat, 11 Nov 2023 12:56:31 -0500 Subject: [PATCH] Reorganize contributing docs + add process description. --- docs/CONTRIBUTING.rst | 150 +++++++++++++++++++++++------------------- 1 file changed, 82 insertions(+), 68 deletions(-) diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst index 9e5bffc4c3..616e3d0149 100644 --- a/docs/CONTRIBUTING.rst +++ b/docs/CONTRIBUTING.rst @@ -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 `__ (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 `__ 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 :doc:`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. +* Suggest new features, dataset integrations, structural changes, or just give + us feedback on overall usability using `GitHub Discussions + `__. +* If something went wrong, `file a bug report + `__ + on Github. + +* Help us plan the future of PUDL by telling us what you're using it for! + hello@catalyst.coop 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 + `__ 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. -* Contribute code via - `pull requests `__. - See the :doc:`developer setup ` for more details. -* And of course... we also appreciate - `financial contributions `__. +* And of course... we also appreciate `financial contributions + `__. -.. 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 ` 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 `__ -(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 +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 +`__ 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 - `__ - 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!