Developer Documentation
=======================

This document contains specific instructions for HARP developers.

Commit steps
------------
If your changes impact any of the autogenerated parts, make sure these
get regenerated (all using the autotools build system):

Run 'make doc' to regenerate the documentation.
Current versions used for generating the documentation are:
- Sphinx 1.8.2
- sphinx-autobuild 0.7.1
- sphinx-rtd-theme 0.4.2
- breathe 4.11.0
- doxygen 1.8.14
With the following versions for third party dependencies:
- Babel 2.6.0
- Jinja2 2.10
- MarkupSafe 1.1.0
- PyYAML 3.13
- Pygments 2.2.0
- alabaster 0.7.12
- argh 0.26.2
- backports-abc 0.5
- certifi 2018.10.15
- chardet 3.0.4
- docutils 0.14
- futures 3.2.0
- idna 2.7
- imagesize 1.1.0
- livereload 2.5.2
- packaging 18.0
- pathtools 0.1.2
- port-for 0.3.1
- pyparsing 2.3.0
- pytz 2018.7
- singledispatch 3.4.0.3
- six 1.11.0
- snowballstemmer 1.2.1
- sphinxcontrib-websupport 1.1.0
- tornado 5.1.1
- typing 3.6.6
- urllib3 1.24.1
- watchdog 0.9.0

Run 'make dist' to have config.h.cmake.in and harp.h.cmake.in updated to be
in line with config.h.in and harp.h.in.

Make sure that python/_harpc.py gets updated with any change to harp.h.in.
This should happen automatically using the Makefile dependencies.
But, make sure to do this by performing an in-source build of HARP such that
the _harpc.py file in the python subdirectory of the source tree gets replaced.
Current versions of cffi and pycparser for generating the python interface are:
- cffi 1.7.0
- pycparser 2.14

Run 'make indent' using GNU indent (2.2.11) to update the indentation of the C
code. You may have to run it twice to work around flipping indentation choices
of GNU indent.

Release checklist
-----------------
- make sure all 'commit steps' (see above) have been performed
- ensure automake and CMake builds are consistent
- check compiler warnings
- increase HARP version number in configure.ac + CMakeLists.txt +
     doc/conf.py (version + release)
  format version is x.y(.z).
  Increase x for big backward compatibility breaking changes.
  Otherwise, increase y if any features were introduced.
  Only add/increase z for bug fix releases.
- update HARP format version if needed (configure.ac + CMakeLists.txt)
  format version is x.y (major.minor version).
  major version increases are for changes in the structure:
  - basic data types
  - attribute names and data types
  - dimension names
  minor version increases are for changes in the content conventions:
  - variable naming
  - ascending/descending contraints
  - dimension ordering
  so (x+1).* routines will usually need a modified reading routine to read x.*
  and x.(y+1) routines should be able to map from x.y after reading a product
  there is no forward compatibility, so higher versions will always be rejected
- update version number of shared libharp library (both in configure.ac and
  CMakeLists.txt)
- make sure all documentation is updated accordingly
- update README (version number at top)
- update CHANGES

Conventions
-----------
- Don't use a starting capital letter or terminating period for warning/error
  messages. Treat messages as something that could be included between
  parentheses as part of a larger sentence. Try to stick to a single sentence
  for a message. If you have to use multiple sentences then separate them with
  a semicolon.
- The same capitalization/punctuation rule for messages also applies for
  descriptions used in product ingestions.
