Repository navigation
Description
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:
- "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).
- "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.
- Primer on github and version control (the current 2.1)
- 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.
- 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:
- 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?)
- Reduce separation into subsections where possible; there are too many subsections containing only a single paragraph, or a very small number of sentences.
- 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.
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Projects
- StatusShow more project fields📝 To-Do
Activity
Sevans711 commentedon Oct 20, 2026
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:
Sevans711 commentedon Oct 26, 2026
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.