Skip to content

Issue Triaging and Prioritization Guide

This document outlines our approach to triaging issues on GitHub, including guidelines for labeling and resolving issues, and best practices for maintaining a well-organized, prioritized, and up-to-date issue tracker via the earthaccess GitHub Project.

We hope that this guide will help empower anyone to contribute to issue triaging, and address a common question for contributors: "I'm interested in working on the highest priority issues that will solve important problems facing the earthaccess community. Where do I begin?"

Issue Lifecycle

  1. A new issue 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:
  3. Determine whether the issue should be worked or not. If yes, move to "Backlog" status, otherwise close as not planned.
  4. Add or adjust issue labels.
  5. Add an issue prioritization.
  6. Respond and follow up as needed (i.e. tagging relevant earthaccess maintainers for further support).
  7. Issues are reviewed and groomed using the earthaccess GitHub Project
  8. An issue is worked following the Pull Request (PR) Guide.
  9. Assign the issue to the implementer.
  10. Update status to In Progress.
  11. Link the issue to the related PR with a comment "Resolves #N" (N is the issue number). The issue will auto-close when the PR is merged.
  12. If the previous step is missed, link any related PRs before manually closing an issue.

Details on each of these workflow steps are provided below.

Moving an issue to Backlog status

Project status

By default, all new issues are created without a project status. Issues without a status are listed in the Needs Triage project view. Statuses include:

  • Backlog
  • In Progress
  • 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 project view into its relevant backlog view depending on issue type. See below for more details on these other project views.

When to "Close as not planned"?

Close issues as "not planned" when:

  • An issue is not aligned with the project's goals or priorities.
  • An issue is not feasible to be addressed due to technical or resource constraints.
  • An issue is a duplicate of an existing issue that has already been addressed.

When closing an issue as not planned:

  • Provide a clear explanation as to why the issue is not planned or feasible.
  • Offer alternative solutions or workarounds, if possible.
  • Link to relevant documentation or resources, if applicable.
  • Add the type: will not do label.

Labeling Issues

When labeling an issue, choose the label(s) that best describes the issue. Using labels consistently and accurately ensures that issues are trackable and searchable.

Issue Types

  • type: bug: Use for issues that identify bugs causing incorrect or unexpected behavior. This label is applied automatically if the Bug template is used.
  • type: decision record: Use this label for issues and PR's that address a new decision record document (e.g. https://github.com/earthaccess-dev/earthaccess/pull/1047).
  • type: duplicate: Use this label for issues that are duplicates of existing ones.
  • type: enhancement: Use this label for requests for new features or improvements to existing functionalities.
  • type: experience report: Use this label for issues that describe a firsthand usability experience.
  • type: metrics: This label is automatically applied upon creation of the Monthly metrics issue. See the Monthly issue metrics action for more details.
  • type: will not do: Use this label for issues that won’t be addressed or fixed.

Impact labels

These labels describe what portion of the project they affect:

  • impact: breaking: Issues that break our public API.
  • impact: core: Issues that affect the core Python codebase.
  • impact: dependencies: Use this label for issues concerning dependencies.
  • impact: documentation: Use this label for issues related to documentation.
  • impact: automation: Use this label for issues related to the CI/CD pipeline or automation.
  • impact: governance: Issues that impact the project's governance or decision-making process.

Impact labels are also used to help group related issues based on a particular feature or topic. For example, impact: virtual-datasets is used to categorize Issues or Discussions related to virtualizarr integration and support. These labels may evolve over time as new features are worked.

Needs labels

  • 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.

Special labels

  • good first issue: Use this label for issues that are suitable for new contributors. These issues are designed to be approachable and not overly complex, making them an ideal starting point for those looking to contribute to the project.

Linking Labels in GitHub Markdown

When referencing a label in a GitHub issue or discussion, it will be useful to link to the label page to provide additional context and help other members to quickly understand the issue's category.

Syntax

To link to a label in GitHub Markdown, copy-and-paste the URL to the label by right-clicking any label and selecting "Copy Link". Then, paste that label in a GitHub issue, PR, discussion, or Markdown document:

