Community
Participate
Working Groups
Zest started out as a research project, and over the past few years we have learned a lot about creating graph APIs. To help improve long term maintanability, foster adoption and help scope the Zest project, I propose we harden the Zest API during the GEF 3.6 lifecycle. In particular, I propose we move from Zest 1.1 to Zest 2.0. It is not my intention to re-design the spirit of Zest API, but I would like to fix some of the "mistakes" we have made. For example: 1. The Zest API is supposed to mimic the SWT/JFace one. In some cases, this has not happened. I would like to bring the Zest API closer to the SWT one. 2. There are some public classes that have no function. I would like to remove these. 3. There are some public API that don't work, and for a number of reasons, cannot work as documented (non overlapping nodes in a layout algorithm for example). In these cases, I would like to remove the API (since it doesn't work anyways). 4. Some of our packages are named incorrectly. 5. The Zest API has never been reviewed by anyone. I would like to solicit the help of some senior developers to help review our changes. Since the Zest project is growing (we have two students helping with it this summer) I think this is a great opportunity for us to solidify the Zest API.
The guidelines here should be to deprecate the old API and add new ones. Current guidelines from the architecture council is that deprecated API needs to stay in for two years.
Zest has been in the field for effectively two years and I do not think it is a good idea to go back and break anything. Just changing from version 1.1 to 2.0 causes everyone using Zest in Ganymede/Galileo to have to rebuild their bundles for Helios. No bundles will be portable to the next release. What you are proposing is a major breakage and should not be entered into lightly. Are existing Bugzillas from the community for the API issues you list? I propose we look at the API in a case by case basis.
The biggest changes I foresee are actually in the layout project. Unfortunately, the entire project was marked API, however, I doubt very many people do more than just: new LayoutAlgorithm(some style). Mateusz has done a very good job of refactoring the old project, but it is completely incompatible with the new project (except you can still say new LayoutAlgorithm()). For most people, it won't be a big change (although it will require anyone using Zest to rebuild their projects). From talking to members of the community, the biggest problems people have with Zest is a result of the layouts. The current layout project has stalled development as we cannot add the new features and fix the existing problems without completely breaking everything. Now, we could mark the entire old project as deprecated, and release the new project. Although, for Zest to support both versions of the layout package (without breaking API) would create a mess. It could be done, but drawback of creating this mess, IMHO, does not outweigh the benefits of maintaining binary compatibility in the layout package. (And when I say it could be done, I mean technically, it's probably not feasible given the size of the Zest team). I talked with a few members of the AC today, and I was told that the two year deprecation policy is a guideline, and the maturity of the project, benefit of the change, etc.. should all be considered when making the decision. I believe that the stability of the Eclipse API is the primary reason Eclipse is so successful as a platform, and maintaining stable APIs should be a goal of all Eclipse projects. However, I don't think that API stability should come at the cost of stalling development or stifling innovation. Even the platform project (and gef for that matter) has gone through 2 major version upgrades -- so clearly breaking APIs for the betterment of the project has value. Finally, I agree that looking at breaking API in a case by case basis makes sense. Beyond the layout, the API changes are minimal (but none-the-less breaking).
(In reply to comment #3) > The biggest changes I foresee are actually in the layout project. > Unfortunately, the entire project was marked API, however, I doubt very many > people do more than just: > > new LayoutAlgorithm(some style). If this is the case, perhaps we can leave at Zest at 1.2? If all the snippets work as is, then perhaps we do not need to update the major version. > [...] However, I don't think that API stability should come at > the cost of stalling development or stifling innovation. Even the platform > project (and gef for that matter) has gone through 2 major version upgrades -- > so clearly breaking APIs for the betterment of the project has value. I think the part that is missing here is that the platform provided a compatibility layer for existing API customers
If we leave Zest at 1.2 but move the layout package to 2.0 then consumers will have to rebuild their packages because of the major number increase of the layout project. So I'm a little confused about the problem: 1. If the problem is the need to continuing shipping products that depend on Zest without a rebuild, then we can increase our Major numbers and customers can choose to use Zest 1.1 or Zest 2.0. If consumers have properly defined their ranges [1.0, 2.0) for example, then they will get Zest 1.1. If we really need to, we can ship both versions with Helios (although the galileo site also holds these versions). 2. If consumers don't mind recompiling (but are not able to make source changes), then we could try and maintain source compatibility. I'm a little hesitant of this approach since users can again define their ranges [1.0, 2.0) or [2.0, 3.0) and choose the version of Zest that is right for them. (Note: We can't do this with the layout package, but I doubt most people are doing much more than instantiating layouts.). Also, regarding src compatibility, we have problems with our package naming (we have internal in the wrong segment) and fixing this will cause source breakage. If it is an absolute must that we maintain src compatibility in the Zest core (but can break binary compatibility), then we can peruse this. However, I would like to understand what problems this solves. Projects get very little opportunity to solidify their API and I would like to do this once-and-for all. In the end, by increasing bundle version numbers, consumers have the freedom to choose the the version that's right for them. I've added Jeff as a CC since he has lots of experience with bundle version numbers and compatibility.
(In reply to comment #5) > [...] If consumers have properly defined > their ranges [1.0, 2.0) for example, then they will get Zest 1.1. This is exactly the issue, existing Zest customers will have their range set to [1.0, 2.0), so a Zest 2.0 will break 100% of existing customers. We can be a little more flexible here. If 90% of Zest users only call new LayoutAlgorithm(some style), even though we may have "disabled" some of the API, in Zest 1.2, 90% of Zest users are not broken. Yes I realize if we use the eclipse version guidlines they say that if I break one API I need to increase the major version. I am saying to be a little more flexible and not break 100% of the community if we can bend the rules and only break 10%.
My opinion on this is simple... Zest is still young and needs to evolve. The whole Eclipse world doesn't depend on it yet (like GEF which needs to be more sensitive). As one of the project mentors, it's my mistake for not getting the Zest team to mark their APIs as provisional. My recommendation is that the Zest team move up to 2.0 and create a guide. I would expect the Zest team to come up with a porting guide... similar to what Mylyn did when they went from 2.X to 3.0 http://wiki.eclipse.org/Mylyn/Porting_Guide/3.0 If this is still viewed as too much, the Zest team has an option of having two streams... 1.X and 2.0 but I discourage this. In the end, it should be up to the committers and project leads to make this decision.
My job unfortunately is to make sure the code our communities products and customers wrote for Ganymede and Galileo works in Helios. This is not all doom and gloom as you say, we can deliver all the 2.0 changes we want, we just need to find a way so that 1.0/1.1 clients can continue to function in Helios.
(In reply to comment #7) > The whole Eclipse world doesn't depend on it yet (like GEF which needs to be > more sensitive). As one of the project mentors, it's my mistake for not getting > the Zest team to mark their APIs as provisional. My recommendation is that the > Zest team move up to 2.0 and create a guide. I am not aware of any documentation indicating the Zest component we released as 1.0 in Ganymede being presented as a component that was provisional. The facts are that the "whole Eclipse world" will have used Zest for two years on the API we gave them in 1.0 and 1.1, we cannot break 100% of them when Helios releases.
So here's my suggestion: 1) create a 2.0 and release it with Helios 2) maintain a 1.X stream for a release or two telling people that it will be deprecated in favor of 2.0 3) create a porting guide so people know what to do when moving to 2.0 Otherwise, we are handicapped.
(In reply to comment #10) > So here's my suggestion: > > 1) create a 2.0 and release it with Helios > 2) maintain a 1.X stream for a release or two telling people that it will be > deprecated in favor of 2.0 > 3) create a porting guide so people know what to do when moving to 2.0 > > Otherwise, we are handicapped. > This aligns exactly with the two year deprecation policy the foundation is proposing through the architecture council. This would be a fair compromise over supporting 1.0 APIs forever.
As we have decided to continue the development of Zest 2 in terms of GEF4 component(s) (see bug #372365 for details), this is no longer an issue. Zest 1.x will be handled similar to Draw2d and GEF (MVC) 3.x, and may thus ultimately be replaced when we turn GEF4 into the official next major GEF version.
