Please provide a stable API!

[rsoika]

Today, unfortunately, I have to criticize the GLSP project. I have been working with GLSP for 2 years now. The main problem I observe is that there seems no point in time with a stable API. My impression is that to many things change with each release.
I've been working with a nightly build in version 1.1.x for a very long period of time and was really hoping for version 2.0. This felt like version 2.0.0 had a half-life of a few seconds and now I'm working again with a pull request in version 2.1.x

It looks like all sorts of things are always changing - permanently. A good example is the integration with VS-Code or Eclipse. I'm really desperate. I have 5 different variants of integration code about ContainerConfiguration and GLSPStarter classes. And again, I can't put things together. Everything is broken again.

So PLEASE: keep the API stable!
Of course, as a developer, you always have new ideas and improvements in mind. But an open source project also thrives on its stability and reliability. Please stop changing the API all the time.

I'm really afraid that you're already working on version 3.x and everything I've been doing for weeks with the migration to version 2.x will then become obsolete again. Please tell me that you don't....

[planger]

Thank you very much for your continued engagement and support as a long-time adopter of Eclipse GLSP! Your feedback is incredibly valuable to us. Your dedication and efforts in keeping pace with the GLSP updates, especially during the transition from version 1.0 to 2.0, have significantly contributed to the evolution and improvement of GLSP.

We acknowledge that the API changes from 1.x to 2.x were rather substantial and understand the challenges they might have presented. Our goal with the 2.0 release was to enhance and consolidate our existing API. This process included the transition to Sprotty's 1.x stream, which, unfortunately, necessitated some API breaks. Recognizing the inevitability of API breaks, we used the opportunity to incorporate as many API improvements as possible, aligning with our roadmap. This move, while causing immediate migration efforts, is aimed at ensuring long-term stability and reducing the need for major changes in the future.

API development is indeed a balancing act – we constantly aim to create an easy-to-use API while considering maintenance efforts and the convenience for our adopters. As GLSP matures and gains broader adoption, we are committed to introduce a new strategy from the 2.x version onwards:

• We plan to roll out a new 2.X version every three months, designed to be non-API-breaking.
• Our commitment is to the 2.X stream for at least the next 12 to 24 months, so you can be assured that a 3.x version is not on the horizon anytime soon. However, this doesn't mean a halt to new features (see the next point).
• New features will initially be introduced as optional, experimental components and will be fully integrated into the fixed API only after their stability and API have matured (see feature table).
• In scenarios requiring API changes, we are dedicated to maintaining backwards compatibility for a longer duration, along with clear deprecation warnings, to minimize migration efforts for our adopters.

Our aim with these measures is to significantly reduce, if not completely eliminate, the migration effort for our adopters in the coming years.

Regarding the issues you've encountered in migrating from 2.0 to the yet-unreleased 2.1 on master: We're releasing 2.1 in the next 1-2 days. This update is designed to be free of API breaks, making the migration process smoother. Should you encounter any issues post-release, please don't hesitate to open a new discussion topic. We're happy to support you through your migration.

Your feedback and experiences as an adopter are crucial in shaping GLSP. We very much appreciate your understanding and patience through these updates!

[rsoika]

Thanks for your feedback. I totally understand you situation and I hope it's only now that I run through all the trouble.

Anyway - my migration to version 2.x (2.1.x) was successful so far. And in deed I was able to remove some of my old code which always indicates that the new API becomes better.

[planger]

Thanks a lot for your understanding and also for your continuous feedback! Very much appreciated! And let us know if you run into any issues. From now on, the evolution shall be rather smooth. :-)