pattern for creating new versions of core components
155 views
Skip to first unread message
Stefan Seifert
Nov 27, 2019, 3:56:08 AM11/27/19
to aem-core-co...@googlegroups.com
i'm currently preparing a new PR for the link handling improvements [1], which involves as discussed in [2] creating new versions of the affected components based on the 3.0.0 branch. i'm nearly finished, however i've some questions on the best practices when creating new versions of existing components. here is my understanding:
1. a new version vX+1 does not inherit (no resourceSuperType) of version vX of the core component
2. that means all existing HTML scripts, dialog definitions, cq:editConfig definitions etc. are copied from version vX to vX+1.
3. once this is done new features to these scripts are only applied to the latest version vX+1. bugfixes may need to be applied to the old version as well (manually).
4. there is only one model interface that is used for all model versions (with default implementations throwing unsupportedoperation)
5. for the model implementations we make use of java inheritance to avoid duplicating logic. we create a new model implementation for the node vX+1 version, but it extends the impl for vX and adds/overwrites only the necessary logic.
6. for unit tests classes we do the same, we inherit from the original test class, change the TEST_BASE path to point to a new set of JSON content/output files, but reuse the existing unit tests and overwrite only that parts that need to be different for vX+1.
7. for the set of JSON content/output files that are used to test the model variants in the unit tests they are copied to a new vX+1 directory and adapted as needed.
8. what are we doing with clientlibs dedicated to a core component (for author or publish side) - should we copy them as well? currently i've kept the old ones and referenced them.
in the case of link handling this approach makes sense, esp. as the JSON output changes in an "incompatible" way (the old url etc. properties are removed, and the new "link" object structures area added instead in the JSON output). my current WIP branch is [3].
there is a problem with this approach, though. while version 3.0.0 is under development, each and every change made to the copied script files, dialog definitions, component definition etc. that is applied to the existing version vX has to be applied to the copy in vX+1 as well. there is no way to automate this with merging, as it's a copy in a separate path. it has to be done manually. this may become somewhat a maintenance hell and is prone to errors. it may be beneficial to release the new version 3.0.0 as soon as possible with the vX+1 version, and do no longer maintain the vX versions. but this again may be a problem for projects heavily depending on the existing vX versions that do not want to update soon to vX+1 due to customizations and compatibility.
with version 2.0.0 there was the same change, but i think the core components were less in use in that time back, and the feature set was very small.
once we agree on the points listed above they should be documented in the wiki.
stefan
[1] https://github.com/adobe/aem-core-wcm-components/issues/713
[2] https://groups.google.com/forum/#!msg/aem-core-components-dev/st_31IWmyhs/fT5ZCXT3DAAJ
[3] https://github.com/stefanseifert/aem-core-wcm-components/tree/issue/713-link-refs-300
1. a new version vX+1 does not inherit (no resourceSuperType) of version vX of the core component
2. that means all existing HTML scripts, dialog definitions, cq:editConfig definitions etc. are copied from version vX to vX+1.
3. once this is done new features to these scripts are only applied to the latest version vX+1. bugfixes may need to be applied to the old version as well (manually).
4. there is only one model interface that is used for all model versions (with default implementations throwing unsupportedoperation)
5. for the model implementations we make use of java inheritance to avoid duplicating logic. we create a new model implementation for the node vX+1 version, but it extends the impl for vX and adds/overwrites only the necessary logic.
6. for unit tests classes we do the same, we inherit from the original test class, change the TEST_BASE path to point to a new set of JSON content/output files, but reuse the existing unit tests and overwrite only that parts that need to be different for vX+1.
7. for the set of JSON content/output files that are used to test the model variants in the unit tests they are copied to a new vX+1 directory and adapted as needed.
8. what are we doing with clientlibs dedicated to a core component (for author or publish side) - should we copy them as well? currently i've kept the old ones and referenced them.
in the case of link handling this approach makes sense, esp. as the JSON output changes in an "incompatible" way (the old url etc. properties are removed, and the new "link" object structures area added instead in the JSON output). my current WIP branch is [3].
there is a problem with this approach, though. while version 3.0.0 is under development, each and every change made to the copied script files, dialog definitions, component definition etc. that is applied to the existing version vX has to be applied to the copy in vX+1 as well. there is no way to automate this with merging, as it's a copy in a separate path. it has to be done manually. this may become somewhat a maintenance hell and is prone to errors. it may be beneficial to release the new version 3.0.0 as soon as possible with the vX+1 version, and do no longer maintain the vX versions. but this again may be a problem for projects heavily depending on the existing vX versions that do not want to update soon to vX+1 due to customizations and compatibility.
with version 2.0.0 there was the same change, but i think the core components were less in use in that time back, and the feature set was very small.
once we agree on the points listed above they should be documented in the wiki.
stefan
[1] https://github.com/adobe/aem-core-wcm-components/issues/713
[2] https://groups.google.com/forum/#!msg/aem-core-components-dev/st_31IWmyhs/fT5ZCXT3DAAJ
[3] https://github.com/stefanseifert/aem-core-wcm-components/tree/issue/713-link-refs-300
Richard Hand
Nov 27, 2019, 4:18:20 AM11/27/19
to AEM Core Components Developer Community
Hi Stefan,
this is a good summary, all the points you list are consistent with the approach we took so far. For 8. we have copied the client libraries so far for clarity, although we could rethink this at a future date if the markup API stabilises and just re-use the same widgets across versions.
I agree that maintaining vX + 1 versions until they're released will become difficult as more changes are merged onto master, but I don't think we have much choice there. Getting 3.0.0 out sooner of course reduces the risk there, but we should also make sure that we gather all breaking changes for the new versions we plan to introduce before releasing, so as to help reduce version creep.
Best,
Richard
this is a good summary, all the points you list are consistent with the approach we took so far. For 8. we have copied the client libraries so far for clarity, although we could rethink this at a future date if the markup API stabilises and just re-use the same widgets across versions.
I agree that maintaining vX + 1 versions until they're released will become difficult as more changes are merged onto master, but I don't think we have much choice there. Getting 3.0.0 out sooner of course reduces the risk there, but we should also make sure that we gather all breaking changes for the new versions we plan to introduce before releasing, so as to help reduce version creep.
Best,
Richard
Konrad Windszus
Feb 12, 2020, 8:32:32 AM2/12/20
to AEM Core Components Developer Community
Hi Richard,
What is the reason for point 1 listed by Stefan? Why not using inheritance also on the script/dialog level?Konrad
Reply all
Reply to author
Forward
0 new messages