Separation of Examples and API Code

[rsoika]

First of all, I would like to emphasize once again how great this project is! In my eyes it's certainly one of the most powerful modeller projects we have.

But after working more than over a year with GLSP I want to suggest to separate the examples code form the API. Maybe you already have this in mind, but currently the core APIs like glsp-server, glsp-client, glsp-vscode-integration or glsp-eclipse-integration all include example code. But this, I think, is for beginners (and still for myself) very confusing.
It looks that I am forced to checkout/clone all these project parts to get started. But this is not the case. And you already have the new glsp-examples project. So why not throw out all the example code from the core APIs?

I am currently working on Eclipse and VSCode integration code and it is still very confusing that the corresponding APIs are mixed with example code. This makes it hard to adapt.

For example: The glsp-vscode-integration includes example code that assumes you have a Java-Server and a NodeJS Server. No one would implement two language servers just for fun in his own project. So I would suggest to move the example/workflow code from the glsp-vscode-integration into the glsp-examples project and separate it in two examples:

• workflow-vscode-integartion-java-server
• workflow-vscode-integartion-node-server

I would do it myself if it would not take me weeks to get the project setup right. It still takes me hours in my own project to figure out which dependencies are necessary and which are not. I also think that many questions often arise because the line between framework and adaptation is blurred by mixing api with examles.

[srcnuzn]

I totally agree, getting started was quite confusing with all the different examples distributed on different repositories. Having one centralized, up-to-date examples/template repo is very helpful. I think it is also easier to maintain.

[planger]

Thank you very much for the feedback! I agree with you that a separated example is much easier to follow than the ones in the respective "core repos" or "integration repos".

Our hope was that the project templates and the separated workflow example fulfill this purpose. We update these after each release. Do you think they are insufficient? What are they missing?

The examples in the respective core and integration repos are actually not really intended to be an example for educational purposes but rather an example for the GLSP dev team to test the core and integration repo functionalities. If there is a bug fix or a new feature in development, it is handy to have a common example we all use for reproducing the issue or demonstrating the correct functionality. This is what the purpose of those examples are.

However, it is important that people have what they need to get started, so we appreciate any suggestion or also of course PRs to add / enhance / change the new or existing examples.

Thank you!

[srcnuzn]

Hi @planger, here's a short version of my experience with the examples/documentation:

The getting started guide was very helpful in quickly finding the right template project (java-eclipse-emf) for my needs. Unfortunately, the example didn't work at that time due to a small bug (which has already been fixed though 👍🏼).

Since I didn't have a running template then, I started looking into other repositories. Seeing all the examples in those repos, I wasn't so sure anymore which one to use and which one is well-maintained. So, I made multiple attempts to modify other examples to suit my needs (getting-started), but I failed. Anyway, now that the java-eclipse-emf template has been fixed, I could quickly get it running and replace the tasklist model with my own source model ✅.

Currently, I'm working on the next steps, i.e. visualizing the source model as required. Here, I'm struggling with the GPort elements, their layout, and some options (see my other post). The problem is that I'm not always sure whether I really understand and use the layout options/concepts correctly or if there is a bug. 🤷🏼‍♂️

With that experience, I have the following suggestions/ideas:

• The templates/examples should be equally well maintained, i.e. use the latest versions. The versions should be synchronized between different examples, such that one example does not look "more up-to-date" than the other.
• It should be clear which purpose an example serves. If this purpose is fulfilled already by another existing example we should drop one example or merge them into a single one.
• We should extend the documentation with even more images/GIFs/code to show how the code/options are influencing the visualization. The existing images and code snippets are very helpful 👍🏼
• The documentation could go hand in hand with the templates, such that we can simply copy/paste code from the docu into the working template to quickly get a first hand experience.
• We should add all the basic graph elements into the project templates, e.g. the the tasklist example only shows nodes, but edges and ports are completely missing, which quickly leads to follow-up questions.

I hope this helps somehow 😄

