Merge pull request #76 from sadielbartholomew/joss-paper

JOSS paper text & documentation revisions

CONTRIBUTING.md

@@ -1,45 +1,26 @@
 Thank you for taking the time to consider making a contribution to the
 cfdm package.
 
-# General Guidelines
-
-General questions, suggestions for enhancements, and reports of bugs
-may be reported in the GitHub issue tracker:
-https://github.com/NCAS-CMS/cfdm/issues
-
-Contributions are welcome and should first be raised as issues in the
-GitHub issue tracker: https://github.com/NCAS-CMS/cfdm/issues, prior
-to submitting a pull request containing the new code made from a fork
-of the cfdm GitHub code repository: https://github.com/NCAS-CMS/cfdm.
-
-# Change log
-
-See the change log
-(https://github.com/NCAS-CMS/cfdm/blob/master/Changelog.rst) for the
-changes introduced by each version.
-
-# Versioning
-
-A ``CF.major.minor`` numeric version scheme is used, where ``CF`` is
-the version of the CF conventions (e.g. ``1.9``) to which a particular
-version of cfdm applies.
-
-## Major changes comprise
-
-  * changes to the API, such as
-    - changing the name of an existing function or method;
-    - changing the behaviour of an existing function or method;
-    - changing the name of an existing keyword parameter;
-    - changing the default value of an existing keyword parameter;
-    - changing the meaning of a value of an existing keyword parameter.
-    - introducing a new function or method;
-    - introducing a new keyword parameter;
-    - introducing a new permitted value of a keyword parameter;
-
- * changes to required versions of the dependencies.
-
-## Minor changes comprise
-
-  * bug fixes that do not change the API;
-  * changes to the documentation;
-  * code tidying.
+Please consult the
+[dedicated guidance page](https://ncas-cms.github.io/cfdm/contributing.html)
+in the documentation for detailed guidance on contributing to cfdm.
+
+Overall, general questions, suggestions for enhancements, and reports
+of bugs are appreciated and should be reported via the
+[GitHub issue tracker](https://github.com/NCAS-CMS/cfdm/issues).
+
+Code-change contributions to cfdm are also very welcome, though to
+ensure the work is in line with plans for development of the library, please
+always discuss any intended changes with the core development team in the
+first instance. The standard way to do so is also through the
+issue tracker:
+
+* if there is an existing issue in the tracker than you would like
+  to address, comment on that issue to indicate you would like to work on
+  it;
+* conversely, if there is not an issue corresponding to your ideas for
+  contribution, please raise a new issue outlining the idea.
+
+If you are not sure about any aspect related to contributing after
+reading the guidance page, do not hesitate to get in touch by posting
+a question in an issue.

docs/source/contributing.rst

@@ -14,8 +14,8 @@ Version |release| for version |version| of the CF conventions.
    :local:
    :backlinks: entry
 
-**Report bugs**
----------------
+**Reporting bugs**
+------------------
 
 Please report bugs via a new issue in issue tracker
 (https://github.com/NCAS-CMS/cfdm/issues), using the **Bug report**
@@ -60,37 +60,39 @@ Clone your fork locally and create a branch:
     $ cd cfdm
     $ git checkout -b <your-bugfix-feature-branch-name master>
 
-Break your edits up into reasonably sized commits.
+Break your edits up into reasonably-sized commits, each representing
+a single logical change:
 
 .. code-block:: console
 	  
     $ git commit -a -m "<COMMIT MESSAGE>"
 
 Create a new changelog entry in ``Changelog.rst``. The entry should be
-entered (where ``<description>`` is a brief description of the change)
-as:
+written (where ``<description>`` should be a *brief* description of
+the change) as:
 
 .. code-block:: rst
 
    * <description> (https://github.com/NCAS-CMS/cfdm/issues/<issue number>)
 
-Run the test suite:
+Run the test suite to make sure the tests all pass:
 
 .. code-block:: console
 
    $ cd cfdm/test
    $ python run_tests.py
 
 Add your name to the list of contributors list at
-``docs/source/contributing.rst``
+``docs/source/contributing.rst``.
 
 Finally, make sure all commits have been pushed to the remote copy of
 your fork and submit the pull request via the GitHub website, to the
 ``master`` branch of the ``NCAS-CMS/cfdm`` repository. Make sure to
 reference the original issue in the pull request's description.
 
 Note that you can create the pull request while you're working on
-this, as it will automatically update as you add more commits.
+this, as it will automatically update as you add more commits. If it is
+a work in progress, you can mark it initially as a draft pull request.
 
 ----
 
@@ -107,4 +109,3 @@ ideas, code, and documentation to the cfdm library:
 * Martin Juckes
 * Riley Brady  
 * Sadie Bartholomew  
-

docs/source/releases.rst

@@ -48,6 +48,9 @@
 **Versioning**
 --------------
 
+Finding versions
+^^^^^^^^^^^^^^^^
+
 Version |release| for version |version| of the CF conventions.
 
 The version of the CF conventions and the CF data model being used may
@@ -66,12 +69,40 @@ changed.
 
 The version identifier of the cfdm package is based on the version of
 the CF conventions to which it applies, with the addition of extra
-integer values for updates that apply to the same version of CF. See
-https://github.com/NCAS-CMS/cfdm/blob/master/CONTRIBUTING.md for
-details.
+integer values for updates that apply to the same version of CF:
 
 .. code-block:: python
    :caption: *Retrieve the version of the cfdm package.*
 	     	     
    >>> cfdm.__version__
-   '1.8.6.0'
+   '1.8.7.0'
+
+The next section outlines the scheme used to set version identifiers.
+
+Versioning strategy
+^^^^^^^^^^^^^^^^^^^
+
+A ``CF.major.minor`` numeric version scheme is used, where ``CF`` is
+the version of the CF conventions (e.g. ``1.9``) to which a particular
+version of cfdm applies.
+
+**Major** changes comprise:
+
+* changes to the API, such as:
+
+  * changing the name of an existing function or method;
+  * changing the behaviour of an existing function or method;
+  * changing the name of an existing keyword parameter;
+  * changing the default value of an existing keyword parameter;
+  * changing the meaning of a value of an existing keyword parameter.
+  * introducing a new function or method;
+  * introducing a new keyword parameter;
+  * introducing a new permitted value of a keyword parameter;
+
+* changes to required versions of the dependencies.
+
+**Minor** changes comprise:
+
+* bug fixes that do not change the API;
+* changes to the documentation;
+* code tidying.

joss/paper.md

@@ -25,37 +25,38 @@ bibliography: paper.bib
 
 # Summary
 
-The `cfdm` open source Python library [@Hassell:2020] implements the
+The `cfdm` open-source Python library [@Hassell:2020] implements the
 data model [@Hassell:2017] of the CF (Climate and Forecast) metadata
-conventions [@Eaton:2020], and so should be able to represent and
+conventions [@Eaton:2020] and so should be able to represent and
 manipulate all existing and conceivable CF-compliant datasets.
 
 The CF conventions are designed to promote the creation, processing,
 and sharing of climate and forecasting data using Network Common Data
 Form (netCDF) files and libraries [@Rew:1990; @Rew:2006]. They cater
-for data from model simulations; and from observations, made in situ
+for data from model simulations as well as from observations, made in situ
 or by remote sensing platforms, of the planetary surface, ocean, and
 atmosphere. For a netCDF data variable, they provide a description of
-the physical meaning of data; and of its spatial, temporal, and other
+the physical meaning of data and of its spatial, temporal, and other
 dimensional properties. The CF data model is an abstract
 interpretation of the CF conventions that is independent of the netCDF
 encoding.
 
 The `cfdm` library has been designed as a stand-alone application,
-e.g. as used in the pre-publication checks for the CMIP6 data request
-[@Juckes:2020; @Eyring:2016]; and also to provide a CF data model
-implementation to other software libraries, e.g. as used in the
-`cf-python` library [@Hassell2:2020].
+e.g. as deployed in the pre-publication checks for the CMIP6 data request
+[@Juckes:2020; @Eyring:2016], and also to provide a CF data model
+implementation to other software libraries, such as
+`cf-python` [@Hassell2:2020].
 
 # Statement of need
 
 The complexity of scientific datasets tends to increase with
-improvements in scientific capabilities, and it is essential that
+improvements in scientific capabilities and it is essential that
 software interfaces are able to understand new research outputs. To
 the authors' knowledge, `cfdm` and software built on it are currently
-the only libraries that are guaranteed to be able to handle every
-possible type of CF-compliant dataset. All others omit facets that are
-not currently of interest to their particular user communities.
+the only libraries that can understand all CF-netCDF datasets, made
+possible by the complete implementation of the CF data model. All
+others omit facets that are not currently of interest to their
+particular user communities.
 
 # Functionality
 
@@ -71,39 +72,39 @@ The latest version of the CF conventions (CF-1.8) is fully represented
 by `cfdm`, including the recent additions of simple geometries
 [@iso19125:2004] and netCDF group hierarchies.
 
-The central element of the CF data model is the "field construct",
+The central element of the CF data model is the "field construct"
 that encapsulates all of the data and metadata for a single
 variable. The `cfdm` library can create field constructs ab initio, or
-read them from netCDF files; inspect, subspace and modify in memory;
+read them from netCDF files; inspect, subspace, and modify in memory;
 and write them to CF-netCDF dataset files. As long as it can interpret
 the data, `cfdm` does not enforce CF-compliance, allowing non-compliant
-datasets to be read, processed, corrected and rewritten.
+datasets to be read, processed, corrected, and rewritten.
 
 This represents a limited functionality in comparison to other
 software libraries used for analysis, which often include higher-level
-functions such as those for regridding, statistical analysis, etc. The
-decision to limit the functionality was made for the following
+functions such as those for regridding and statistical analysis, etc.
+The decision to restrict the functionality was made for the following
 reasons:
 
-* The restricted functionality is sufficient for dataset inspection
-  and creation, and for modifying non-CF-compliant datasets -
+* The controlled functionality is sufficient for dataset inspection
+  and creation, as well as for modifying non-CF-compliant datasets,
   activities that are an important part of both archive curation and
   data analysis workflows.
 
 * An extended functionality could complicate the implementation,
   making it harder to update the library as the CF data model evolves.
 
-* The expectation is that other libraries will build on `cfdm`,
+* The anticipation is that other libraries will build on `cfdm`,
   inheriting its knowledge of the CF conventions and extending the API
   to add more sophisticated functions that are appropriate to their
-  users (e.g. `cf-python`).
+  users (notably `cf-python`).
 
 # Example usage
 
 In this example, a netCDF dataset is read from disk and the resulting
 field construct is inspected. The field construct is then subspaced,
-its standard name property is changed, and the new field construct is
-inspected and written to a new dataset on disk:
+has its standard name property changed, and finally is
+re-inspected and written to a new dataset on disk:
 
 ```python
 >>> import cfdm
@@ -131,28 +132,28 @@ Dimension coords: latitude(1) = [-75.0] degrees_north
 
 # Evolution
 
-The CF data model will evolve in line with the CF conventions, and the
+The CF data model will evolve in line with the CF conventions and the
 `cfdm` library will need to respond to such changes. To facilitate this,
 there is a core implementation (`cfdm.core`) that defines an in-memory
-representation of a field construct, but with no further features. The
-implementation of an enhancement to the CF data model then proceeds as
-follows: the core implementation is first updated independently, and
-then the functionality for dataset interaction and further field
-construct modification is updated outside of the inherited core
-implementation.
+representation of a field construct, with no further features. The
+implementation of an enhancement to the CF data model would proceed
+first with an independent update to the core implementation, then with
+an update, outside of the inherited core implementation, to the
+functionality for dataset interaction and further field construct
+modification.
 
 # Extensibility
 
 To encourage other libraries to build on `cfdm`, it has been designed
 to be subclassable so that the CF data model representation is easily
 importable into third-party software. An important part of this
 framework is the ability to inherit the mapping of CF data model
-constructs to, and from, netCDF datasets. This is made possible by the
-use of the bridge design pattern [@Gamma:1995], that decouples the
+constructs to, and from, netCDF datasets. This is made possible by
+use of the bridge design pattern [@Gamma:1995] that decouples the
 implementation of the CF data model from the netCDF encoding so that
 the two can vary independently. Such an inheritance is employed by the
 `cf-python` library, which adds many metadata-aware analytical
-capabilities, and employs a more sophisticated data class. By
+capabilities and employs a more sophisticated data class. By
 preserving the API of the `cfdm` data class, the `cf-python` data
 class can be used within the inherited `cfdm` code base with almost no
 modifications.