Improve design docs

[myurkin]

Is your feature request related to a problem? Please describe.

In some discussions of code development (i.e., how to implement some new features or refactor existing code), there is "my feeling or understanding" but no written guidelines. Existing page CodeStyle discusses the style, but not the structure. Wiki page CodeDesign explains current structure, but shows that is is not optimal, while not providing guidelines for further extension. Development workflow is partly described in contributing guide, but it lacks the underlying design principles as well.

Describe the solution you'd like

• A rework of existing pages, maybe adding files like ARCHITECTURE.md. It is not obvious how to separate architectural guidelines and design principles, but the former are currently missing altogether.
• Explicit discussion of semantic versioning (including policy for breaking changes)
• Explicit discussion of C standard (including its potential upgrade) and critical features (like support for complex double, see also Parallel OpenCL #185).
• Maybe, move all relevant files to one place (e.g., into .github/ folder)

Reasonable architecture guidelines will most probably be not satisfied by the current code, so we need to mention it and have a plan for a transitional period.

[myurkin]

What should be considered as breaking changes? Or what is sufficiently good agreement between two versions of the same code, executed with the same input? There are several potential levels (and many examples):

Definitely breaking

• Compile errors:

  • replacing/adding required external libraries, Iterative solver on OpenCL (GPU) devices #199
  • increasing required version of external libraries or compiler (or language standard, including MPI, OpenCL, etc.).
    This may seem redundant if the new required version is already sufficiently old (say, 10 years) and widely supported (if talking about a standard), see also Specify requirements #352.

• Run errors:

  • removing some features
  • renaming command line options (at the end of deprecation period), Refactor command line interface #348, Remove deprecated specification of beam center as argument to -beam #306
  • changing expected format of input files (after deprecation, if possible)

• Errors when parsing output:

  • renaming output files or default output folders, Add .txt to ADDA output files #273
  • changing existing lines in log or output files, Consistent use of capilalizaiton in output #327

• Difference of 1-2 significant digit in output:

  • Changing the default DDA formulation or settings for output, Change the default DDA formulation #305, Reference frame for defining scattered angles with non-default incident direction #170, Improve heuristics for chosing default number of scattering angles (-ntheta) #100
  • Changing definition of some of produced quantities, Consider switching to SI units #253

Potentially breaking (questionable)

• Same as above, but for experimental features:

  • removal of features that were always advertised as "under development", -int so in Integrating Green’s tensor: second order kD approximation in ADDA #299
  • removal of compilation modes that only affect performance, Consider deprecating SSE3 code #260

• Adding lines in the log or output. This is most complicated, illustrating the difference between output files (especially, log), which are only partly machine-readable, and a proper public API (Working as a library #200). It makes sense to at least explicitly formulate, what kind of stability users can expect from these files. For example:

  • format of existing lines should not change (see above in Breaking class)
  • lines can be added anywhere into log (for new features). Thus, this file can only be searched for lines, but not indexed.
  • lines can be added files with name=value strings, like CrossSec*, but probably to the end. So indexing (taking n-th line) is possible, but searching for name is still much more reliable.
  • spreadsheet files (mueller*, IntField*, etc.) should not change at all

• Difference in the output comparable to the iterative-method threshold or, roughly, 4-10 significant digits:

  • changing the default iterative solver or its convergence threshold, -iter qmr2 by default #289, Stopping criterion for iterative solvers #161
  • optimizations/changes to functions that are computed with satisfactory precision, Optimize calculation of reflected Green's tensor #176, Optimize calculation of Csca and g  #22

Not breaking

• adding optional external libraries or optional features from higher versions of these libraries, Linear algebra  #61

• large changes in output, if previous value can be considered erroneous (i.e., the change is a bug fix)

• difference of output comparable to floating point precision (say, > 10 significant digits). High optimization level of ADDA compilation does not guarantee this level of reproducibility anyway (e.g., if compiled on different hardware). Examples:

  • optimizations/changes to functions, that are supposed to be computed with floating point precision, Ci,Si optimization #55
  • changing order of operations (this applies to a lot of different changes)

Conclusion

The first class of changes definitely require increment of major version, third class - hardly any care at all. The main question is about the second class. Should we consider them breaking or create some special tag for them (e.g., semi-breaking).

I guess, the latter classification is anyway useful to indicate that extra attention is needed to them in release notes, but without increment of major version. However, we need to review whether some of those listed in this middle section need to be elevated to Breaking.

/cc @Argencle