CORE_TEAM_GUIDE.md

Note: This Core Team Member Guide was adapted from the napari project's Core Developer Guide and the Pandas maintainers guide.

Core Team Member Guide

Welcome, new core team member! We appreciate the quality of your work, and enjoy working with you! Thank you for your numerous contributions to the project so far.

By accepting the invitation to become a core team member you are not required to commit to doing any more work - xarray is a volunteer project, and we value the contributions you have made already.

You can see a list of all the current core team members on our @pydata/xarray GitHub team. Once accepted, you should now be on that list too. This document offers guidelines for your new role.

Tasks

Xarray values a wide range of contributions, only some of which involve writing code. As such, we do not currently make a distinction between a "core team member", "core developer", "maintainer", or "triage team member" as some projects do (e.g. pandas). That said, if you prefer to refer to your role as one of the other titles above then that is fine by us!

Xarray is mostly a volunteer project, so these tasks shouldn’t be read as “expectations”. There are no strict expectations, other than to adhere to our Code of Conduct. Rather, the tasks that follow are general descriptions of what it might mean to be a core team member:

• Facilitate a welcoming environment for those who file issues, make pull requests, and open discussion topics,
• Triage newly filed issues,
• Review newly opened pull requests,
• Respond to updates on existing issues and pull requests,
• Drive discussion and decisions on stalled issues and pull requests,
• Provide experience / wisdom on API design questions to ensure consistency and maintainability,
• Project organization (run developer meetings, coordinate with sponsors),
• Project evangelism (advertise xarray to new users),
• Community contact (represent xarray in user communities such as Pangeo),
• Key project contact (represent xarray's perspective within key related projects like NumPy, Zarr or Dask),
• Project fundraising (help write and administrate grants that will support xarray),
• Improve documentation or tutorials (especially on tutorial.xarray.dev),
• Presenting or running tutorials (such as those we have given at the SciPy conference),
• Help maintain the xarray.dev landing page and website, the code for which is here,
• Write blog posts on the xarray blog,
• Help maintain xarray's various Continuous Integration Workflows,
• Help maintain a regular release schedule (we aim for one or more releases per month),
• Attend the bi-weekly community meeting (issue),
• Contribute to the xarray codebase.

(Matt Rocklin's post on the role of a maintainer may be interesting background reading, but should not be taken to strictly apply to the Xarray project.)

Obviously you are not expected to contribute in all (or even more than one) of these ways! They are listed so as to indicate the many types of work that go into maintaining xarray.

It is natural that your available time and enthusiasm for the project will wax and wane - this is fine and expected! It is also common for core team members to have a "niche" - a particular part of the codebase they have specific expertise with, or certain types of task above which they primarily perform.

If however you feel that is unlikely you will be able to be actively contribute in the foreseeable future (or especially if you won't be available to answer questions about pieces of code that you wrote previously) then you may want to consider letting us know you would rather be listed as an "Emeritus Core Team Member", as this would help us in evaluating the overall health of the project.

Issue triage

One of the main ways you might spend your contribution time is by responding to or triaging new issues. Here’s a typical workflow for triaging a newly opened issue or discussion:

1. Thank the reporter for opening an issue.

   The issue tracker is many people’s first interaction with the xarray project itself, beyond just using the library. It may also be their first open-source contribution of any kind. As such, we want it to be a welcoming, pleasant experience.

2. Is the necessary information provided?

   Ideally reporters would fill out the issue template, but many don’t. If crucial information (like the version of xarray they used), is missing feel free to ask for that and label the issue with “needs info”. The report should follow the guidelines for xarray discussions. You may want to link to that if they didn’t follow the template.

   Make sure that the title accurately reflects the issue. Edit it yourself if it’s not clear. Remember also that issues can be converted to discussions and vice versa if appropriate.

3. Is this a duplicate issue?

   We have many open issues. If a new issue is clearly a duplicate, label the new issue as “duplicate”, and close the issue with a link to the original issue. Make sure to still thank the reporter, and encourage them to chime in on the original issue, and perhaps try to fix it.

   If the new issue provides relevant information, such as a better or slightly different example, add it to the original issue as a comment or an edit to the original post.

4. Is the issue minimal and reproducible?

   For bug reports, we ask that the reporter provide a minimal reproducible example. See minimal-bug-reports for a good explanation. If the example is not reproducible, or if it’s clearly not minimal, feel free to ask the reporter if they can provide and example or simplify the provided one. Do acknowledge that writing minimal reproducible examples is hard work. If the reporter is struggling, you can try to write one yourself and we’ll edit the original post to include it.

   If a nice reproducible example has been provided, thank the reporter for that. If a reproducible example can’t be provided, add the “needs mcve” label.

   If a reproducible example is provided, but you see a simplification, edit the original post with your simpler reproducible example.

5. Is this a clearly defined feature request?

   Generally, xarray prefers to discuss and design new features in issues, before a pull request is made. Encourage the submitter to include a proposed API for the new feature. Having them write a full docstring is a good way to pin down specifics.

   We may need a discussion from several xarray maintainers before deciding whether the proposal is in scope for xarray.

6. Is this a usage question?

   We prefer that usage questions are asked on StackOverflow with the python-xarray tag or as a GitHub discussion topic.

   If it’s easy to answer, feel free to link to the relevant documentation section, let them know that in the future this kind of question should be on StackOverflow, and close the issue.

7. What labels and milestones should I add?

   Apply the relevant labels. This is a bit of an art, and comes with experience. Look at similar issues to get a feel for how things are labeled. Labels used for labelling issues that relate to particular features or parts of the codebase normally have the form topic-<SOMETHING>.

   If the issue is clearly defined and the fix seems relatively straightforward, label the issue as contrib-good-first-issue. You can also remove the needs triage label that is automatically applied to all newly-opened issues.

8. Where should the poster look to fix the issue?

   If you can, it is very helpful to point to the approximate location in the codebase where a contributor might begin to fix the issue. This helps ease the way in for new contributors to the repository.

Code review and contributions

As a core team member, you are a representative of the project, and trusted to make decisions that will serve the long term interests of all users. You also gain the responsibility of shepherding other contributors through the review process; here are some guidelines for how to do that.

All contributors are treated the same

You should now have gained the ability to merge or approve other contributors' pull requests. Merging contributions is a shared power: only merge contributions you yourself have carefully reviewed, and that are clear improvements for the project. When in doubt, and especially for more complex changes, wait until at least one other core team member has approved. (See Reviewing and especially Merge Only Changes You Understand below.)

It should also be considered best practice to leave a reasonable (24hr) time window after approval before merge to ensure that other core team members have a reasonable chance to weigh in. Adding the plan-to-merge label notifies developers of the imminent merge.

We are also an international community, with contributors from many different time zones, some of whom will only contribute during their working hours, others who might only be able to contribute during nights and weekends. It is important to be respectful of other peoples schedules and working habits, even if it slows the project down slightly - we are in this for the long run. In the same vein you also shouldn't feel pressured to be constantly available or online, and users or contributors who are overly demanding and unreasonable to the point of harassment will be directed to our Code of Conduct. We value sustainable development practices over mad rushes.

When merging, we automatically use GitHub's Squash and Merge to ensure a clean git history.

You should also continue to make your own pull requests as before and in accordance with the general contributing guide. These pull requests still require the approval of another core team member before they can be merged.

How to conduct a good review

Always be kind to contributors. Contributors are often doing volunteer work, for which we are tremendously grateful. Provide constructive criticism on ideas and implementations, and remind yourself of how it felt when your own work was being evaluated as a novice.

xarray strongly values mentorship in code review. New users often need more handholding, having little to no git experience. Repeat yourself liberally, and, if you don’t recognize a contributor, point them to our development guide, or other GitHub workflow tutorials around the web. Do not assume that they know how GitHub works (many don't realize that adding a commit automatically updates a pull request, for example). Gentle, polite, kind encouragement can make the difference between a new core team member and an abandoned pull request.

When reviewing, focus on the following:

1. Usability and generality: xarray is a user-facing package that strives to be accessible to both novice and advanced users, and new features should ultimately be accessible to everyone using the package. xarray targets the scientific user community broadly, and core features should be domain-agnostic and general purpose. Custom functionality is meant to be provided through our various types of interoperability.

2. Performance and benchmarks: As xarray targets scientific applications that often involve large multidimensional datasets, high performance is a key value of xarray. While every new feature won't scale equally to all sizes of data, keeping in mind performance and our benchmarks during a review may be important, and you may need to ask for benchmarks to be run and reported or new benchmarks to be added. You can run the CI benchmarking suite on any PR by tagging it with the run-benchmark label.

3. APIs and stability: Coding users and developers will make extensive use of our APIs. The foundation of a healthy ecosystem will be a fully capable and stable set of APIs, so as xarray matures it will very important to ensure our APIs are stable. Spending the extra time to consider names of public facing variables and methods, alongside function signatures, could save us considerable trouble in the future. We do our best to provide deprecation cycles when making backwards-incompatible changes.

4. Documentation and tutorials: All new methods should have appropriate doc strings following PEP257 and the NumPy documentation guide. For any major new features, accompanying changes should be made to our tutorials. These should not only illustrates the new feature, but explains it.

5. Implementations and algorithms: You should understand the code being modified or added before approving it. (See Merge Only Changes You Understand below.) Implementations should do what they claim and be simple, readable, and efficient in that order.

6. Tests: All contributions must be tested, and each added line of code should be covered by at least one test. Good tests not only execute the code, but explore corner cases. It can be tempting not to review tests, but please do so.

Other changes may be nitpicky: spelling mistakes, formatting, etc. Do not insist contributors make these changes, but instead you should offer to make these changes by pushing to their branch, or using GitHub’s suggestion feature, and be prepared to make them yourself if needed. Using the suggestion feature is preferred because it gives the contributor a choice in whether to accept the changes.

Unless you know that a contributor is experienced with git, don’t ask for a rebase when merge conflicts arise. Instead, rebase the branch yourself, force-push to their branch, and advise the contributor to force-pull. If the contributor is no longer active, you may take over their branch by submitting a new pull request and closing the original, including a reference to the original pull request. In doing so, ensure you communicate that you are not throwing the contributor's work away! If appropriate it is a good idea to acknowledge other contributions to the pull request using the Co-authored-by syntax in the commit message.

Merge only changes you understand

Long-term maintainability is an important concern. Code doesn't merely have to work, but should be understood by multiple core developers. Changes will have to be made in the future, and the original contributor may have moved on.

Therefore, do not merge a code change unless you understand it. Ask for help freely: we can consult community members, or even external developers, for added insight where needed, and see this as a great learning opportunity.

While we collectively "own" any patches (and bugs!) that become part of the code base, you are vouching for changes you merge. Please take that responsibility seriously.

Feel free to ping other active maintainers with any questions you may have.

Further resources

As a core member, you should be familiar with community and developer resources such as:

• Our contributor guide.
• Our code of conduct.
• Our philosophy and development roadmap.
• PEP8 for Python style.
• PEP257 and the NumPy documentation guide for docstring conventions.
• pre-commit hooks for autoformatting.
• black autoformatting.
• flake8 linting.
• python-xarray on Stack Overflow.
• @xarray_dev on Twitter.
• xarray-dev discord community (normally only used for remote synchronous chat during sprints).

You are not required to monitor any of the social resources.

Where possible we prefer to point people towards asynchronous forms of communication like github issues instead of realtime chat options as they are far easier for a global community to consume and refer back to.

We hold a bi-weekly developers meeting via video call. This is a great place to bring up any questions you have, raise visibility of an issue and/or gather more perspectives. Attendance is absolutely optional, and we keep the meeting to 30 minutes in respect of your valuable time. This meeting is public, so we occasionally have non-core team members join us.

We also have a private mailing list for core team members [email protected] which is sparingly used for discussions that are required to be private, such as nominating new core members and discussing financial issues.

Inviting new core members

Any core member may nominate other contributors to join the core team. While there is no hard-and-fast rule about who can be nominated, ideally, they should have: been part of the project for at least two months, contributed significant changes of their own, contributed to the discussion and review of others' work, and collaborated in a way befitting our community values. We strongly encourage nominating anyone who has made significant non-code contributions to the Xarray community in any way. After nomination voting will happen on a private mailing list. While it is expected that most votes will be unanimous, a two-thirds majority of the cast votes is enough.

Core team members can choose to become emeritus core team members and suspend their approval and voting rights until they become active again.

Contribute to this guide (!)

This guide reflects the experience of the current core team members. We may well have missed things that, by now, have become second nature—things that you, as a new team member, will spot more easily. Please ask the other core team members if you have any questions, and submit a pull request with insights gained.

Conclusion

We are excited to have you on board! We look forward to your contributions to the code base and the community. Thank you in advance!