[Gatsby] New Code Page

[ardatan]

On this PR, We started by improving the design and ordering of the code page in addition to our Gatsby migration PR #938.
We’ve followed the guidelines and ideas from #768.
There are now clear sections for each language.
Also, this PR uses a ranking algorithm for libraries and tools in the Code page.
This algorithm compares those by their GitHub stars, NPM downloads, number of commits (except bots like renovate and dependabot) in the last month.

We deployed the new Code page;
http://guild-gatsby-graphql-org-new-code-page.netlify.app/code

This PR includes changes from;
#954
#927
#774
#673
#664
#916
#914
#956
#950
#922
#903
#859
#858
#865
#781

[carolstran]

There's a lot happening here, but an initial question: Why have the changes to the Code page in the same PR as the migration?

Asking because the Code page updates will require more review and is more... controversial... than the migration (which has already been approved). Plus they are two separate issues which would traditionally mean two PRs, so I'm curious about the thinking behind it.

[Urigo]

Thank you for the comment @carolstran
I would welcome any comments about the code page and if we'll get comments that would make it controversial or hold us back from merging, we'll pull those changes into a separate PR.

Let's focus on getting as much actionable feedback as soon as possible before merging

[IvanGoncharov]

@Urigo I agree with @carolstran that we need to separate migration from design and content changes.
Can you please split code page changes into separate PR?

@ardatan can you please properly rebase this PR on top of master?

[ardatan]

Because of the redesign-code name of the branch, this PR will have code page redesign besides gatsby migration. The PR that belongs to gatsby migration only will be this one;
#938

[carolstran]

I might wait until after #938 is merged to properly review (it's difficult to see what the specific Code page changes are now), but a quick question in the meantime: Did you have a chance to check out the discussion in #911? If so, I'd be curious to hear how it informed the way you implemented a ranking algorithm.

[Urigo]

Thanks for the review @carolstran, I worked with @ardatan on the algorithm implementation so I'll try to explain our reasoning behind it.

We’ve basically followed the comment you quoted at the beginning of the issue:

The ranking is calculated by Github stars, Commit volume and Latest commit which are not renovate/bot and package downloads stats.
We believe this follows the main goal better than the current state of rank on the website.

The reasoning behind the algorithm and the goals are as follows:

We see the main goal of graphql.org is to make it as easy as possible for beginners to get into GraphQL without getting stuck.
That’s the first place beginners are being introduce to GraphQL.
More advanced developers would find their path with more confidence.

With the current state to rank, beginners are constantly trying to use outdated, unmaintained libraries and get stuck.
(this is feedback we get daily for months and years....)
This ranking puts the most popular, actively maintained libraries on top, to minimize the chances for a beginner to hit a path that doesn’t work.

The reason we wanted to get this merged quickly was that we agree with the sentiment of that comment by @dosco - “Sometimes good enough is better than perfect.”
As this is already better, and also we are going to actively and continuously work on graphql.org from now on and improve it with any feedback that would come.
That algorithm would also make the job of merging a lot of community libraries much easier, as we don’t need to have a whole discussion on each of them (and would close tons of open issues and PRs), and we could continue the discussion about improving the algorithm separately.

We would gradually apply that algorithm and the parts of it where possible.
Where it won’t work or achieve its goal, lets fall back to alphabetical order.

Once that will be merged, we will add more package managers data from package managers that are not npm for other languages and ecosystems.

It’s similar also to what was suggested on this comment by @jeggy

We could also later on add voting mechanism like @saihaj suggested here, even though I believe that could easily be manipulated and also it’s much more complicated because it means we need to start storing state and votes somewhere...

Sorry for the long message @carolstran, looking forward to hearing your thoughts and feedback!

[orta]

I think this needs a fundamental re-think, it forces anyone wanting to edit the site to have GITHUB_ACCESS_TOKEN set up, and anyone wanting to add to a library to make markdown edits inside a JSON file. I don't want this repo to have these barriers to entry.

How I solved this in the TypeScript website was to have a bootstrap command which bundles up a series of markdown files which are easy for folks to contribute to (and to add their own).

You could have a folder structure like:

./src/content
├── blog
│   ├── 20150914-graphql.md
│   ├── 20151016-subscriptions.md
│   ├── 20160419-mocking.md
│   ├── 20160502-rest-api-graphql-wrapper.md
│   └── 20160914-production-ready.md
├── codeofconduct
│   └── CodeOfConduct.md
├── code
│   ├── JavaScript
│   │    ├── Apollo.md
│   │    └── Relay.md
│   ├── Go
│   │    └── GraphQL-Go.md
│   ├── Groovy
│   │    └── Gorm-GraphQL.md

The metadata can be attached as yml frontmatter.

Then during bootstrap the additional sorting metadata can be grabbed if there's GITHUB_ACCESS_TOKEN but there should be some sort of fallback to make the site work if that's not available. That could either be a mock/fake, "old" data in source or just be optional in the UI.

[orta]

This section again is continuing to get chunks of hard to grok code without the reasoning for why. I think this should probably have comments - and more likely I think that async could probably just be moved to a bootstrapping phrase.

[benjie]

Could I request the addition of PostGraphile to this? I think under the JavaScript section makes most sense.

Separately,

This algorithm compares those by their GitHub stars, NPM downloads, number of commits (except bots like renovate and dependabot) in the last month.

I'd just like to point out that ranking based on number of commits in the last month unfairly penalises projects that use the squash-merge technique. Maybe LOC changed might be a fairer metric, though again that's problematic as some languages are naturally more terse than others. Personally I feel like this metric should be removed, or should be replaced with something like "time since last commit."

[orta]

Personally, I don't really see much user value in sorting each library per language if we provide better visibility into useful metrics. The page basically looks randomly ordered right now on this branch. I'm not sure sorting internally vs alphabetically it pays for itself, I think by most recent deploy could work, though we'd probably need to explain that somewhere on the page. Though it might be more obvious in the new designs. I think there's definitely value in sorting the languages by stars though.

Rather than a write-up, I've worked on the designs and added all my comments, the previous one was only meant to be a sketch to get a direction from folks and so I've just continued that direction and tightened it up.

Figma link

[orta]

I've given it a run through locally and shipped anything I had as feedback, I think this is a great improvement.

It means we can accept pretty much any PR to the code section now without merge conflicts, and we can encourage people to show example code in their samples wiht as much code as the want. Good work.

I'll leave this open for a day for feedback, if there's none blocking. I'll merge.

[orta]

Alright, let's get this merged. Thanks folks!

[8bitreid]

cleanup from this can be found #964 @orta and @carolstran could you please take a look. thank you.