New API for Ratings

Development
#1

Hi everyone,

as part of my work on Likes I have started in 12.7 to work on the Ratings extension, to allow using it for Likes, and first I started to notice some problems in the API, and second after talking with Vincent it appeared that we might want to re-design it in order to allow generic ratings usage throughout XWiki.

With all that in mind, I wrote a design page to summarize the usecases I would want for a Rating API taken into account the already existing API and the needs I discovered with Likes, and the ones discussed with Vincent. Here’s the design page: https://design.xwiki.org/xwiki/bin/view/Proposal/RatingsnewAPI

Based on that, there’s several choices that I want to discuss here to ensure we agree on them.

Proposal 1: create a Rating API that allows to create instances of RatingManager

That’s the actual basis of the discussion on this new design (UC1 of the design page): the idea is to be able to create a Like extension (at least the backend) just by instantiating a new RatingManager with some information.
Do we all agree on that?

Proposal 2: Move the actual Rating extension to the attic and create a new one

I’ve not put it in the design page yet, but it seems to me that it would be far more easy to move the actual Rating API extension to the attic and develop a new one, compared to deprecate stuff / put it in legacy and move like that.
The reason is that preserving the backward compatibility here won’t be really easy, especially since there are very few tests and that I want to drop some support (see below).
So basically if I want to keep the actual API and work on it, I’d need almost to first cover it with test before starting the changes. It’s doable, but I think I will lose lots of time for doing it.
Also note that Rating API is not recommended (as well as Rating Extension).

So do we agree to move the actual Rating API to the attic (pretty sure it won’t be needed for the Rating UI) and to create a new one?

Note that we could decide to rename the parent module xwiki-platform-rating (instead of xwiki-platform-ratings) and to create a new Rating API named xwiki-platform-rating-api: we would avoid name conflicts and keep a good name.

Proposal 3: Dropping support of storing Ratings info into xobjects

One of the reason for proposing to move the existing API to the attic is also to drop support of storing Ratings as xobjects. This is clearly not a scalable solution for storing such information.

As proposed in the design page (see UC9), I propose that we allow first storing Rating information in Solr since it’s already implemented, but we can also improve it by providing a dedicated hibernate mapping for Ratings.

Note that this drop of support of xobjects also imply necessarily a migration tool for old ratings (See UC13)

New design open questions

Besides those proposal there is also a few open questions in the design page that I’ll try to summarize here to simplify the discussion:

  1. Do we want to keep supporting the Users’ reputation usecase (UC11): I’m personally not sure if it’s needed or not, it’s not really documented or used in the current extension AFAICS.
  2. Do we want to allow Admin to change the Storage of Ratings (see UC9), or do we want to consider that several storage implementation are provided for Ratings and it’s the developer of the extension who chose which storage will be used? Note that allowing Admin to change the Storage would imply to have the migration mechanisms.
  3. Do we want to have a Rating Right to be configured globally, or do we want to be able to have custom Rights depending on the RatingManager instance (e.g. a Rating Right, a Like Right, etc) (see UC10)

Thanks.

#2

Recommended means supported by the XWiki dev team, and everything in platform is supported by the XWiki dev team. So I’m not sure why you say it’s not recommended.

Why not consider it just as another storage alternative?

#3

Indeed I’ve not been clear enough. So 2 things:

  1. the Rating API until 12.7 was not bundled in XS by default (now bundled because of the dependency on Like)
  2. the Rating Extension is not marked as recommended on https://extensions.xwiki.org/xwiki/bin/view/Extension/Ratings%20Application so it might make it a bit less used right now (and I guess it’s a mistake)

Because I don’t think we want it on the long term: as already said it badly scales and if we want to support it along with other storages it means also to have the migration support in both ways. Moreover it’s more maintenance for us if we keep supporting it.

#4

It also means rewriting tools which rely on it like Extension Repository app (extensions.xwiki.org).

#5

