add more to contributing

Author: alimanfoo

docs/contributing.rst

@@ -102,26 +102,33 @@ To verify that your development environment is working, you can run the unit tes
 Creating a branch
 ~~~~~~~~~~~~~~~~~
 
+Before you do any new work or submit a pull request, please open an issue on GitHub to
+report the bug or propose the feature you'd like to add.
+
 It's best to create a new, separate branch for each piece of work you want to do. E.g.::
 
     git fetch upstream
     git checkout -b shiny-new-feature upsteam/master
 
-This changes your working directory to the shiny-new-feature branch. Keep any changes in
+This changes your working directory to the 'shiny-new-feature' branch. Keep any changes in
 this branch specific to one bug or feature so it is clear what the branch brings to
 NumCodecs.
 
 To update this branch with latest code from NumCodecs, you can retrieve the changes from
-the master branch::
+the master branch and perform a rebase::
 
     git fetch upstream
     git rebase upstream/master
 
 This will replay your commits on top of the latest NumCodecs git master. If this leads to
 merge conflicts, these need to be resolved before submitting a pull request.
+Alternatively, you can merge the changes in from upstream/master instead of rebasing,
+which can be simpler::
 
-Before you do any new work or submit a pull request, please open an issue on GitHub to
-report the bug or propose the feature you'd like to add.
+    git fetch upstream
+    git merge upstream/master
+
+Again, any conflicts need to be resolved before submitting a pull request.
 
 Running the test suite
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -191,3 +198,121 @@ The documentation can be built by running::
     $ tox -e docs
 
 The resulting built documentation will be available in the ``.tox/docs/tmp/html`` folder.
+
+Development best practices, policies and procedures
+---------------------------------------------------
+
+The following information is mainly for core developers, but may also be of interest to
+contributors.
+
+Merging pull requests
+~~~~~~~~~~~~~~~~~~~~~
+
+Pull requests submitted by an external contributor should be reviewed and approved by at least
+one core developers before being merged. Ideally, pull requests submitted by a core developer
+should be reviewed and approved by at least one other core developers before being merged.
+
+Pull requests should not be merged until all CI checks have passed (Travis, AppVeyor,
+Coveralls) against code that has had the latest master merged in.
+
+Compatibility and versioning policies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because NumCodecs is a data encoding/decoding library, there are two types of compatibility to
+consider: API compatibility and data format compatibility.
+
+API compatibility
+"""""""""""""""""
+
+All functions, classes and methods that are included in the API
+documentation (files under ``docs/api/*.rst``) are considered as part of the NumCodecs
+**public API**, except if they have been documented as an experimental feature, in which case they
+are part of the **experimental API**.
+
+Any change to the public API that does **not** break existing third party
+code importing NumCodecs, or cause third party code to behave in a different way, is a
+**backwards-compatible API change**. For example, adding a new function, class or method is usually
+a backwards-compatible change. However, removing a function, class or method; removing an argument
+to a function or method; adding a required argument to a function or method; or changing the
+behaviour of a function or method, are examples of **backwards-incompatible API changes**.
+
+If a release contains no changes to the public API (e.g., contains only bug fixes or
+other maintenance work), then the micro version number should be incremented (e.g.,
+2.2.0 -> 2.2.1). If a release contains public API changes, but all changes are
+backwards-compatible, then the minor version number should be incremented
+(e.g., 2.2.1 -> 2.3.0). If a release contains any backwards-incompatible public API changes,
+the major version number should be incremented (e.g., 2.3.0 -> 3.0.0).
+
+Backwards-incompatible changes to the experimental API can be included in a minor release,
+although this should be minimised if possible. I.e., it would be preferable to save up
+backwards-incompatible changes to the experimental API to be included in a major release, and to
+stabilise those features at the same time (i.e., move from experimental to public API), rather than
+frequently tinkering with the experimental API in minor releases.
+
+Data format compatibility
+"""""""""""""""""""""""""
+
+Each codec class in NumCodecs exposes a ``codec_id`` attribute, which is an identifier for the
+**format of the encoded data** produced by that codec. Thus it is valid for two or more codec
+classes to expose the same value for the ``codec_id`` attribute if the format of the encoded data
+is identical. The ``codec_id`` is intended to provide a basis for achieving and managing
+interoperability between versions of the NumCodecs package, as well as between NumCodecs and other
+software libraries that aim to provide compatible codec implementations. Currently there is no
+formal specification of the encoded data format corresponding to each ``codec_id``, so the codec
+classes provided in the NumCodecs package should be taken as the reference implementation for a
+given ``codec_id``.
+
+There must be a one-to-one mapping from ``codec_id`` values to encoded data formats, and that
+mapping must not change once the first implementation of a ``codec_id`` has been published within a
+NumCodecs release. If a change is proposed to the encoded data format for a particular type of
+codec, then this must be implemented in NumCodecs via a new codec class exposing a new ``codec_id``
+value.
+
+Note that the NumCodecs test suite includes a data fixture and tests to try and ensure that
+data format compatibility is not accidentally broken. See the
+:func:`test_backwards_compatibility` functions in test modules for each codec for examples.
+
+When to make a release
+~~~~~~~~~~~~~~~~~~~~~~
+
+Ideally, any bug fixes that don't change the public API should be released as soon as
+possible. It is fine for a micro release to contain only a single bug fix.
+
+When to make a minor release is at the discretion of the core developers. There are no
+hard-and-fast rules, e.g., it is fine to make a minor release to make a single new
+feature available; equally, it is fine to make a minor release that includes a number of
+changes.
+
+Major releases obviously need to be given careful consideration, and should be done as
+infrequently as possible, as they will break existing code and/or affect data
+compatibility in some way.
+
+Release procedure
+~~~~~~~~~~~~~~~~~
+
+Checkout and update the master branch::
+
+    $ git checkout master
+    $ git pull
+
+Verify all tests pass on all supported Python versions, and docs build::
+
+    $ tox
+
+Tag the version (where "X.X.X" stands for the version number, e.g., "2.2.0")::
+
+    $ version=X.X.X
+    $ git tag -a v$version -m v$version
+    $ git push --tags
+
+Release source code to PyPI::
+
+    $ python setup.py register sdist
+    $ twine upload dist/numcodecs-${version}.tar.gz
+
+Obtain checksum for release to conda-forge::
+
+    $ openssl sha256 dist/numcodecs-${version}.tar.gz
+
+Release to conda-forge by making a pull request against the numcodecs-feedstock conda-forge
+repository, incrementing the version number.