search

eclipse-lyo / lyo.client

Lyo project repository (lyo.client)
11 stars 16 forks source link

Rename oslc4j-client to lyo-client and refactor #106

Closed berezovskyi closed 3 years ago

berezovskyi commented 3 years ago

Rationale: we are trying to have all projects be named lyo-xyz and drop OSLC4J. I am also constantly confused with which of them is new and which is old.

Action plan

jamsden commented 3 years ago

I guess, but it's API breaking. The pattern as oslc4{lang}-client back when Lyo was intended to support multiple languages. Might be better to leave it a lone.

berezovskyi commented 3 years ago

Now, the REAL problem is not a pesky package name but that the old client uses namespace org.eclipse.lyo.client that we'd really want for the new client and I suspect Jim just added oslc4j in both places as a simplest workaround possible. I don't like that but I don't have an immediate solution. Better ideas are welcome, if I like it I promise your initiative won't be punished (ie I will do the work). @isccarrasco your suggestions and from your colleagues at Koneksys are welcome too!

Another thing I am really not happy about is that all exceptions and resource classes were duplicated and now we'll have to deprecate them twice (strange that we are releasing classes that were never released before as deprecated right from the start). I see no need for that. I think we can easily extract them into a common package that both the new and old client would depend on this common package.

Finally, the reason I am raising this is because we will be stuck with it all the way till 5.0.

P.S. An answer to the Jim's reply he posted while I was drafting it: 4.0.0 is not yet released so no API breakage is there. Anyone who depends on SNAPSHOT does that at their own risk 🤷‍♂️ Finally, I don't want to add a new package with the name that follows oslc4{lang}-client exactly becase that's the old convention.

jamsden commented 3 years ago

I'm ok with your suggestion.

berezovskyi commented 3 years ago

Regarding package namespace suggestions, I will go first with 3 non-ideal suggestions:

  1. Do not add the new package name and simply co-exist in the old namespace. It will be a bit "cramped" till 5.0 but will get resolved nicely. Example: org.eclipse.lyo.client.oslc namespace is there, we don't touch it but all new client code to org.eclipse.lyo.client and call it LyoClient instead of OslcClient. I think this is the idea I like most.
  2. Go with Jim's workaround (I am only talking here about org.eclipse.lyo.client.oslc to org.eclipse.lyo.oslc4j.client change) but use a neutral term like next, vnext, v4. Not bad but the problem is that we'd have to move new code again in 5.0 so I am not happy with 2 breaking changes.

So, the final suggestion:

  1. oslc-java-client stays with the same name, package namespace (org.eclipse.lyo.client.oslc), and a bumped version 4.0 but with all classes under client.oslc and client.jazz deprecated.
  2. oslc4j-client is renamed to lyo-client and org.eclipse.lyo.oslc4j.client code is moved to org.eclipse.lyo.client. Note that oslc is missing at the end and this is how we avoid clashes technically. Also, classes are renamed from OslcClientXYZ to LyoClientXYZ; this is how we signal to developers which classes to use.
  3. client.exception and client.resources are moved into two differnt packages (read below why) and previously discussed deprecations are made to client.resources because lyo-domains is preferred.
  4. oslc-java-client depends on lyo-client-base (where I will move client.exception code) and oslc-java-client-resources (where client.resources will go). However, lyo-client will only depend on lyo-client-base and users will be advised to depend on lyo-domains BUT they will be able to also load oslc-java-client-resources if really needed.
berezovskyi commented 3 years ago

Haha, the third non-ideal solution got lost along the way :)

berezovskyi commented 3 years ago

One final suggestion is to make a 4.0.0.M2 release before that to provide a temporary but reliable workaround for all the SNAPSHOT code out there.

jamsden commented 3 years ago

I prefer Oslc over Lyo prefix because it has stronger functional cohesion. Lyo is a project while OSLC is a technical architecture and standard. The API is for the standard, not the project. You can drop the 4j, its obvious its java. That might make the old and new easier to distinguish.

berezovskyi commented 3 years ago

oslc-client is fine with me too

are we in agreement over the rest of the points?

berezovskyi commented 3 years ago

Just discussed with Jad and OKed. With Jim's change the final plan is:

  1. oslc-java-client stays with the same name, package namespace (org.eclipse.lyo.client.oslc), and a bumped version 4.0 but with all classes under client.oslc and client.jazz deprecated.
  2. oslc4j-client is renamed to oslc-client and org.eclipse.lyo.oslc4j.client code is moved to org.eclipse.lyo.client. Note that oslc is missing at the end and this is how we avoid clashes technically. Also, classes are renamed from OslcClientXYZ to LyoClientXYZ; this is how we signal to developers which classes to use.
  3. client.exception and client.resources are moved into two differnt packages (read below why) and previously discussed deprecations are made to client.resources because lyo-domains is preferred.
  4. oslc-java-client depends on oslc-client-base (where I will move client.exception code) and oslc-java-client-resources (where client.resources will go). However, lyo-client will only depend on lyo-client-base and users will be advised to depend on lyo-domains BUT they will be able to also load oslc-java-client-resources if really needed.