[planger]

Thank you very much for your feedback! It surely helps to understand where newcomers are struggling.

Would you agree that much of the confusion is coming from the fast that all the examples in glsp-examples (project template and workflow example) are built against the latest release, whereas the examples in the core repos (glsp-client, glsp-theia-integration, etc.) are developed against master? Thus, you may run into issues when trying to copy code from the glsp-client into a clone of the project templates.

Our strategy is that glsp-examples is always up to date with the latest release (1.0.0 in that case), where as everything else is up to date with the latest master (and thus the release candidates). Keeping the glsp-examples up to date with master would add too much overhead if we need to do that on our own. Also, it would be confusing if someone starts with a project template and happens to be in a state that is built against a non-released version (which also has much more API changes). Thus, we decided to update them only once per release. The same is true for the documentation, we have a 2.0 branch there, but the published doc (which is master) is up to date with the release only (1.0).

We should extend the documentation with even more images/GIFs/code to show how the code/options are influencing the visualization. The existing images and code snippets are very helpful 👍🏼

Great idea! I'll keep that in mind! If you happen to be able to enhance the docs in this regard, we'll be happy to integrate your enhancements!

The documentation could go hand in hand with the templates, such that we can simply copy/paste code from the docu into the working template to quickly get a first hand experience.

Also a very good idea!

We should add all the basic graph elements into the project templates, e.g. the the tasklist example only shows nodes, but edges and ports are completely missing, which quickly leads to follow-up questions.

I understand why this is useful. However, we also received feedback that this will pollute the template making it less useful for starting a new GLSP project, because more has to be removed/changed.
Our thinking was a bit that the workflow example covers a large part of the features, whereas the project templates are just the minimal project setup to act as a starting template.

WDYT?

[rsoika]

Hi @planger , I think the confusion is maybe caused by the fact, that sometimes solutions discussed in this forum are based on newer or at least different versions. For example our own project is based on version 1.1.0 now for one year. And we are still working with Release candidate versions. In the last weeks I personally struggled again because of API changes between RC04 to RC10. Finally I was lucky to get it solved. But for things like the eclipse-integration, I gave up totally. For such work you have no other change than to look into examples in the core repos and the corresponding branch/RC-candidate. But for users like us it is nearly impossible to get through all the different versions.

I know that it is difficult to manage different versions in such a project. And my hope is, that the final version 1.1.0 will be released soon. If the API becomes stable, I expect that things become better and better over the time as we than all discuss the same API and example code.

But when I read about version 2.0, I'm a little bit horrified. Does this mean the API changes again....? You know that I value this project very much. But we need a stable API and my hope is that the final API is now included in 1.1.0.RC10.

[planger]

Thanks @rsoika, that makes sense! I know that API breaks are very cumbersome for adopters. We surely try to keep them at a minimum, but as you know it is always a compromise between clarify, maintenance effort and work for migrations of existing products.

1.1.0.RC10 will eventually become 2.0.0. As 1.1.0.RC10 contains API breaks relative to 1.0.0, it must be 2.0.0 once it is released. So there is no to very little API breaks to be expected from 1.1.0.RC10 to 2.0.0, which will be released in 1-2 months. After that's released we'll certainly put more emphasis on avoiding API breaks.

Our hope was that the changelog, which lists the PRs that breaks API, helps to migrate existing products, as those changes also contain the changes that have been required to the workflow example. Does this help? Or is this insufficient to see what needed to be changed on the workflow example from one version to the next one?

Thanks again!

[rsoika]

Yes, in deed the documentation was good and most the comments in the @deprecated annotations helped me to get through very fast. Also I noticed that code becomes more simple and some of my code could simply be removed after RC10. So - good work - thanks!
I only was shocked in the first moment after I switch to RC10 that my code no longer compiled - that was an unexpected situation. But I know this kind of difficulties with innovation in my own project ;-)
So go ahead and follow the Open Source rule: release fast and early.