| Re: [cross-project-issues-dev] Unannounced Changes Have Unforeseen Consequences |
I, for one, would like to have further discussion on the topic of platform strictly following Semantic Versioning as it’s an important tool in ensuring that we create valid installations that don’t break with class not found or method not found errors. - Konstantin From: cross-project-issues-dev-bounces@xxxxxxxxxxx [mailto:cross-project-issues-dev-bounces@xxxxxxxxxxx] On Behalf Of John Arthorne Hi everyone, This has been a great discussion. I have a few points to add: - It is very important for the Platform (and other projects) to have the right to occasionally remove API. In a nutshell, maintaining API forever generally benefits existing consumers but adds pain and cost for those maintaining the API. As the number of API maintainers has dwindled, the Platform made a deliberate choice about 5 years ago to slightly relax its previous stringent API maintenance practices. There are APIs in Platform none of the remaining committers understand or use, and it creates a large burden on them to maintain it. The huge API surface area of the Platform also creates a burden for new consumers. When there are 5 available ways to do something with the Platform API, removing some of the oldest and least recommended options helps new adopters chose the right path. While this depends on your perspective, I think moving the needle slightly in favor of committers and new adopters is beneficial for the future of the Platform, even if there is some impact for legacy code consumers. - In this particular case, the Platform API removal process was not completely followed [1, 2]. The removal is being reverted for the next Platform integration build. The API may still be removed in the June 2017 simultaneous release, so if you have already taken steps to adopt the changes, consider yourself ahead of the game :) It is important for API removals to be widely announced, and a justification given to the community who will be impacted by it. I apologize for this not being done in this case. - On the topic of semantic versioning, there is no easy answer. Incrementing the major version number of a bundle in the Platform is guaranteed to have a massive impact on adopters, even if they did not use the particular API that was affected. Nearly every annual release of the Eclipse Platform has had some very minor API breakage, which is always carefully documented in the migration guide. If we strictly followed Semantic Versioning, the major version of much of the Platform would now be around 12 or so by now, and adopters would have learned to completely remove the upper bound from their version ranges to avoid being constantly broken at the bundle metadata level. What we have always done in the Platform is try to have the version numbers reflect the anticipated overall impact on clients. In most release, the API is 99.9% compatible and we don't let the rare exception dictate the overall version number. I still believe this approach minimizes the total impact on consumers, but if the community feels a stricter interpretation of SemVer is more valuable, it is worth discussing. Links: john
|