API Standards

[ryanmrichard]

The authors group of the NWChemEx Community have agreed to follow semantic versioning. One of the requirements of semantic versioning is bumping the major whenever there is an API break. This is not as concrete as it sounds without us defining what is/isn't part of the API. I think it makes sense for the authors to come to a consensus on this front, put said consensus in writing somewhere, and link to it from repos to which the consensus applies.

FWIW, I am particularly thinking about C++ standards and things like:

• What header files can users rely on not moving?
• Typedefs, not the underlying type, are part of the API, i.e., we reserve the right to swap the underlying type out so long as the new type has the same interface.
• Contiguous-ness guarantees. Only from .data() members, i.e. operator[] may or may not be contiguous.
• Alisaing vs. owning semantics combined with typedefs means typedefs must be standardized because you can not rely on the underlying type, e.g., types should end in "view" or "reference" to guarantee aliasing and "value" (or none of the other distinctions) to guarantee owning.

Are there other things people can think of? Basically the idea is with a 1.0 imminent, we should know what we can and cannot change going forward.