apex-enterprise-patterns
Create Releases and add docs when introducing Breaking changes
I noticed 7 months ago changes were made to separate the Domain into two entities, one to work as the trigger handler and the other to basically manipulate data. This is a breaking change because class and interface names were changed. So it would be nice to have a Doc showing before and after, when these type of changes happen before merging them. Also, it would be nice if you could tag at least these Major changes, so people are aware of them. Because my project has an older version of FFLIB and the sample code is using the latest, when I wrote my app following the sample I got some errors while deploying. Because of these errors, I spent around an hour reading the sample code changes to understand what I should do to enable my app to work with the old fflib.
We did our best to circulate the announcement about the plan to split the Domain/TriggerHandler responsibilities of fflib_SObjectDomain. We created this discussion and it went out on Twitter too
https://github.com/apex-enterprise-patterns/fflib-apex-common/discussions/323
To our knowledge, there was only one very minor breaking changes introduced and it was discussed over on the PR:
https://github.com/apex-enterprise-patterns/fflib-apex-common/pull/300#issuecomment-766720325
You are correct that it wasn't documented in an obvious way -- though you're the first person to call attention to this after the new code has been merged for 7 months now. Prior major updates to fflib-apex-common were documented in the README but that was overlooked in this case. We will try to keep this in mind next time a breaking change is introduced.
As for tagging. This is a continual challenge with open source projects in general but even harder with Salesforce 'loose code' where there is only one sensible way of including 3rd party modules: 2GP unlocked packages (and unlocked packages don't work for ISVs or most happy soup dev teams). We recently resurrected and discussed that problem over on https://github.com/apex-enterprise-patterns/fflib-apex-common/issues/239#issuecomment-925766112 ... point being: if you look at your code base, you have no way of knowing what 'snapshot' of fflib is in your project. Is it one from 2017, 2018, 2019, etc? So having a tag in git isn't going to be terribly helpful, IMO.
@daveespo maybe you should put these changes in a next branch until trailhead modules are updated. And do the same for the sample code