Extension Repository doesn’t rely on Rating API, but directly on the Rating xobjects? If it relies on Rating API then it’s less a problem: we have a the choice to refactor the app when we chose to migrate it to the new API, the old one would be still available with the latest version published.

#6

It manipulates directly the AverageRatingsClass object in a few places (the livetable, the solr index, the extension class rating computed field) where it was not really possible to use the API I think (maybe not for the last one).

#7

Ok that’s good to know and indeed something to check then. Adding a use case for it in my design page.

#8

So I started to work on the implementation of this new API as part of https://jira.xwiki.org/browse/XWIKI-17761 in a dedicated branch.
First of all we need to agree on a new naming for this module, I proposed in my original post to use xwiki-platform-rating (without an s), but now I’m thinking that it could be possibly error prone, and that might be better to clearly express that it’s a new API.

For my first implementation, I used xwiki-platform-ranking with the usage of Ranking instead of Rating everywhere. I’m not completely satisfied by it, and we need an agreement about this name, so tell me what you think about it.

For information, for now the implementation follow the design I proposed on https://design.xwiki.org/xwiki/bin/view/Proposal/RatingsnewAPI except for the following point:

#9

I agree but I don’t have anything better than “ranking” to propose right now.

#10

Actually just got a suggestion for using “grading”, wdyt?

#11

Yes it’s better than “rank” which is more about ordering than the values.

#12

From what I see we don’t have any “Grading” extension either, so we shouldn’t have any issue of name conflict.
So it would be xwiki-platform-grading.

#13

I need to read all this thread but at first sigh “ratings” seems better than “grading”. Isn’t there a way to rename the current maven modules/artifacts and instead use “ratings” for the new API? Also, couldn’t we do version “2.0” of the ratings API instead (without an alias to not have an automatic upgrade)? And users wanting to use the old api would use version “1.x”? I haven’t really thought through about this so these are just open questions, to make sure we’ve considered them.

I think the first thing to agree about is: " Proposal 2: Move the actual Rating extension to the attic and create a new one"

I don’t see any agreement yet (haven’t seen any preference about the 3 proposals yet from committers).

On my side I haven’t read the thread yet (just skimmed quickly), and I need to take the time to read it.

#14

I don’t understand this suggestion: Ratings is already the old name.

Same here could you be a bit more specific by “version 2.0”? versions are following XWiki Standard versions there…

Yes I really need agreements there so I can move on.

#15

Yes.

After some pondering, I think I’m fine with that if you think it’s faster this way. We will still need to provide a migration path for existing users.

BTW what is your proposal for the migration process? How is it triggered for users? How do they decide to upgrade? In the vast majority of cases users will want to upgrade, so how do we make that easy for that? This is why I was hesitating since if we keep the same extension id (or if we add an EM alias) then users can get an automatic upgrade.

Since we decided to use a NoSQL (Solr) solution for likes I think it’s the same for ratings. The same downside than for likes still apply (basically we loose all the wiki features: simple edition for fixing mistakes for ex, history, rights, refactorings, etc). Overall I don’t think we have a choice if we want a scalable solution though and I see ratings/likes in the same domain as statistics and notifications.

Note: @Enygma raised the issue in some jira issue where we started a discussion about NoSQL vs RDBMS (and XWiki’s model). Basically we need to agree when it’s ok to use NoSQL for storing data and when we should store them in XWiki’s RDBMS. TODO: Find the jira link and paste it here.

@Enygma would you be ok on your side for storing ratings data in a NoSQL place? (I know that you consider that the NoSQL - Solr - we chose is not the right one, but disregarding this, do you agree that storing ratings in a NoSQL store is the way to go?).

I think NoSQL is a better candidate than RDBMS for a topic like ratings (and notifications too). It scales much better in perf for large volumes.The volume is quite large because:

  • For page ratings, we can have up to (number of users) * (number of pages). For ex on a wiki with 3M pages and 120K users, that 360 billions dataset.
  • Ratings can be extended to topics other than pages: ratings for comments, ratings for users, ratings for specific apps (e.g. The Idea application could be refactored to use ratings for the proposed ideas). So that increases the volume a lot too.

Extensions bundled in XS are not marked as recommended voluntarily on e.x.o as we don’t them to be listed on the Recommended Extension page. Now for https://extensions.xwiki.org/xwiki/bin/view/Extension/Ratings%20Application since it’s not bundled by default, it’s indeed a mistake that I’ve just fixed.

I’ve also fixed https://extensions.xwiki.org/xwiki/bin/view/Extension/Ratings%20API which was showing the active installs (we don’t show active installs for extensions bundled in XS since that doesn’t mean anything then).

I don’t know what we were doing with it. This needs to be researched. My recommendation is to find xwiki users that would act as stakeholders and ask them (for examples I’m sure some users from XWiki SAS would be ok with that, and they’re probably the ones using the ratings API the most).

I don’t understand this part:

or do we want to consider that several storage implementation are provided for Ratings and it’s the developer of the extension who chose which storage will be used?

If the dev of the extension chooses the storage then there’s only one.

AFAICS we would implement only 1 storage for the new ratings api. However, I definitely agree that we need to make the store pluggable. It’ll be up to the implementer of the second store to provide the migration path, if needed.

It has to be specific (it’s a consequence of UC1) since Ratings can be used to rate various topics (pages, comments, users, specific app data, etc), and having a single right is going to be too limited IMO.

Note that a consequence of UC1 is that we’ll probably need an Admin UI for Ratings that lists all the ratings instances in the wiki, with admin configurations for each (like rights at least).

Side note: the current ratings api/app was supporting multiple rating instances in some ways, by being able to be installed in various wikis (like any app), since it was storing its data in wiki pages.

Some wild idea:

  • What about renaming the artifact ids when moving the ratings api/app to the attic (and use aliases). In any case it’s nicer than keeping xwiki-platform-ratings which is platform related.
  • If someone ever wants to make the old api evolves or fix bugs, they can always release new versions with the new ids.
  • We reuse the same artifact ids in platform.
  • This will propose to admins upgrading XWiki to also upgrade the ratings extensions. This is where it could be tricky. In the majority of cases this is good and this will perform a migration. In some small cases, the user will have code using the old ratings API and will not want to upgrade. Note that he’s never forced to upgraded but it’s easy to make the mistake. Ideally we would need a way to tell EM to not propose an upgrade from version XXX of the ratings extension ids, to version YYY. But this is probably not supported.

This might be too complicated and OTOH using a new name is probably more clear as otherwise when someone talks about Ratings we wouldn’t know off-hand if he/she’s referring to the old api or the new one.

So +1 for grading.

#16

I need to think more about it but some possibilities I’m thinking about:

  • to provide a new step in DW that would detect the presence of a Ratings XObject in DB and would propose to migrate them: since Ratings was released with platform I guess it would make sense and the advantage is that users wouldn’t miss it.
  • another possibility is to perform this detection in the Administration configuration of the new module

What I mean is that new Rating API could provide two storages implementation, let’s say Solr and Hibernate. Now as a developer of Like extension, I could decide to only use Solr for storage. Or I might want to let admins the possibility to chose.

That’s also my feeling. Keeping grading for now unless someone is -1.
Thanks.

#17

Hi everyone! Regarding the naming, Rating(s) was a really nice choice, but I understand we can’t keep it considering it’s a new api / app.

Would it be possible to consider using a variation from rating, such as “Page Rating”, “Rate me”, “Rate it”?

My concern is that if we use the word “Grading” people will not find the app easily (if at all). Users are already accustomed to use the word “Rating(s)” in this context, while “Grading” is more reserved for teaching.

I took a quick look at what other similar apps are named on top of other platforms and found the following examples: Rating, Ratings, Content rating, Rating CustomField, Rate me, Ratings for (product).

On the Atlassian Marketplace for instance I couldn’t find any grading apps, but could see multiple apps for ratings.

I think the bigger the project, the more likely there will be more apps (old and new) tackling the same area.

#18

For me what’s important is:

  • Keep backward compatibility for the old API, i.e. don’t break devs who have used the old API in their wikis for custom development.
  • Have the same name for the api and the app (they’ll be under the same directory anyway so they need a common name).
  • Have the same name in the UI than in the code.

This one is not great since it’s not just about rating pages. The API can be used to rate/grade/score anything. For the apps we’ll see if we provide several apps or a single one. For now, the app is indeed for “rating” pages but but it needs to use the same terminology as the API (same module).

These ones are not good either IMO because again the terminology must be the same as the API and using “rat*” in the API/module naming is too close to the existing one and makes it confusing.

#19

@SilviaMacovei I don’t see any way around it. Either we break backward compatibility or we don’t. If we break it then we keep the same name. If we don’t break it we need a new name that’s different and non-ambiguous.

Actually I proposed a solution above to keep the same name by renaming the old API and Apps. But it depends on implementing a feature in EM: See

#20

Posting here some things mentioned in an off-channel discussion:

  • “grading” hearts my ear, honestly. I think I would have went for something like “scoring”/“score” … “page score”, “user score”, scoring policy, etc., sounds better IMO than “page grade/grading”, “user grade/grading”, grading policy, etc. As an example, Solr uses “score” as well for its search results. It is common to encounter it in other software as well when “evaluating” something.
    • Heck, even “evaluation” would be a better option than “grading”, if we’d really need to use something other than “rating”. It’s generic and common enough to fit most requirements.
  • “Grading” is not really used anywhere in software as synonym for rating, mostly probably because “grading” usually is restricted to actual grades (numbers), while rating applications are usually presented in “stars” (with associated average grade/score). It would really be ideal if we kept “rating” as it really damages the feature to use a non-standard name just because of an internal, technical reason. I agree that grading might fit better, but it is just too off-putting, as it refers a much too formal activity.
  • Honestly, it makes little sense from the usability pov to rename the app on the user side to anything other than the industry standard “rating *”. We need to focus on the user’s experience, not break it for the sake of a developer issue that can be handled by devs. Yes, we need to take care of the upgrade path (provide a migrator/migration path to the new app) but in a way that does not sacrifice the user’s expectations and introduces a name that would distract too much from the point of the application.
  • “rating”-related suggestions:
    • “Global Rating Application”, “Generic Rating Application”, “Universal Rating Application”
    • “Better Rating Application”, “Improved Rating Application”, “Modern Rating Application”, “Scalable Rating Application”, “Redesigned Rating Application”, “New Rating Application”
    • “Standard Rating Application”
    • “Rating for XWiki Application” (based on one of Silvia’s suggestions)
    • “Rate Everything Application”, “Rate Anything Application”, “Rate All Things Application” (“RAT Application” :smiley: ) :slight_smile:

If I were more invested in this current effort, I’d be -1ing “grading”, but since I’m not, I’m just "-0"ing it for the moment. I know it’s annoying, but it really feels like a bad choice and we need to come up with something better, since it’s a mess to change later (“cache invalidation and naming things”).

The problem/question with these “app replacements” is what happens when “appA” depends on “ratings1”, we replace “ratings1” with “ratings2” in XS and, at upgrade, the user ends up with both “ratings1” and “ratings2” installed because “appA” was not really updated by its dev to use “ratings2”? Most likely the 2 “ratings” applications will not play nice together and it wouldn’t be that feasible to uninstall the new “ratings2” app because XS now depends on it. Do we make it “optional”? Then we’d break XS. AFAIR, for notifications, we’ve handled that with feature flags to be able to disable notifications on systems not wanting to upgrade from watchlist, but that’s quite a pain and it creates a bit of junk that we then have to carry around (the flags themselves, configuration and checking).

Thanks for your patience, Simon. I know these things can get frustrating.