Proposal 5: Definition of Backward Compatibility #2795
Replies: 4 comments 3 replies
-
|
Additional topics to discuss:
|
Beta Was this translation helpful? Give feedback.
-
|
I think it is quite useful to have a list of changes that are known to be backwardly incompatible, but rather than try to be exhaustive my feeling is that these should be guidelines, and then we refer to first principles as David suggests. |
Beta Was this translation helpful? Give feedback.
-
|
For reference, here is a link to https://cdm.finos.org/docs/contribution/#backward-compatibility and the PPT Brian mentions |
Beta Was this translation helpful? Give feedback.
-
1.a Slide #2 "Planning breaking changes" in the CDM roadmap, where are incompatible changes flagged? https://github.com/finos/common-domain-model/blob/master/ROADMAP.md. it would need to be clear on the roadmap. e.g. red highlight 1.b. where are incompatible changes listed for each version? (release notes?) 1.c slide #2 says "for clarity, breaking changes shall only be included in x.0 versions"). This may not be enough. Since we could have many breaking changes between minor versions e.g. from 5.5 to 5.6 (breaking changes that qualify under the "exception process" slide #3) if that is the case, we may need to carry a list of incompatible changes through the lifecycle of 5.x versions. That list could reset with the next major version 6.0.
|
Beta Was this translation helpful? Give feedback.
-
|
1.b Yes, a "backward incompatible change" should contain a dedicated section labelled as such in the release notes. A practice that we have started to apply, but which should be codified, is to include those between incremental dev versions, i.e. from x.0.0-dev.n to x.0.0-dev.n+1. The note must include details about how "old" objects should be remapped into "new" ones, ideally pointing at illustrative example(s) distributed in the test pack. In doing so, when the x.0 production version is cut, the list of such "backward incompatible changes" from all the x.0.0-dev.n release notes can be compiled into the x.0 release notes, giving implementors the instructions manual to remap from x-1 to x. |
Beta Was this translation helpful? Give feedback.
-
@dschwartznyc That would be the definition of "forward compatible", but I propose that we're explicitly not adding that constraint. |
Beta Was this translation helpful? Give feedback.
-
|
@lolabeis seems as if the scope of the discussion expanded from what is "backward compatibility" to what is a "breaking change" (may have been my doing). Agree that N code ingesting N+1 formatted data would be the definition of "forward compatible." Regardless, I don't think there's a concrete plan to support compatibility in either direction and I support the recommendation to make "backward compatible" a higher priority when the time comes to address interoperability between versions. |
Beta Was this translation helpful? Give feedback.
-
Current: Like other types of software, backward compatibility in the context of a domain model means that an implementor of that model would not have to make any change to update to such version.
• Prohibited changes:
o Change to the structure (e.g. the attributes of a data type or the inputs of a function) or removal of any model element
o Change to the name of any model element (e.g. types, attributes, enums, functions or reporting rules)
o Change to any condition or cardinality constraint that makes validation more restrictive
o Change to the DSL that results in any existing expression becoming invalid
o Change to the DSL that results in change to any of the generated code's public interfaces
• Allowed changes:
o Change that relaxes any condition or cardinality constraint
o Change to any synonym that improves, or at least does not degrade, the mapping coverage
o Addition of new examples or test packs
o Change to the user documentation or model descriptions
o Addition of new data types, optional attributes, enumerations, rules or functions that do not impact current functionality
Proposed:
Prohibited changes:
All the above plus:
o Any DSL change that results in any prohibited change or change in a test case input or output file.
o A public interface shall be defined as any generated API or function that can be called from software or service outside the CDM.
BL: >> Back in September I had developed a more comprehensive set of proposals around change control. See in the attached PowerPoint. The intention is to provide some clearer definitions of what is to be controlled and how, while also providing a certain amount of wiggle room so that non-critical changes don’t force a major release. David asked me to present this to the SWG next month.
Chris: We cannot stop another project/application (the DSL) from performing releases so the first of the two new bullet points cannot be added. I also wonder whether we should revisit the 2 Prohibited Changes associated to the DSL in this context?
I don’t follow what the second bullet point is suggesting should be prohibited? Can you elaborate please?
I would also probably make it clearer in the Prohibited Changes list that existing elements from within an enum cannot be removed
DS:
• The terminology of this proposal is also confusing. For example, is the intent for using the term "prohibited change" to describe those that must be migrated to the next Major release and cannot be included in a Minor or Patch release? If so, there is an urgent need for definitions that are very clear since "prohibited changes" must fall under the proposed annual schedule for Major releases.
• What is the categorization for the migration of data from one field to another? Is it "prohibited" for releases labeled "Minor" / "Bug-fix"?
• Are we confident that any addition of a test case should be a breaking change? What if the addition increases the test coverage of the existing model and the test passes?
• How do we classify changes to the machinery associated with the DSL such as the code-generators?
• How do we classify changes to the build process for CDM and who is responsible for its maintenance?
David: We agree that the definition of backward compatibility and the process around it should be tightened. It critically underpins many of the above proposals. It’s a topic onto itself and merits a dedicated discussion. However, rather than trying to define it by listing what it is and isn’t (incomplete), we should drive it from first principles and then illustrate it with some examples of allowed vs disallowed changes. This approach would also allow us to implement proper regression testing of backward compatibility.
There are 2 types of model entities: objects (types and enums) and functions.
For objects, we propose the following definition of backward compatible. It is based on 2 users or systems (1 producer and 1 consumer) trying to exchange information about those objects.
A change (n --> n+1) is backward compatible if a consumer on version n+1 can consume and validate any object X that has been produced and validated by a producer on version n
In this definition:
“validate” means passing all the condition and cardinality constraints
“any object X” could be restricted to objects annotated as rootType and all of their attributes, recursively.
For functions, backward compatible simply means preserving the function’s signature (inputs and outputs). And indeed we should distinguish between “public” functions (that are exposed to model consumers) and “private” ones (that are internal to the model workings) – something that we don’t have in the CDM right now.
Result:
Additional clarity is needed. Some commenters misunderstood use of prohibited changes and DSL. Keep in mind the purpose if to define changes that are not backward compatible. Meaning version 4 cannot be used with version 5. Although since we don't currently embed versions and version validation this is more of a statement on usage. Final details to be worked out.
Beta Was this translation helpful? Give feedback.
All reactions