Core team member guide

CORE_TEAM_GUIDE.md

@@ -0,0 +1,306 @@
+> **_Note:_**  This Core Team Member Guide was adapted from the [napari project's Core Developer Guide](https://napari.org/stable/developers/core_dev_guide.html) and the [Pandas maintainers guide](https://pandas.pydata.org/docs/development/maintaining.html).
+
+# Core Team Member Guide
+
+Welcome, new core team member!  The core team appreciate the quality of
+your work, and enjoy working with you; we have therefore invited you
+to join us.  Thank you for your numerous contributions to the project
+so far.
+
+By accepting 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](https://github.com/orgs/pydata/teams/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](https://pandas.pydata.org/docs/development/maintaining.html)).
+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](https://github.com/pydata/xarray/tree/main/CODE_OF_CONDUCT.md).
+Rather, the tasks that follow are general descriptions of what it might mean to be a core team member:
+
+- 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 / attend developer meetings, coordinate with sponsors),
+- Project evangelism (advertise xarray to new users),
+- Community contact (represent xarray in user communities such as [Pangeo](https://pangeo.io/)),
+- 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`](https://tutorial.xarray.dev/)),
+- Presenting or running tutorials (such as those we have given at the SciPy conference),
+- Maintain the [`xarray.dev`](https://xarray.dev/) landing page and website, the [code for which is here](https://github.com/xarray-contrib/xarray.dev),
+- Write blog posts on the [xarray blog](https://xarray.dev/blog),
+- Maintain xarray's various Continuous Integration Workflows,
+- Write code that goes into xarray `main`.
+
+(Matt Rocklin's post on [the role of a maintainer](https://matthewrocklin.com/blog/2019/05/18/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.
+   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](https://github.com/pydata/xarray/discussions/5404).
+   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” assign the milestone “No Action”, 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](https://matthewrocklin.com/blog/work/2018/02/28/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 reproducible example can’t be provided, add the “Needs info” 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 pandas tag. https://stackoverflow.com/questions/tagged/pandas
+
+   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`.
+
+
+## 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](#reviewing) and especially
+[Merge Only Changes You Understand](#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](https://github.com/pydata/xarray/tree/main/CODE_OF_CONDUCT.md).
+We value sustainable development practices over mad rushes.
+
+When merging, we automatically use GitHub's
+[Squash and Merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request#merging-a-pull-request)
+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](https://docs.xarray.dev/en/stable/contributing.html). 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](https://github.com/pydata/xarray/tree/main/asv_bench) 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.
+
+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](https://docs.xarray.dev/en/stable/contributing.html#backwards-compatibility)
+when making backwards-incompatible changes.
+
+4. **Documentation and tutorials:** All new methods should have appropriate doc
+strings following [PEP257](https://peps.python.org/pep-0257/) and the
+[NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style).
+For any major new features, accompanying changes should be made to our
+[tutorials](https://tutorial.xarray.dev). 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](#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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/committing-changes-to-a-pull-request-branch-created-from-a-fork), or using GitHub’s [suggestion](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request)
+[feature](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request), 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!
+
+### 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.
+
+## Further resources
+
+As a core member, you should be familiar with community and developer
+resources such as:
+
+- Our [contributor guide](https://docs.xarray.dev/en/stable/contributing.html).
+- Our [code of conduct](https://github.com/pydata/xarray/tree/main/CODE_OF_CONDUCT.md).
+- Our [philosophy and development roadmap](https://docs.xarray.dev/en/stable/roadmap.html).
+- [PEP8](https://peps.python.org/pep-0008/) for Python style.
+- [PEP257](https://peps.python.org/pep-0257/) and the
+   [NumPy documentation guide](https://numpy.org/devdocs/dev/howto-docs.html#documentation-style)
+   for docstring conventions.
+- [`pre-commit`](https://pre-commit.com) hooks for autoformatting.
+- [`black`](https://github.com/psf/black) autoformatting.
+- [`flake8`](https://github.com/PyCQA/flake8) linting.
+- [python-xarray](https://stackoverflow.com/questions/tagged/python-xarray) on Stack Overflow.
+- [@xarray_dev](https://twitter.com/xarray_dev) on Twitter.
+- [xarray-dev](https://discord.gg/bsSGdwBn) 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](https://docs.xarray.dev/en/stable/developers-meeting.html) 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
+`xarray-core-team@googlegroups.com` which is sparingly used for discussions
+that are required to be private, such as voting on new core members.
+
+## 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. 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!

doc/whats-new.rst

@@ -41,6 +41,8 @@ Documentation
 - Add docstrings for the :py:class:`Index` base class and add some documentation on how to
   create custom, Xarray-compatible indexes (:pull:`6975`)
   By `Benoît Bovy <https://github.com/benbovy>`_.
+- Added a page clarifying the role of Xarray core team members.
+  (:pull:`7999`) By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~