https://github.com/username/repository/labels/label-name

Example

For example, to link to the "good first issue" label in the earthaccess-dev/earthaccess repository, you would use the URL:

https://github.com/earthaccess-dev/earthaccess/labels/good%20first%20issue

Issue Prioritization

Issue priorities are surfaced within the Bug Priority and Docs project views. When triaging a new issue, select a priority based on the user impact and urgency. The following guidelines apply broadly across issue types, with additional notes for bugs and documentation issues.

Priority: 1 - Critical

The issue has significant, immediate impact on users and/or major components of the earthaccess library.

  • Core functionality is broken or inaccessible for a meaningful number of users
  • Key workflows or use cases are blocked
  • Users are likely to stop using the library or lose trust in it

Bug example: Users cannot search or access data for a significant number of collections or key earthaccess workflows.

Documentation example: Content is incorrect or missing in a way that would immediately block or mislead a user.

Priority: 2 - Important

The issue has real impact but is not immediately blocking a majority of users.

  • Affects primary user workflows but a workaround exists, or only a subset of users is affected
  • Incorrect or confusing content that degrades the experience without fully blocking users
  • Less common use cases or data collections are impacted

Bug example: Functionality is degraded but users can still accomplish their goals.

Documentation example: A Tutorial or secondary documentation is broken or unclear; contributing docs with significant usability issues.

Priority: 3 - Nice to have

The issue is a real improvement but not urgent.

  • Affects a small percentage of users, data collections, or use cases
  • Polish, enhancements, or "nice to haves" with no meaningful workflow impact
  • Minor inconsistencies or style issues

Bug example: Affects a small number of users, data collections, or edge-case workflows; a workaround is readily available or the impact is cosmetic.

Documentation example: Minor inconsistencies, typos, or style issues; improvements to contributing or developer-facing docs with no impact on end-user workflows.

Notes for Triagers

  • When in doubt, start at Medium and adjust based on community feedback or additional context.
  • The User Guide and API Reference generally warrant higher priority than contributing or developer docs when impact is otherwise similar.
  • Priority reflects impact and urgency, not effort — a quick fix can still be High priority.

Issue Triaging Workflow


flowchart TD
  %%{init: {"flowchart": {"htmlLabels": false}} }%%
  classDef default font-size:32pt;
  start{"`Followed
  issue
  template?`"}
  start ==NO==> close1[Request needed information from reporter and update issue on behalf of reporter]
  start == YES ==> dupe{Is duplicate?}
  dupe == YES ==> close2[Close and point to duplicate]
  dupe == NO ==> repro{Has proper reproduction?}
  repro == NO ==> close3[Label: 'needs reproduction' bot will auto close if no update has been made in 3 days]
  repro == YES ==> real{Is actually a bug?}
  real == NO ==> intended{Is the intended behaviour?}
  intended == YES ==> explain[Explain and close point to docs if needed]
  intended == NO ==> open[Keep open for discussion Remove 'pending triage' label]
  real == YES ==> real2["Confirm that 'Bug' label was automatically added as part of the Bug Issue template, otherwise add 'Bug' label."]


  %% Link Color %%
    linkStyle default stroke:black,stroke-width:2px,font-size:24pt;

Discussions vs Issues

TODO Move to https://earthaccess.readthedocs.io/en/latest/contributor/ ?

This section would cover the guidelines for when to use discussions versus issues, and how to migrate between them.

What are Discussions?

Discussions are used for:

  • Brainstorming and idea generation.
  • Project feedback.
  • General questions and topics.

What are Issues?

Issues are used for:

  • Reporting bugs and errors.
  • Tracking progress on specific tasks or projects.
  • Requesting changes or improvements.

When to Migrate

Use your best judgement when migrating between issues and discussions. Sometimes it makes more sense to open a new issue or discussion instead of migrating, for example when there are many things being discussed, but we want to create an issue or task out of just one of those things.

Migrate a discussion to an issue when:

  • A specific task is identified.
  • A bug or error is reported.
  • A change or improvement is requested.

Migrate an issue to a discussion when:

  • 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.