Merge remote-tracking branch 'upstream/master' into dev

* upstream/master: (23 commits)
  combine keep_attrs and combine_attrs in apply_ufunc (pydata#5041)
  Explained what a deprecation cycle is (pydata#5289)
  Code cleanup (pydata#5234)
  FacetGrid docstrings (pydata#5293)
  Add whats new for dataset interpolation with non-numerics (pydata#5297)
  Allow dataset interpolation with different datatypes (pydata#5008)
  Flexible indexes: add Index base class and xindexes properties (pydata#5102)
  pre-commit: autoupdate hook versions (pydata#5280)
  convert the examples for apply_ufunc to doctest (pydata#5279)
  fix the new whatsnew section
  Ensure `HighLevelGraph` layers are `Layer` instances (pydata#5271)
  New whatsnew section
  Release-workflow: Bug fix (pydata#5273)
  more maintenance on whats-new.rst (pydata#5272)
  v0.18.0 release highlights (pydata#5266)
  Fix exception when display_expand_data=False for file-backed array. (pydata#5235)
  Warn ignored keep attrs (pydata#5265)
  Disable workflows on forks (pydata#5267)
  fix the built wheel test (pydata#5270)
  pypi upload workflow maintenance (pydata#5269)
  ...

.github/workflows/cancel-duplicate-runs.yaml

@@ -8,6 +8,7 @@ jobs:
   cancel:
     name: Cancel previous runs
     runs-on: ubuntu-latest
+    if: github.repository == 'pydata/xarray'
     steps:
     - uses: styfle/cancel-workflow-action@0.9.0
       with:

.github/workflows/ci-additional.yaml

@@ -12,7 +12,9 @@ jobs:
   detect-ci-trigger:
     name: detect ci trigger
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    if: |
+      github.repository == 'pydata/xarray'
+      && (github.event_name == 'push' || github.event_name == 'pull_request')
     outputs:
       triggered: ${{ steps.detect-trigger.outputs.trigger-found }}
     steps:
@@ -111,6 +113,7 @@ jobs:
   doctest:
     name: Doctests
     runs-on: "ubuntu-latest"
+    if: github.repository == 'pydata/xarray'
     defaults:
       run:
         shell: bash -l {0}

.github/workflows/ci-pre-commit.yml

@@ -10,6 +10,7 @@ jobs:
   linting:
     name: "pre-commit hooks"
     runs-on: ubuntu-latest
+    if: github.repository == 'pydata/xarray'
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2

.github/workflows/ci.yaml

@@ -12,7 +12,9 @@ jobs:
   detect-ci-trigger:
     name: detect ci trigger
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    if: |
+      github.repository == 'pydata/xarray'
+      && (github.event_name == 'push' || github.event_name == 'pull_request')
     outputs:
       triggered: ${{ steps.detect-trigger.outputs.trigger-found }}
     steps:

.github/workflows/pypi-release.yaml

@@ -0,0 +1,96 @@
+name: Build and Upload xarray to PyPI
+on:
+  release:
+    types:
+      - published
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-artifacts:
+    runs-on: ubuntu-latest
+    if: github.repository == 'pydata/xarray'
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: 3.8
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install setuptools setuptools-scm wheel twine check-manifest
+
+      - name: Build tarball and wheels
+        run: |
+          git clean -xdf
+          git restore -SW .
+          python -m build --sdist --wheel .
+
+      - name: Check built artifacts
+        run: |
+          python -m twine check dist/*
+          pwd
+          if [ -f dist/xarray-0.0.0.tar.gz ]; then
+            echo "❌ INVALID VERSION NUMBER"
+            exit 1
+          else
+            echo "✅ Looks good"
+          fi
+      - uses: actions/upload-artifact@v2
+        with:
+          name: releases
+          path: dist
+
+  test-built-dist:
+    needs: build-artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: 3.8
+      - uses: actions/download-artifact@v2
+        with:
+          name: releases
+          path: dist
+      - name: List contents of built dist
+        run: |
+          ls -ltrh
+          ls -ltrh dist
+      - name: Publish package to TestPyPI
+        if: github.event_name == 'push'
+        uses: pypa/gh-action-pypi-publish@v1.4.2
+        with:
+          user: __token__
+          password: ${{ secrets.TESTPYPI_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+          verbose: true
+
+      - name: Check uploaded package
+        if: github.event_name == 'push'
+        run: |
+          sleep 3
+          python -m pip install --upgrade pip
+          python -m pip install --extra-index-url https://test.pypi.org/simple --upgrade xarray
+          python -m xarray.util.print_versions
+
+  upload-to-pypi:
+    needs: test-built-dist
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v2
+        with:
+          name: releases
+          path: dist
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.4.2
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}
+          verbose: true

.github/workflows/upstream-dev-ci.yaml

@@ -14,7 +14,9 @@ jobs:
   detect-ci-trigger:
     name: detect upstream-dev ci trigger
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    if: |
+      github.repository == 'pydata/xarray'
+      && (github.event_name == 'push' || github.event_name == 'pull_request')
     outputs:
       triggered: ${{ steps.detect-trigger.outputs.trigger-found }}
     steps:
@@ -31,12 +33,8 @@ jobs:
     runs-on: ubuntu-latest
     needs: detect-ci-trigger
     if: |
-      always()
-      && github.repository == 'pydata/xarray'
-      && (
         (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch')
         || needs.detect-ci-trigger.outputs.triggered == 'true'
-      )
     defaults:
       run:
         shell: bash -l {0}
@@ -97,9 +95,7 @@ jobs:
     name: report
     needs: upstream-dev
     if: |
-      always()
-      && github.event_name == 'schedule'
-      && github.repository == 'pydata/xarray'
+      github.event_name == 'schedule'
       && needs.upstream-dev.outputs.artifacts_availability == 'true'
     runs-on: ubuntu-latest
     defaults:

.pre-commit-config.yaml

@@ -13,15 +13,15 @@ repos:
       - id: isort
   # https://github.com/python/black#version-control-integration
   - repo: https://github.com/psf/black
-    rev: 21.4b2
+    rev: 21.5b0
     hooks:
       - id: black
   - repo: https://github.com/keewis/blackdoc
     rev: v0.3.3
     hooks:
       - id: blackdoc
   - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.9.1
+    rev: 3.9.2
     hooks:
       - id: flake8
   # - repo: https://github.com/Carreau/velin

doc/api.rst

@@ -846,6 +846,7 @@ Faceting
    plot.FacetGrid
    plot.FacetGrid.add_colorbar
    plot.FacetGrid.add_legend
+   plot.FacetGrid.add_quiverkey
    plot.FacetGrid.map
    plot.FacetGrid.map_dataarray
    plot.FacetGrid.map_dataarray_line

doc/contributing.rst

@@ -379,10 +379,34 @@ with ``git commit --no-verify``.
 Backwards Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Please try to maintain backward compatibility. *xarray* has growing number of users with
+Please try to maintain backwards compatibility. *xarray* has a growing number of users with
 lots of existing code, so don't break it if at all possible.  If you think breakage is
-required, clearly state why as part of the pull request.  Also, be careful when changing
-method signatures and add deprecation warnings where needed.
+required, clearly state why as part of the pull request.
+
+Be especially careful when changing function and method signatures, because any change
+may require a deprecation warning. For example, if your pull request means that the
+argument ``old_arg`` to ``func`` is no longer valid, instead of simply raising an error if
+a user passes ``old_arg``, we would instead catch it:
+
+.. code-block:: python
+
+    def func(new_arg, old_arg=None):
+        if old_arg is not None:
+            from warnings import warn
+
+            warn(
+                "`old_arg` has been deprecated, and in the future will raise an error."
+                "Please use `new_arg` from now on.",
+                DeprecationWarning,
+            )
+
+            # Still do what the user intended here
+
+This temporary check would then be removed in a subsequent version of xarray.
+This process of first warning users before actually breaking their code is known as a
+"deprecation cycle", and makes changes significantly easier to handle both for users
+of xarray, and for developers of other libraries that depend on xarray.
+
 
 .. _contributing.ci: