@@ -12,7 +12,40 @@ Overview
1212-------------------------------------------------------------------------------
1313
1414This 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-------------------------------------------------------------------------------
1851Guidelines 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