linewrap and style

Author: d-v-b

docs/developers/contributing.rst

@@ -272,51 +272,71 @@ Compatibility and versioning policies
 
 Versioning
 """"""""""
-Versions of this library are identified by a triplet of integers with the form  ``<major>.<minor>.<patch>``, for example 3.0.4. A release of ``zarr-python`` is associated with a new
-version identifier. That new identifier is generated by incrementing exactly one of the components of the previous version identifier by 1. When incrementing the ``major``
-component of the version identifier, the ``minor`` and ``patch`` components is reset to 0. When incrementing the minor component, the patch component is reset to 0.
-
-Releases are classified by the library changes contained in that release. This classification determines which
-component of the version identifier is incremented on release.
-
-* ``major`` releases (for example, ``2.18.0`` -> ``3.0.0``) are for major API changes that will require extensive adaptation efforts from many users and downstream projects.
+Versions of this library are identified by a triplet of integers with the form
+``<major>.<minor>.<patch>``, for example ``3.0.4``. A release of ``zarr-python`` is associated with a new
+version identifier. That new identifier is generated by incrementing exactly one of the components of
+the previous version identifier by 1. When incrementing the ``major`` component of the version identifier,
+the ``minor`` and ``patch`` components is reset to 0. When incrementing the minor component,
+the patch component is reset to 0.
+
+Releases are classified by the library changes contained in that release. This classification
+determines which component of the version identifier is incremented on release.
+
+* ``major`` releases (for example, ``2.18.0`` -> ``3.0.0``) are for changes that will
+  require extensive adaptation efforts from many users and downstream projects.
   For example, breaking changes to widely-used user-facing APIs should only be applied in a major release.
 
 
-  Users and downstream projects should carefully consider the impact of a major release before adopting it.
-  In advance of a major release, developers should communicate the scope of the upcoming changes, and help users prepare for them.
+  Users and downstream projects should carefully consider the impact of a major release before
+  adopting it.
+  In advance of a major release, developers should communicate the scope of the upcoming changes,
+  and help users prepare for them.
+
+* ``minor`` releases (or example, ``3.0.0`` -> ``3.1.0``) are for changes that do not require
+  significant effort from most users or downstream downstream projects to respond to. API changes
+  are possible in minor releases if the burden on users imposed by those changes is sufficiently small.
 
-* ``minor`` releases (or example, ``3.0.0`` -> ``3.1.0``) are for minor changes that do not require significant effort from most users or downstream
-  downstream projects to respond to. API changes are possible in minor releases if the burden on users imposed by those changes is sufficiently small.
   For example, a recently released API may need fixes or refinements that are breaking, but low impact
   due to the recency of the feature. Such API changes are permitted in a minor release.
 
 
   Minor releases are safe for most users and downstream projects to adopt.
 
 
-* ``patch`` releases (for example, ``3.1.0`` -> ``3.1.1``) are for changes that contain no breaking or behaviour changes for downstream projects or users. Examples of changes in a patch release are bugfixes and documentation improvements.
+* ``patch`` releases (for example, ``3.1.0`` -> ``3.1.1``) are for changes that contain no breaking
+  or behaviour changes for downstream projects or users. Examples of changes suitable for a patch release are
+  bugfixes and documentation improvements.
 
 
   Users should always feel safe upgrading to a the latest patch release.
 
-Note that this versioning scheme is not consistent with `Semantic Versioning <https://semver.org/>`_. The Zarr library
-may release breaking changes in ``minor`` releases, or even ``patch`` releases under exceptional circumstances.
-But we should strive to avoid doing so. A better model for our versioning scheme is `Intended Effort Versioning <https://jacobtomlinson.dev/effver/>`_, or "EffVer".
-The guiding principle off EffVer is to categorize releases based on the *expected effort required to upgrade to that release*.
+Note that this versioning scheme is not consistent with `Semantic Versioning <https://semver.org/>`_.
+Contrary to SemVer, the Zarr library may release breaking changes in ``minor`` releases, or even
+``patch`` releases under exceptional circumstances. But we should strive to avoid doing so.
+
+A better model for our versioning scheme is `Intended Effort Versioning <https://jacobtomlinson.dev/effver/>`_,
+or "EffVer". The guiding principle off EffVer is to categorize releases based on the *expected effort
+required to upgrade to that release*.
 
-Zarr developers should make changes as smooth as possible for users. This means making backwards-compatible changes wherever possible.
-When a backwards-incompatible change is necessary, users should be notified well in advance, e.g. via informative deprecation warnings.
+Zarr developers should make changes as smooth as possible for users. This means making
+backwards-compatible changes wherever possible. When a backwards-incompatible change is necessary,
+users should be notified well in advance, e.g. via informative deprecation warnings.
 
 Data format compatibility
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Zarr library is an implementation of a file format standard defined externally -- see the `Zarr specifications website <https://zarr-specs.readthedocs.io>`_ for the list of Zarr file format specifications.
+The Zarr library is an implementation of a file format standard defined externally --
+see the `Zarr specifications website <https://zarr-specs.readthedocs.io>`_ for the list of
+Zarr file format specifications.
 
 
-If an existing Zarr format version changes, or a new version of the Zarr format is released, then the Zarr library will generally require changes. It is very likely that
-a new Zarr format will require extensive breaking changes to the Zarr library, and so support for a new Zarr format in the Zarr library will almost certainly come in new ``major`` release.
-When the Zarr library adds support for a new Zarr format, there may be a period of accelerated changes as developers refine newly added APIs and deprecate old APIs. In such a transitional phase breaking changes may be more frequent than usual.
+If an existing Zarr format version changes, or a new version of the Zarr format is released, then
+the Zarr library will generally require changes. It is very likely that a new Zarr format will
+require extensive breaking changes to the Zarr library, and so support for a new Zarr format in the
+Zarr library will almost certainly come in new ``major`` release.
+When the Zarr library adds support for a new Zarr format, there may be a period of accelerated
+changes as developers refine newly added APIs and deprecate old APIs. In such a transitional phase
+breaking changes may be more frequent than usual.
 
 
 Release procedure
@@ -360,5 +380,7 @@ pre-releases will be available under
 Post-release
 """"""""""""
 
-- Review and merge the pull request on the `conda-forge feedstock <https://github.com/conda-forge/zarr-feedstock>`_ that will be automatically generated.
+- Review and merge the pull request on the
+  `conda-forge feedstock <https://github.com/conda-forge/zarr-feedstock>`_ that will be
+  automatically generated.
 - Create a new "Unreleased" section in the release notes