Merge remote-tracking branch 'upstream/master' into contribution_over…

…haul

* upstream/master:
  move whatsnew contributions (SciTools#3816)
  Parse with packaging version (SciTools#3815)
  Add "What's New" entries for unpinning Cartopy, Matplotlib, Proj (SciTools#3811)
  tidy issue templates (SciTools#3814)
  Legacy doc notice (SciTools#3813)
  Update issue templates
  Update issue templates
  Update issue templates
  Unpin Matplotlib and proj (SciTools#3762)

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,31 @@
+---
+name: "\U0001F41B Bug Report"
+about: Submit a bug report to help us improve Iris
+title: ''
+labels: 'New: Issue, Type: Bug'
+assignees: ''
+
+---
+
+## 🐛 Bug Report
+<!-- Provide a clear description of what the bug is -->
+
+## How To Reproduce
+Steps to reproduce the behaviour:
+
+1. 
+2. 
+3. 
+
+## Expected behaviour
+<!-- A clear and concise description of what you expected to happen -->
+
+## Screenshots
+<!-- If applicable, add screenshots to help explain your problem -->
+
+## Environment 
+ - OS & Version: [e.g., Ubuntu 20.04 LTS]
+ - Iris Version: [e.g., From the command line run `python -c "import iris; print(iris.__version__)"`]
+
+## Additional context
+<!-- Provide any further information to help us understand -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+# reference: https://docs.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,12 @@
+---
+name: "\U0001F4DA Documentation"
+about: Report an issue with the Iris documentation
+title: ''
+labels: 'New: Documentation, Type: Documentation'
+assignees: ''
+
+---
+
+## 📚 Documentation
+<!-- See https://scitools-iris.readthedocs.io/en/latest/ -->
+<!-- Describe the issue or provide a suggestion for improving the Iris documentation -->

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,18 @@
+---
+name: "⚙ Feature Request"
+about: Submit a request for a new feature in Iris
+title: ''
+labels: 'New: Feature'
+assignees: ''
+
+---
+
+## ⚙ Feature Request
+<!-- Provide a clear and concise description of the feature proposal -->
+
+## Motivation
+<!-- Is your feature request related to an existing issue? -->
+<!-- I'm always frustrated when ... -->
+
+## Additional context
+<!-- Provide any further information to help us understand -->

.github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,11 @@
+---
+name: "\U0001F4F0 Custom Issue"
+about: Submit a generic issue to help us improve Iris
+title: ''
+labels: 'New: Issue'
+assignees: ''
+
+---
+
+## 📰 Custom Issue
+<!-- Provide a clear description of what the issue is, and we'll try our best to help 😀 -->

ci/requirements/readthedocs.yml

@@ -14,12 +14,11 @@ dependencies:
 
 # Without these, iris won't even import.
 
-  - cartopy>=0.12
-  - proj4<6
+  - cartopy>=0.18
   - cf-units>=2
   - cftime
   - dask>=2
-  - matplotlib<3.3
+  - matplotlib
   - netcdf4
   - numpy>=1.14
   - scipy

docs/iris/src/index.rst

@@ -1,10 +1,16 @@
+.. note:: For **Iris 2.4** and earlier documentation please see the
+          `legacy documentation`_
+
+.. _legacy documentation: https://scitools.org.uk/iris/docs/v2.4.0/
+
+
 Iris Documentation
 ==================
 
 .. todolist::
 
-**A powerful, format-agnostic, community-driven Python library for analysing and
-visualising Earth science data.**
+**A powerful, format-agnostic, community-driven Python library for analysing
+and visualising Earth science data.**
 
 Iris implements a data model based on the `CF conventions <http://cfconventions.org>`_
 giving you a powerful, format-agnostic interface for working with your data.
@@ -23,18 +29,19 @@ associated metadata as first-class objects includes:
 * subsetting and extraction,
 * merge and concatenate,
 * aggregations and reductions (including min, max, mean and weighted averages),
-* interpolation and regridding (including nearest-neighbor, linear and area-weighted), and
+* interpolation and regridding (including nearest-neighbor, linear and
+  area-weighted), and
 * operator overloads (``+``, ``-``, ``*``, ``/``, etc.).
 
-A number of file formats are recognised by Iris, including CF-compliant NetCDF, GRIB,
-and PP, and it has a plugin architecture to allow other formats to be added seamlessly.
+A number of file formats are recognised by Iris, including CF-compliant NetCDF,
+GRIB, and PP, and it has a plugin architecture to allow other formats to be
+added seamlessly.
 
 Building upon `NumPy <http://www.numpy.org/>`_ and
-`dask <https://dask.pydata.org/en/latest/>`_,
-Iris scales from efficient single-machine workflows right through to multi-core
-clusters and HPC.
-Interoperability with packages from the wider scientific Python ecosystem comes from Iris'
-use of standard NumPy/dask arrays as its underlying data storage.
+`dask <https://dask.pydata.org/en/latest/>`_, Iris scales from efficient
+single-machine workflows right through to multi-core clusters and HPC.
+Interoperability with packages from the wider scientific Python ecosystem comes
+from Iris' use of standard NumPy/dask arrays as its underlying data storage.
 
 
 .. toctree::

docs/iris/src/userguide/cube_maths.rst

@@ -219,6 +219,8 @@ The result could now be plotted using the guidance provided in the
     A very similar example to this can be found in the examples section, 
     with the title "Deriving Exner Pressure and Air Temperature".
 
+.. _cube_maths_combining_units:
+
 Combining units
 ---------------
 

lib/iris/analysis/cartography.py

@@ -599,6 +599,12 @@ def project(cube, target_proj, nx=None, ny=None):
         on the statistics of the data e.g. the mean and standard deviation
         will not be preserved.
 
+    .. warning::
+
+        If the target projection is non-rectangular, e.g. Robinson, the target
+        grid may include points outside the boundary of the projection. The
+        latitude/longitude of such points may be unpredictable.
+
     """
     try:
         lon_coord, lat_coord = _get_lon_lat_coords(cube)

lib/iris/plot.py

@@ -441,6 +441,11 @@ def _draw_2d_from_bounds(draw_method_name, cube, *args, **kwargs):
                     values = np.arange(data.shape[data_dim] + 1) - 0.5
                 else:
                     values = coord.contiguous_bounds()
+                    values = _fixup_dates(coord, values)
+                    if values.dtype == np.dtype(object) and isinstance(
+                        values[0], datetime.datetime
+                    ):
+                        values = mpl_dates.date2num(values)
 
             plot_arrays.append(values)
 

lib/iris/quickplot.py

@@ -13,7 +13,10 @@
 
 """
 
+from packaging import version
+
 import cf_units
+from matplotlib import __version__ as _mpl_version
 import matplotlib.pyplot as plt
 
 import iris.config
@@ -46,6 +49,13 @@ def _title(cube_or_coord, with_units):
 
             if _use_symbol(units):
                 units = units.symbol
+            if units.is_time_reference():
+                # iris.plot uses matplotlib.dates.date2num, which is fixed to the below unit.
+                if version.parse(_mpl_version) >= version.parse("3.3"):
+                    days_since = "1970-01-01"
+                else:
+                    days_since = "0001-01-01"
+                units = "days since {}".format(days_since)
             title += " / {}".format(units)
 
     return title

lib/iris/tests/experimental/test_raster.py

@@ -77,6 +77,10 @@ def _check_tiff_export(self, masked, inverted=False):
             339,
             33550,
             33922,
+            42113,
+            # Don't add a check entry for this, as coding changed between gdal
+            # version 1 and 2.
+            # tif_header_entries[42113] = (u'1e+20',)
         ]
         tif_header_entries = {
             256: (160,),
@@ -130,12 +134,6 @@ def _check_tiff_export(self, masked, inverted=False):
             # Mask some of the data + expect a slightly different header...
             cube.data = np.ma.masked_where(cube.data <= 380, cube.data)
 
-            # There is an additional key..
-            tif_header_keys += [42113]
-            # Don't add a check entry for this, as coding changed between gdal
-            # version 1 and 2, *and* between Python2 and Python3.
-            # tif_header_entries[42113] = (u'1e+20',)
-
         if inverted:
             # Check with the latitude coordinate (and the corresponding
             # cube.data) inverted.

lib/iris/tests/integration/plot/test_plot_2d_coords.py

@@ -43,14 +43,14 @@ def test_2d_coord_bounds_platecarree(self):
         cube = simple_cube_w_2d_coords()[0, 0]
         ax = plt.axes(projection=ccrs.PlateCarree(central_longitude=180))
         qplt.pcolormesh(cube)
-        ax.coastlines(color="red")
+        ax.coastlines(resolution="110m", color="red")
         self.check_graphic()
 
     def test_2d_coord_bounds_northpolarstereo(self):
         cube = simple_cube_w_2d_coords()[0, 0]
         ax = plt.axes(projection=ccrs.NorthPolarStereo())
         qplt.pcolormesh(cube)
-        ax.coastlines(color="red")
+        ax.coastlines(resolution="110m", color="red")
         self.check_graphic()
 
 
@@ -71,7 +71,7 @@ def test_2d_coords_contour(self):
         cube.add_aux_coord(co_x, (0, 1))
         ax = plt.axes(projection=ccrs.PlateCarree())
         qplt.contourf(cube)
-        ax.coastlines(color="red")
+        ax.coastlines(resolution="110m", color="red")
         ax.gridlines(draw_labels=True)
         ax.set_extent((0, 180, 0, 90))
         self.check_graphic()

lib/iris/tests/integration/plot/test_vector_plots.py

@@ -121,7 +121,7 @@ def test_2d_plain_latlon(self):
         self.plot(
             "latlon_2d", u_cube, v_cube, coords=("longitude", "latitude")
         )
-        ax.coastlines(color="red")
+        ax.coastlines(resolution="110m", color="red")
         ax.set_global()
         self.check_graphic()
 
@@ -132,7 +132,7 @@ def test_2d_plain_latlon_on_polar_map(self):
         self.plot(
             "latlon_2d_polar", u_cube, v_cube, coords=("longitude", "latitude")
         )
-        ax.coastlines(color="red")
+        ax.coastlines(resolution="110m", color="red")
         self.check_graphic()
 
     def test_2d_rotated_latlon(self):
@@ -142,7 +142,7 @@ def test_2d_rotated_latlon(self):
         self.plot(
             "2d_rotated", u_cube, v_cube, coords=("longitude", "latitude")
         )
-        ax.coastlines(color="red")
+        ax.coastlines(resolution="110m", color="red")
         ax.set_global()
         self.check_graphic()