I will illustrate the problem with a specific case. Suppose we have a bit-flag style enumeration type defining different kinds of validations. It's tempting to define an enumerator like
FULL_VALIDATION with all bits set. The most obvious (and superficial) justification for it is convenience. Users no longer need to explicitly bitwise OR possibly a large number of specific enumerators.
While such an enumerator may seem OK at first sight, certain concerns come to mind after a second thought. As the library evolves, new validation types may be added, which do not exist in previous versions. As a result,
FULL_VALIDATION will imply a stricter validation than it did before. User code that runs OK on previous versions may fail with the new one. In some sense, this may categorize as a breaking change (thought I don't see it this way).
So, the question is: is such an all-encompassing enumerator appropriate? Personally, I'm in favor of defining it. The exact semantics of
FULL_VALIDATION should be: do as many validations as you possibly can. By incorporating new validations into this enumerator, we are not breaking this semantics (or contract, promise, interface, whichever you prefer). There is no need to modify the documentation concerning this enumerator. In this regard, the subtleties with this enumerator are more of a feature than a bomb.
The semantics of the enumerator is inherently inaccurate and inexact. This is just what it's meant to be, and should be what users expect and want if they choose to use it. Despite being somewhat ambiguous, this is actually a quite flexible design. By using such an enumerator, you allow your code to evolve with the library, taking advantages of any new features as they appear. On the contrary, if you explicitly bitwise OR a number of specific enumerators, you are stuck with it and get none of the flexibility and evolvability.
With respect to "breaking changes" that may result from using such an enumerator, I think it's not only OK but should actually be cheered upon. A bug that fails to manifest itself is still a bug. What's really happening here is that with the new version of the library and its more powerful validations, we just managed to reveal yet another bug in user code. So, it's not an issue of the library, but of user code. Users should be happy with this. It's one of the advantages and benefits by using the
FULL_VALIDATION enumerator. Last but not least, users should ALWAYS run regression tests when moving to new versions of depended libraries.
The above is what I have thought. To be sure and make informed decisions, I want ideas from you guys also.