Skip to content

Reorganize and improve uxarray contributor's guide #1831

Open

Description

@Sevans711

Right now the contributor's guide (https://uxarray.readthedocs.io/en/latest/contributing.html) is long, a bit outdated in some parts, and (in my personal opinion at least) somewhat overwhelming, partly due to lacking a clear narrative structure.

The text structure is currently:

  • (1) overview
    • (1.1) many ways to contribute to uxarray
    • (1.2) about this guide
    • (1.3) links to project-specific resources
  • (2) Configuring github and setting up python environment
    • (2.1) setting up git
    • (2.2) setting up python
  • (3) "How uxarray uses github"
    • (3.1) options for selecting an issue to work on or posting a new issue
    • (3.2) should you fork, or should you clone locally instead?
    • (3.3) configure conda environment
    • (3.4) setting up pre-commit hooks
    • (3.5) use feature branches
    • (3.6) local development process, and pushes
    • (3.7) pull requests
      • (3.7.1) link PR to issue
      • (3.7.2) review your changes
      • (3.7.3) common elements of pull requests
        • (3.7.3.1) unit tests: "do not use pytest inside your test scripts"
        • (3.7.3.2) docstrings
        • (3.7.3.3) documentation
        • (3.7.3.4) usage examples
      • (3.7.4) after you open the pull request
        • (3.7.4.1) addressing reviews
        • (3.7.4.2) github actions checks

I would propose changing uxarray's guide to the following structure instead:

  1. "Overview" which is not broken into 3 subsections, and does not include possible issues you might want to solve (the current 1.1). It should include some project-specific links (the current 1.3) but these links need to be updated (e.g., most/all(?) Milestones are not being actively used right now).
  2. "Where to start", including issues you might want to solve (combining the current 3.1 with the current 1.1), and details about where to report issues / request new features. Drop detailed explanation about issue labels. Clarify to wait a little bit for someone to "assign" an issue to you; don't ask people to self-assign.
  3. Primer on github and version control (the current 2.1)
  4. Clear description of the development workflow, assuming you have already picked an issue to work on. Combine the current 3.2 (but focus only on how to fork, and just briefly mention that regular contributors might choose to clone directly instead), 3.3, 3.4, 3.5, 3.6, and top of 3.7 (which explains how to open a PR). Finish with the current 3.7.1 and 3.7.2 (probably combined into a single subsection) and 3.7.4 (probably not splitting across subsections), which explain the last stages of opening a PR and the PR review process.
  5. Details about contribution style / guides; this is the current 3.7.3 and its subsections.

This provides a clearer narrative: (1) start with a quick overview of links, (2) figure out what part of the project you might want to contribute to, (3) learn a bit about git/github, then (4) follow a clear workflow to develop and contribute. And, finally, (5) provides some extra details about the contribution style and some guides for the contribution itself.

Finally, I would also propose a few miscellaneous improvements/fixes:

  1. Fix the instructions in (3.7.3.1); uxarray has leaned into pytest heavily since this section was written, and the advice here no longer applies. (This is relevant today, e.g. a first-time contributor closely following the guide created many unittest tests in Support reusing an existing Grid when opening datasets #1827, rather than following in the style of more recent pytest tests. Using unittest instead of pytest is definitely acceptable as long as the test coverage is good, of course, but it might be adding more complexity than necessary?)
  2. Reduce separation into subsections where possible; there are too many subsections containing only a single paragraph, or a very small number of sentences.
  3. Reduce the number of "Note" / "Attention" / "Caution" boxes. Especially, details which someone following the whole guide would see anyway (such as 3.6 ending with "Remember that we are still not proposing to merge our work into the UXarray GitHub repository, which will be described in the next subsection, 3.7"), should not be in these highlight boxes.

Activity

  1. added
    documentationImprovements or additions to documentation
    developer experienceMakes the codebase easier to read, debug, maintain, or extend.
    on Oct 20, 2026
  2. Sevans711 commented on Oct 20, 2026

    @Sevans711
    CollaboratorAuthor

    While writing this issue report I also looked into xarray's contributor guide as a reference. Putting my notes about it here. At a high level, that guide is structured as follows:

    • Overview (including links to AI policy, github discussions, discord, mailing list, link to community meeting, code of conduct)
    • Where to start (links the github issues tab and has some suggestions of what you might want to work on. Clarifies to just start work, nothing gets "assigned".)
    • Bug reports and enhancement requests (small description about how to submit issue reports or feature requests)
    • A brief primer on github and version control (mostly with links to github, git, github desktop, and other good resources for learning git)
    • Development workflow (fork xarray, create an environment, set up pre-commit hooks, create a new feature branch, editing, commit and push, open a PR)
    • Contributing to the documentation (details about the docs pages, style, how to build them, how to improve them)
    • Contributing to the code base (details about the code base, style, formatting, CI, tests, pytest, running the tests locally, running ASV benchmarks locally)
    • Contributing your changes to xarray (mostly redundant with the development workflow section above. Also mentions a PR checklist).
  3. moved this from 📚 Backlog to 📝 To-Do in UXarray Developmenton Oct 26, 2026
  4. Sevans711 commented on Oct 26, 2026

    @Sevans711
    CollaboratorAuthor

    From internal discussion today: there was a general agreement that the update should include making the guide more concise, especially when it comes to explaining other topics like "how to set up git". There was also a general agreement that, while LLMs might be useful for brainstorming or iterating here, if the final text is written by an LLM then any humans looking at it will probably be less likely to read through it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

developer experienceMakes the codebase easier to read, debug, maintain, or extend.documentationImprovements or additions to documentation

Type

No type

Fields

Priority

Low

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions