Change the ranking/level system

[LucBerge]

I just discovered your repo and it is exactly what I need to create my user repo and user readme. Thank you for the amazing work you are doing here !

Is your feature request related to a problem? Please describe.

I'm surprised by the ranking system currently used:

• B+ everyone
• A++ top 60%
• A+ top 45%
• S top 25%
• S+ top 1%

Most of the people who will see a github stats card like this won't understand the ranking system or will not understand it correctly. For me, A+ means really good user (or code quality) if you consider the ABCDEF ranking system.

To actually understand your ranking system, you need to click on the card, start reading the readme and find a little note explaining it.

The ranking label on the card must be obvious for anybody reading the card, whatever the job, nationality, education or culture.

Describe the solution you'd like

Proposing my own ranking system won't be the ideal solution too. It will have a global impact on everybody, so I think the community itself must debate to find the right ranking system !

Describe alternatives you've considered

Instead of a ranking system, you could just display the user rank in percentage:

Additional context

If you think this issue is relevant, consider pinning it so everybody can contribute.

[rickstaa]

@LucBerge Thanks for your feature request. I agree with you that the ranking system is weird, and I think we are not the only ones since there have been multiple proposals and PRs open that try to improve the ranking:

• Change the ranking/level system #2265
• Yet Another Proposal for Calculate Ranks #1560
• Suggestion for more ranks or a different raking system. #1579
• Improve ranking system #455
• Ranking System v1 #960
• Ranking System v2 #1186

I think three things can be improved about the ranking:

