Skip to content

Commit e47a4c8

Browse files
authored
Add good first issue dev docs (#5300)
1 parent b659747 commit e47a4c8

1 file changed

Lines changed: 34 additions & 6 deletions

File tree

docs/dev/managing_external_contributions.rst

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,40 @@ Overview
1212
-------------------------------------------------------------------------------
1313

1414
This document outlines norms, practical tips, and expectations for internal
15-
Catalyst developers reviewing external community contributions.
15+
Catalyst developers supporting external community contributions.
16+
17+
-------------------------------------------------------------------------------
18+
Creating 'good first issues'
19+
-------------------------------------------------------------------------------
20+
21+
The 'good first issue' label on a Github issue is used to identify issues well-suited
22+
for first-time contributors to the PUDL repository. Issues with this label are
23+
compiled by Github into a `contribution page <https://github.com/catalyst-cooperative/pudl/contribute>`__,
24+
indexed on sites such as `Climate Triage <https://climatetriage.com/>`__.
25+
26+
To be a truly good first issue, an issue should:
27+
28+
* be a small discrete task with clear checkpoints and well-defined outcomes
29+
(e.g., create one new core table, not 'integrate this dataset').
30+
* be low context: the issue should not touch multiple complex parts of the
31+
code (e.g., harvesting) or require knowledge of existing bespoke workarounds in
32+
our code.
33+
* be relatively easy to test and review. Relatedly, the issue should have
34+
constrained downstream impacts: e.g., a change to the I/O manager we use for all
35+
tables is probably not a great good first issue.
36+
* have a clear implementation solution in mind: while soliciting external feedback on
37+
implementation design can be useful, an issue which requires us to do further research
38+
and decide what to do, or to weigh different options as a team is a poor choice for a
39+
good first issue.
40+
* have a satisfying outcome - a new table, a bug fix, a performance improvement!
41+
We value our contributor's time and want them to get to work on exciting stuff,
42+
not chores.
43+
* have no active blockers: while you can write up an issue to be an eventual good first
44+
issue, you should avoid applying the label until the blocking issue is resolved.
45+
* not be highly time sensitive: data updates, breaking issues, and other tasks
46+
that need to happen on a predictable timeline are best handled by Catalyst developers.
47+
48+
To create a good first issue, use the issue template on Github to get started!
1649

1750
-------------------------------------------------------------------------------
1851
Guidelines for contributor review
@@ -228,8 +261,3 @@ To push your local branch directly to a contributor's PR, run the following:
228261
# If you have a different local branch name from the remote, it
229262
# should instead look like this
230263
git push user-name local-branch-name:remote-branch-name
231-
232-
233-
.. todo::
234-
235-
* Add good first issue norms and template information once established.

0 commit comments

Comments
 (0)