Skip to content

Commit

Permalink
Reorganize contributing docs + add process description.
Browse files Browse the repository at this point in the history
  • Loading branch information
@jdangerx
jdangerx committed Nov 28, 2023
1 parent 45d9356 commit 3b6486d
Showing 1 changed file with 82 additions and 68 deletions.
150 changes: 82 additions & 68 deletions docs/CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!
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
<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!

0 comments on commit 3b6486d

Please sign in to comment.