• Switch to a more commonly used grading system (i.e. A-F, A+ to F or % based).
• Show top-users percentage on hover (see Grade description in the report card. #2157).
• Improve the rank calculation (see Missing term in calculation of TOTAL_VALUES. #2116 and Ranking System v2 #1186).

@anuraghazra I think we can merge #2116 and #1186 and switch to the A-F or A+ to F ranking system?

[rickstaa]

This is one of our most requested features, so I have looked at it (see #1935). I, however, would like some feedback from @anuraghazra before merging #2116 and #1186.

[LucBerge]

In this issue, I'm only talking about the displayed values, I'm not questionning the model behind.

You first have to deal with the computation method before moving to the displayed values.

For now, the propositions are:

• Yet Another Proposal for Calculate Ranks #1560: S+, S, A, B, C, D, E...
• Suggestion for more ranks or a different raking system. #1579: lvl 1, lvl 2, lvl 3, lvl 4...
• Change the ranking/level system #2265: % based
• US ranking system: A+, A, B+, B, C+, C...

What else do we have ?

[rickstaa]

@LucBerge I think the other ones would be the US ranking systems (see https://everydayeducation.com/blogs/news/grading-systems#:~:text=The%20most%20commonly%20used%20grading,100%20instead%20of%20letter%20grades).

• A-F.
• A+-F

I prefer these systems while showing the % based results on hover (see #2157), but I might be biased let's see what @anuraghazra thinks.

[rickstaa]

We also have the Japanese, which I think the current ranking is based on (see https://en.wikipedia.org/wiki/Academic_grading_in_Japan). Since only the S+ is confusing for me, I think this one is also fine, but I think fewer people are familiar with that ranking system. So my vote still goes to the US-based ranking systems If we want to use letters.

[LucBerge]

Well, I didn't know it was Japanese until now...

[rickstaa]

Well, I didn't know it was Japanese until now...

Same for me. I looked it up some months ago. It was the closest one I could find to the one GRS is using. 🤓 Maybe @anuraghazra can elaborate on which ranking system he based the GRS ranks on.

[francois-rozet]

Hello, I don't think the A-F system is a good idea. C, D and F are associated to a bad grade so it would be like "shaming" new devs because they have little contributions.

[ZjzMisaka]

Maybe we can refer to the game rank, after all the developers spent a lot of time researching this

[rickstaa]

Hello, I don't think the A-F system is a good idea. C, D and F are associated to a bad grade so it would be like "shaming" new devs because they have little contributions.

Good point we don't want that 😅!

[rickstaa]

Maybe we can refer to the game rank after all the developers spent a lot of time researching this

@ZjzMisaka Thanks for your input. That ranking system looks good to me very clear. It also is very close to the Japanese game ranking system @anuraghazra is currently using. I think if we extend the current ranking system to your suggestion and add a hover that explains the score, we should be good to go (see #2157).

[rickstaa]

@ZjzMisaka, I think your suggestion is similar to the suggestion given in #1560. I would go for your version since it doesn't include the F grade and is more commonly used. Let's see what @anuraghazra thinks.

[vezaynk]

Giving the lowest percentile a "B+" is bizarre. Based on the popularity of the project, I think it deserves a meaningful ranking system that doesn't use "A++" for half of users.

[Zo-Bro-23]

+1 for this, since A+, A++, S, S+, etc are confusing for me. @francois-rozet has a valid point about C, D, and E though, so maybe we should consider something different. Seeing the current ranks though, A++, A+, A, A-, B+, B, B- should be enough, which solves both the problems.

[vezaynk]

B- to say bottom percentile is weird as well.

Imagine if the top grade this gave was a C+ for top 1%.

Same thing here.

[Zo-Bro-23]

B- to say bottom percentile is weird as well.

Why do you say so? The problem with C and D is that they imply a "bad" user, which is not the case. So we have to make do with A and B alone.

[vezaynk]

C and D only mean "bad" because they're at the bottom. If you make B- at the bottom, it's not any better, just misleading.

[Zo-Bro-23]

C and D only mean "bad" because they're at the bottom. If you make B- at the bottom, it's not any better, just misleading.

Well, the whole point of changing the ranking system is for users who have no idea what GRS is. When someone randomly comes across a GitHub profile, their impression is different for B and C, since they have no idea what ranking system we use.

The same is true for the current ranking system. I have an A+, which might impress people more than if I had an S, since they have no idea what S means.

[vezaynk]

In which case we could give everyone an S++++? You see what I'm saying?

[Zo-Bro-23]

In which case we could give everyone an S++++? You see what I'm saying?

Yes. This is difficult 😕 @rickstaa thoughts?

[rickstaa]

In which case we could give everyone an S++++? You see what I'm saying?

Yes. This is difficult 😕 @rickstaa thoughts?

My vote is with the gaming rank system proposed by @ZjzMisaka (see #2265 (comment)). I think that system togheter with a hover that explains the score solves our problems (see #2157). @anuraghazra what do you think?

[Zo-Bro-23]

In which case we could give everyone an S++++? You see what I'm saying?

Yes. This is difficult confused @rickstaa thoughts?

My vote is with the gaming rank system proposed by @ZjzMisaka (see #2265 (comment)). I think that system togheter with a hover that explains the score solves our problems (see #2157). @anuraghazra what do you think?

Sure, that works. Can you add hover text to SVGs though?

[rickstaa]

In which case we could give everyone an S++++? You see what I'm saying?

Yes. This is difficult confused @rickstaa thoughts?

My vote is with the gaming rank system proposed by @ZjzMisaka (see #2265 (comment)). I think that system togheter with a hover that explains the score solves our problems (see #2157). @anuraghazra what do you think?

Sure, that works. Can you add hover text to SVGs though?

It appears so (see https://stackoverflow.com/questions/41768657/display-text-over-svg-element-on-hover). I also was surprised; I didn't test it out yet. 😅

[Zo-Bro-23]

In which case we could give everyone an S++++? You see what I'm saying?

Yes. This is difficult confused @rickstaa thoughts?

My vote is with the gaming rank system proposed by @ZjzMisaka (see #2265 (comment)). I think that system togheter with a hover that explains the score solves our problems (see #2157). @anuraghazra what do you think?

Sure, that works. Can you add hover text to SVGs though?

It appears so (see https://stackoverflow.com/questions/41768657/display-text-over-svg-element-on-hover). I also was surprised; I didn't test it out yet. sweat_smile

That would be in HTML, yes? I doubt you can do that with GRS though, since the application returns an SVG image, and not an SVG image embedded in an HTML page. It's obviously great if you can do that, but even if it works in the browser, I doubt it will work in other places like GitHub READMEs.

[rickstaa]

So to summarize I think the following will improve the ranking of the stats card which is one of our most requested enhancements:

• Merging Ranking System v2 #1186 while setting the STARS_WEIGHTS to 0.75.
• Creating a PR for @ZjzMisaka ranking suggestions (see Change the ranking/level system #2265 (comment)). Also document the new ranking in the readme.
• Create a PR for Grade description in the report card. #2157.

However, since this affects all users I also want to have @anuraghazra's opinion.

[rickstaa]

In which case we could give everyone an S++++? You see what I'm saying?

Yes. This is difficult confused @rickstaa thoughts?

My vote is with the gaming rank system proposed by @ZjzMisaka (see #2265 (comment)). I think that system togheter with a hover that explains the score solves our problems (see #2157). @anuraghazra what do you think?

Sure, that works. Can you add hover text to SVGs though?

It appears so (see https://stackoverflow.com/questions/41768657/display-text-over-svg-element-on-hover). I also was surprised; I didn't test it out yet. sweat_smile

That would be in HTML, yes? I doubt you can do that with GRS though, since the application returns an SVG image, and not an SVG image embedded in an HTML page. It's obviously great if you can do that, but even if it works in the browser, I doubt it will work in other places like GitHub READMEs.

I support your conclusion. 🤔 I, however, did not test this out. Anyway, I would likely wait for #1633 to be implemented before trying to see if a hover works on the README. This proposal will improve our codebase a lot.

[lorezyra]

If the ranking system could be explained, then I can easily reference it when posting my stats on my websites.

[timheuer]

Just adding my feedback to this one as well. I actually thought there was a bug that I was getting "S" in my card view. Was about to log an issue and saw this thread. Noticed "S" is actually quite good (yay!) but the single letter meant nothing to me (US educated, 'grading' system A-F). I like the original image at the start of this post of the "Top X%" in the inner ring, that's cool and clear. Anyhow, thanks for this project, but +1 comment here that "S" seems weird without explanation.

[vezaynk]

Prominent percentiles in some way are ideal imo

Letters are culture-dependent

[lorezyra]

Instead of some letter, why not use what most apps do in gamification: show an XP or numerical level rank? Everyone starts from zero. But few can keep pushing the top.

[rickstaa]

If the ranking system could be explained, then I can easily reference it when posting my stats on my websites.

Does #2749 fit your need?

[rickstaa]

oticed "S" is actually quite good (yay!) but the single letter meant nothing to me (US educated, 'grading' system A-F). I like the original image at the start of this post of the "Top X%" in the inner ring, that's cool and clear. Anyhow, thanks for this project, but +1 comment here that "S" seems weird without explan

With those stats, you deserve an S 🚀. The current ranking system is based on the Japanese system, I think. I however, still want to improve it to make it more general. My current preference is with #2265 (comment), but a level - based ranking system as given by @lorezyra would also work. Please have no hesitation to put your suggestions in here. I will likely open a poll when the new rank calculation has been merged for a while (i.e. #1186).

[francois-rozet]

To add my grain of salt, is "S" really that hard to understand? It is extremely common in games and means "super"/"more-than-perfect". If you type "tier list" on google images, you will find it everywhere. However what I don't like with the current system is the "S+", which makes no sense. So what I would do as a first step is remove "S+" and add "C" and "C+" (but not below as "E" and "F" are associated with failure). I would also separate the levels evenly (currently the step between "A" and "A+" is much smaller than "B" and "B+") to make it more motivational for newcomers.

I also like the "top x%" (or simply x% and the goal would be to reach 100%); it is the less confusing. I like the idea of "unbounded XP", but this will lead to display issues when the number gets large.

[lorezyra]

@francois-rozet

To add my grain of salt, is "S" really that hard to understand? It is extremely common in games and means "super"/"more-than-perfect". If you type "tier list" on google images, you will find it everywhere. However what I don't like with the current system is the "S+", which makes no sense. So what I would do as a first step is remove "S+" and add "C" and "C+" (but not below as "E" and "F" are associated with failure). I would also separate the levels evenly (currently the step between "A" and "A+" is much smaller than "B" and "B+") to make it more motivational for newcomers.

First, not everyone plays games. I'm over 40 and don't have time to play games anymore. (Too busy writing code and chasing money...)

Second, despite living in Japan for the past 15 years, I have never encountered Academic grading in Japan system. Perhaps it's relatively new and not implemented widely? My point is that not everyone is aware nor familiar with it. Without documentation to explain it, it's a meaningless indicator.

I also like the "top x%" (or simply x% and the goal would be to reach 100%); it is the less confusing. I like the idea of "unbounded XP", but this will lead to display issues when the number gets large.

I'm not sure "100%" would be all that meaningful either. "100%" of what? I like the unbounded XP / level ranking idea. If the numbers get too big, it's trivial to use metric notation to denote larger numbers - e.g. 1K, 99M, 12B... or, use: 3x10^6? The numbers combined with letters would be easier to display. (12M)

That said, "top %" may be more meaningful to recruiters and social circles that value that data.

[guylepage3]

Prominent percentiles in some way are ideal imo

Letters are culture-dependent

I agree with @vezaynk. Letters don't work for everyone where as percentiles do.

[rickstaa]

I agree with. I don't think the current ranking system is bad, but it can be improved. I think the suggestions you made will greatly improve the ranking:

• Remove the S+ ranking, since it is not in the Japanese Grading system anyway.
• Add extra ranks between S-C (i.e. S, A+, A, B+, B, C+, C) while omitting the D and F rankings since they are associated with bad grades.
• Device ranks evenly.

@francois-rozet You are welcome to create a pull request if you like. I am willing to merge these changes without the approval of @anuraghazra. If we want to switch to other ranking systems, I would first like to discuss this with @anuraghazra.

@lorezyra and @guylepage3 About the percentage-based ranking system, I think this is redundant since the rank circle already shows the percentage:

The level/XP-based system indeed is a candidate, but I think will require a lot of code and therefore could hamper the maintainability of the repository. Since GRS is a fun OS project and not a certified skill evolution tool for recruitment, this might not be worth it 🤔.

[lorezyra]

@rickstaa,

Okay. Recommend better docs to explain the meaning of the circle and letters inside the circle. I think it's fantastic to have this tool. Perhaps if you had more sponsorships, an XP based system could be devised to support users that want to show off to recruiters. Until then, whatever the method to determine the rank, please provide documentation that I can link to on my sites.

[guylepage3]

@rickstaa,

Okay. Recommend better docs to explain the meaning of the circle and letters inside the circle. I think it's fantastic to have this tool. Perhaps if you had more sponsorships, an XP based system could be devised to support users that want to show off to recruiters. Until then, whatever the method to determine the rank, please provide documentation that I can link to on my sites.

💯 agree that this is now needed. I did some basic anecdotal evidence that people in North America only understand up to A++. Anything beyond that doesn't exist. A full explanation would be required for N.A. audiences.

[rickstaa]

@rickstaa,

Okay. Recommend better docs to explain the meaning of the circle and letters inside the circle. I think it's fantastic to have this tool. Perhaps if you had more sponsorships, an XP based system could be devised to support users that want to show off to recruiters. Until then, whatever the method to determine the rank, please provide documentation that I can link to on my sites.

@guylepage3 and @lorezyra I updated https://github.com/anuraghazra/github-readme-stats/pull/2749/files so that it explains both the ranking system it is based on and the meaning of the circle around the rank. We can update this when the suggestions made by @francois-rozet are implemented 👍🏻.

[rickstaa]

@guylepage3 I just checked your README page and it looks wonderful. I love https://guylepage3.vercel.app/. Just wondering. What is the reason that you decided to use https://github.com/brunobritodev/awesome-github-stats 's version instead of the GRS 🤔? Are there any features GRS is missing?

[rickstaa]

@rickstaa,

Okay. Recommend better docs to explain the meaning of the circle and letters inside the circle. I think it's fantastic to have this tool. Perhaps if you had more sponsorships, an XP based system could be devised to support users that want to show off to recruiters. Until then, whatever the method to determine the rank, please provide documentation that I can link to on my sites.

I think switching to an organization would already improve maintainability, since it will give me more control about who can collaborate (see #1867). I noticed that many people are passionate about this project and want to contribute, but the permission control of a personal repository limits this 😅.

[rickstaa]

For future reference, I also merged a pull request some months ago which allows you to replace the rank with a GitHub logo using the rank_icon flag. When this is done, it only shows the percentage.

[![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra&rank_icon=github)](https://github.com/anuraghazra/github-readme-stats)

[rickstaa]

@guylepage3 I just checked your README page and it looks wonderful. I love https://guylepage3.vercel.app/. Just wondering. What is the reason that you decided to use https://github.com/brunobritodev/awesome-github-stats version instead of the upstream thinking? Are there any features GRS is missing?

One feature I see in that version that would be nice in the upstream is the card generation website (see #1761) 🤔.

[chrisK824]

@rickstaa I'll agree with guys that support percentage number is the most efficient here.

Pros

• global regardless the culture/ranking systems around countries
• extra resolution down to 1% changes that can motivate the user, so just doing what the ranking is supposed to do in the first place
• easily compare all users rather than group them in big clusters (just in case this is used for any kind of comparison/evaluation)

[guylepage3]

@guylepage3 I just checked your README page and it looks wonderful. I love https://guylepage3.vercel.app/. Just wondering. What is the reason that you decided to use https://github.com/brunobritodev/awesome-github-stats 's version instead of the GRS 🤔? Are there any features GRS is missing?

@rickstaa Thanks for the kind words 😄. And yes. I reached out to @brunobritodev a little while back. He seems to have, although not perfect, a bit better structure for ranking. At the time of me creating https://guylepage3.vercel.app/. I will have to check out the upcoming results of future releases here in the not so distant future. Also I have a lot to complete with https://guylepage3.vercel.app/.

Are there any features GRS is missing?

I believe the value of commits to stars is calculated and valued differently. Stars, imo, are usually just well-marketed projects. Marketing, although important, is not a determining factor in what makes a great developer. Again, imo.

[rickstaa]

@rickstaa Thanks for the kind words smile. And yes. I reached out to @brunobritodev a little while back. He seems to have, although not perfect, a bit better structure for ranking. At the time of me creating https://guylepage3.vercel.app/. I will have to check out the upcoming results of future releases here in the not so distant future. Also I have a lot to complete with https://guylepage3.vercel.app/.

Ah, thanks for the detailed explanation, makes sense!

I believe the value of commits to stars is calculated and valued differently. Stars, imo, are usually just well-marketed projects. Marketing, although important, is not a determining factor in what makes a great developer. Again, imo.

I agree that ranking developers on a small set of parameters is hard to do. I think @francois-rozet's version now results in a more balanced ranking now that pull requests also have a high ranking. However, there is always room for improvement 👍🏻.

[anarchopossum]

I personally Like the numerical ranking system. Not only is it more universal for people around the world to understand. it keeps people motivated to keep working. Seeing a letter value might demote someone from wanting to work or it might not translate very well for other regions outside of the US

[rickstaa]

I personally Like the numerical ranking system. Not only is it more universal for people around the world to understand. it keeps people motivated to keep working. Seeing a letter value might demote someone from wanting to work or it might not translate very well for other regions outside of the US

Maybe we can give the user the ability to set the rank_type to number or letter? We could use the inverse of the number that is used to calculate the rank 🤔.

[rickstaa]

I personally Like the numerical ranking system. Not only is it more universal for people around the world to understand. it keeps people motivated to keep working. Seeing a letter value might demote someone from wanting to work or it might not translate very well for other regions outside of the US

Maybe we can give the user the ability to set the rank_type to number or letter? We could use the inverse of the number that is used to calculate the rank thinking.

Closing this because #2762 in my opinion, improved the ranking level system by a great around! Feel welcome to open a new issue or pull request if you guys want to have the ability to show the percentage complete instead of the ranking letters 👍🏻.

[rickstaa]

Additionally, I now created #2859, which gives users the ability to show the percentile:

[![Anurag's GitHub stats](https://github-readme-stats-git-addpercentilerankicon-rickstaa.vercel.app/api?username=mindlabordev&rank_icon=percentile)](https://github.com/anuraghazra/github-readme-stats)

[rickstaa]

We decided to replace progress with percentile since it is unclear to users what progress means (see #2859 (review)). Therefore, changing progress to percentile in your README would be best.