Updates to triaging guide: Issue prioritization and high-level triage workflow by asteiker · Pull Request #1308 · earthaccess-dev/earthaccess

asteiker · 2026-04-20T20:26:06Z

Description

Related to #1070 and based on recent discussions at the Collab cafe with @saberbrasher on incorporating prioritization best practices, GitHub project management, and overall triaging workflow into the Triaging Guide.

Note that this is a draft PR that still needs formatting review, and overall content review. I have not yet reviewed the Triaging workflow diagram which may also benefit from updates.

Other TODOs:

Add more content around the GH Project usage in general. (I have not included an overview of all project views and their intended purpose.
Review Issues vs Discussion section.
Update Bug project view to include prioritization column.

"Ready for review" checklist

Place this Pull Request (PR) in draft until it is ready for review (see below)
Please review our Pull Request Guide
Mark "ready for review" after following instructions in the guide

Merge checklist

PR title is descriptive
PR body contains links to related and resolved issues (e.g. closes #1)
If needed, CHANGELOG.md updated
If needed, docs and/or README.md updated
If needed, unit tests added (unsure how? see below!)
All checks passing (tip: comment pre-commit.ci autofix if pre-commit is failing)
At least one approval

📚 Documentation preview 📚: https://earthaccess--1308.org.readthedocs.build/en/1308/

github-actions · 2026-04-20T20:26:17Z

👈 Launch a binder notebook on this branch for commit b5c4f68

I will automatically update this comment whenever this PR is modified

👈 Launch a binder notebook on this branch for commit 6d9e0d5

👈 Launch a binder notebook on this branch for commit 420fd25

👈 Launch a binder notebook on this branch for commit 6e5ce75

👈 Launch a binder notebook on this branch for commit 0ef563d

👈 Launch a binder notebook on this branch for commit f200646

👈 Launch a binder notebook on this branch for commit 1aff0da

👈 Launch a binder notebook on this branch for commit 4bb4454

👈 Launch a binder notebook on this branch for commit 7e0512a

👈 Launch a binder notebook on this branch for commit dd8c8a9

👈 Launch a binder notebook on this branch for commit 64e87fb

👈 Launch a binder notebook on this branch for commit 6fa0d59

👈 Launch a binder notebook on this branch for commit 6baeaad

mfisher87 · 2026-04-21T18:33:41Z

+   * Add or adjust issue labels.
+   * Add an issue prioritization. 
+   * Respond and follow up as needed (i.e. tagging relevant earthaccess maintainers for further support).
+3. Issues are reviewed and groomed using the `earthaccess` [GitHub Project](https://github.com/orgs/earthaccess-dev/projects/1)


Needs accountability -- when / by whom? Without a person responsible or a cadence/habit of doing it together, it won't get done :)

@mfisher87 Absolutely.

I want any contributor to feel comfortable reviewing a new issue and doing all of these things. And at the same time, as you're raising, if we're not expecting this from a particular role or on a particular cadence, then I agree it will happen inconsistently (which is the case today). I would love to hold the community manager role accountable as the primary triager. Ideally I'd like to get in the habit of doing this at the collab cafe. Putting this in writing will empower me to play a more active role in this. And then in addition, we can open this up to any contributor who sees gaps in any/all of these steps within a given issue. What do you think about this?

I think this sounds great 😁 Thanks for being an awesome community manager, Amy!

Sounds great, Amy.

mfisher87 · 2026-04-21T18:59:39Z

- Link to relevant documentation or resources, if applicable.

 ## Discussions vs Issues
+TODO Move to https://earthaccess.readthedocs.io/en/latest/contributor/ ?


I do think this should move, but I'm not sure where this should go. This is part of the contributor funnel, IMO, not necessarily for people who are already contributors. So we might want this to be in the user guide in a dedicated page about "How to report a problem or make a suggestion"? I dunno :)

"How to migrate between them" probably should stay here.

Yep, I had the same thought on keeping the migrating instructions here. I like the idea of a separate page. We have a nice list of other engagement venues on https://earthaccess.readthedocs.io/en/latest/contributor/ so that also makes me wonder if all of that content should move out. Hmm.

Good point. I think "When contributing we recommend:" should stay, but probably "Then, you can:" should move out to a dedicated "entry-point". Or be copied so it's in both places. But then we have to sync them.

I've been thinking about this for GeoJupyter and started work on it. I love the idea of a menu-like experience for people looking to get in to contributing. E.g. something like these

https://openscapes.org/resources

https://antennapod.org/contribute/

The WIP for GJ is here: geojupyter/geojupyter.org#127

Maybe for earthaccess we add a "contributing menu" and link to it on this page so we don't have to duplicate anything https://earthaccess.readthedocs.io/en/latest/contributor/

Agree that the Discussions vs. Issues content could/ should move... in the short term, I lean toward maybe just expanding a bit on what is present on this page https://earthaccess.readthedocs.io/en/latest/contributor/ assuming that is the first page someone who is on the fence about contributing would go to. Not sure what the best long term solution is, though!

mfisher87 · 2026-04-21T19:00:39Z

Nice work! 🤩

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

mfisher87 · 2026-04-23T02:12:05Z

@asteiker just in case you didn't see them, many of my comments are hidden because I did too many 🫣

saberbrasher

Awesome work on this @asteiker and @mfisher87 !! I have a few comments/ questions, but you two definitely did the heavy lifting.

saberbrasher · 2026-04-23T19:17:10Z

+
+1. A [new issue](https://github.com/earthaccess-dev/earthaccess/issues/new/choose) is created, either using a pre-existing template, or as a blank issue.
+2. The issue is triaged by a community member in order to: 
+   * Determine whether the issue should be worked or not. If yes, move to "Backlog" status, otherwise close as not planned.


Not sure if my docs preview is outdated or if markdown does not like the * bullet, but these are showing up as numbers to me. I like the idea of the * ones being bullets of #2, though!

shakes fist at mkdocs

I seriously don't like mkdocs. It doesn't do anything the way I expect from working with other markdown tools. Why not just do it the normal way!

Suggested change

* Determine whether the issue should be worked or not. If yes, move to "Backlog" status, otherwise close as not planned.

* Determine whether the issue should be worked or not. If yes, move to "Backlog" status, otherwise close as not planned.

I think we need both a blank line and exactly 4 spaces. 😩 https://squidfunk.github.io/mkdocs-material/reference/lists/#usage

saberbrasher · 2026-04-23T19:19:15Z

+   * Add or adjust issue labels.
+   * Add an issue prioritization. 
+   * Respond and follow up as needed (i.e. tagging relevant earthaccess maintainers for further support).
+3. Issues are reviewed and groomed using the `earthaccess` [GitHub Project](https://github.com/orgs/earthaccess-dev/projects/1)


Sounds great, Amy.

saberbrasher · 2026-04-23T19:33:39Z

+Details on each of these workflow steps are provided below. 
+
+
+## Moving an issue to Backlog status


Maybe this header should be something more along the lines of the main steps abbreviated above? So something like:

A new issue is created

which then feeds into Matt's point below about how you want to first acknowledge receipt of the issue (and show gratitude).

And we could probably also mention the status of the issue when it's first created (i.e. no status) in this section. This motivates the next section!

saberbrasher · 2026-04-23T19:34:47Z

+- In Review
+- Done
+
+When triaging a new issue, review the information and provide a response or follow up with question(s) if needed. Providing gratitude for the submission as a text or emoji response is highly encouraged. Move the issue to the Backlog unless it ought to be closed as "not planned", as outlined below. If you are unsure, add the **needs: triage** label. On the righthand side of the issue page, the "Projects" section contains an `earthaccess` project box. Click "no status" to select the status options. Select "Backlog". This will move the project out of the [Needs Triage](https://github.com/orgs/earthaccess-dev/projects/1/views/3) project view into its relevant backlog view depending on issue type. See below for more details on these other project views. 


Yeah, the first two bullets could be earlier in this process... and then the third one makes sense under a "project status" sub-header.

saberbrasher · 2026-04-23T19:39:57Z

 - **needs: decision**: We're struggling to decide what to do and the decision committee needs to help.
 - **needs: feedback**:  Use this label for issues where feedback is requested from the team or our community.
 - **needs: help**: Use this label for issues where additional help or contributions are needed.
+- **needs: triage**: Use this label for new issues that require additional information to determine whether it should move to the backlog, or close as not planned. 


Is it confusing that issues without a status auto go to the "needs triage" section of the project page, but then this label does not get auto applied if one is not selected when an issue is created?

I think we can ditch this label entirely, the "No status" status is an indicator for that already!

Otherwise we can set up our issue templates to auto-apply this label.

saberbrasher · 2026-04-23T19:46:42Z

- The issue is a nebulous idea that needs to be workshopped before it can be implemented.
- The issue is a general question or topic.
- The issue is not specific or actionable.
+- **When in doubt, start at Medium** and adjust based on community feedback or additional context.


By Medium do you mean 2 - Important?

saberbrasher · 2026-04-23T19:51:58Z

- Link to relevant documentation or resources, if applicable.

 ## Discussions vs Issues
+TODO Move to https://earthaccess.readthedocs.io/en/latest/contributor/ ?


Agree that the Discussions vs. Issues content could/ should move... in the short term, I lean toward maybe just expanding a bit on what is present on this page https://earthaccess.readthedocs.io/en/latest/contributor/ assuming that is the first page someone who is on the fence about contributing would go to. Not sure what the best long term solution is, though!

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

asteiker added 9 commits April 6, 2026 15:22

update goal and scope

e25c68c

add tip callout

66cd0f6

draft updated outline

e25e557

update broken link

5d97781

add issue lifecycle outlne

e7935bd

issue prioritization outline

990c5bc

update triage workflow and labels

dd4b9a4

update label section

7092656

add prioritization section

b5c4f68

asteiker requested a review from saberbrasher April 20, 2026 20:26

mfisher87 reviewed Apr 21, 2026

View reviewed changes

asteiker and others added 8 commits April 22, 2026 17:18

Update docs/contributor/triaging.md

6d9e0d5

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

420fd25

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

6e5ce75

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

0ef563d

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

f200646

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

1aff0da

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

4bb4454

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

7e0512a

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

saberbrasher reviewed Apr 23, 2026

View reviewed changes

asteiker and others added 4 commits May 18, 2026 08:53

Update docs/contributor/triaging.md

dd8c8a9

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

64e87fb

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

6fa0d59

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/contributor/triaging.md

6baeaad

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

	* Determine whether the issue should be worked or not. If yes, move to "Backlog" status, otherwise close as not planned.

	* Determine whether the issue should be worked or not. If yes, move to "Backlog" status, otherwise close as not planned.

		Details on each of these workflow steps are provided below.


		## Moving an issue to Backlog status

Conversation

asteiker commented Apr 20, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

"Ready for review" checklist

Merge checklist

Uh oh!

github-actions Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 commented Apr 21, 2026

Uh oh!

mfisher87 commented Apr 23, 2026

Uh oh!

saberbrasher left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

A new issue is created

Uh oh!

mfisher87 Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

asteiker commented Apr 20, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Apr 20, 2026 •

edited

Loading

mfisher87 Apr 23, 2026 •

edited

Loading

mfisher87 Apr 23, 2026 •

edited

Loading

mfisher87 Apr 23, 2026 •

edited

Loading

mfisher87 Apr 23, 2026 •

edited

Loading