Devhints 2.0 migration plan

rstacruz commented 5 years ago

(I'm still writing this document - more info to follow!)

New Devhints is coming <3

Over the next few weeks/months, Devhints will be transitioned from it's aging Jekyll setup to a more modern stack built with Gatsby and Node.js.

What are we trying to solve?

:cry: Jekyll is slow.
Devhints today uses Jekyll to generate the website, since it's the default (and only) generator for GitHub Pages. However, it's been long since Devhints has outgrown Jekyll. It takes a long time to start a development server due to the sheer amount of files to be processed. Changing files are quite slow, too, due to the same reason.
😲 The Git repository is very messy.
The Git repository now hosts the cheatsheets themselves, along with the Jekyll theme, and all the other build artifacts like vendor.js.map. This makes it very hard to navigate, and git greping around is very messy.

Changes: Cleaner repos!

:v: There will be 2 repositories: one for sheets, one for code.
The main repo, cheatsheets, will host nothing but Markdown files for the cheatsheets themselves. The supporting files are now in devhints-engine.
Sheets will now be in sheets/ and not /.

Changes: Cleaner code!

Sheets will now be formatted through prettier.
This should get us some consistent formatting of Markdown files.
CSS classes will now be using rehype-decorate instead of Kramdown. This will make Devhints's Markdown files be written in a standard [Common Mark] format, without any backward-incompatible syntax constructed.

New code

rstacruz/devhints-engine
This is the "engine" that powers the website, written in Gatsby. The sheets are still going to be stored and maintained in cheatsheets, but all the JavaScript and CSS that builds the website will be in devhints-engine. This repo is publically-accessible right now, do check it out.
rstacruz/cheatsheets-ng
For now, this is a fork of cheatsheets with the content updated with the new format. It's private right now (so no one stumbles upon it by mistake), and I update it manually as cheatsheet is updated. When we launch 2.0, I'll push the contents of cheatsheets-ng into cheatsheets :)

Migration plan

TBD

Beyond 2.0

A redesign of Devhints is in the works. (...)

Maintenance plans

(...welcome new maintainers)
(...implement stalebot)

Kreijstal commented 5 years ago

I discovered this project today, how exciting!

Kreijstal commented 5 years ago

I just had this idea: Wouldn't it be cool if there was something like wikis but for github, everyone has write access but you can add/remove permissions to certain files.

kevin-lindsay-1 commented 5 years ago

@Kreijstal That sounds interesting, and less of a hassle to wait for PRs to be reviewed. Perhaps one could implement an automated system wherein once you've had a few PRs accepted, the individual is automatically granted the permissions of a reviewer.

borekb commented 5 years ago

I'd love Devhints integration with tldr one day.

d0vi commented 5 years ago

If it is posible, get #321 solved would be great!

qoomon commented 5 years ago

@d0vi I've just created a PR #1023 to solve the favicon issue #321

BosEriko commented 4 years ago

Is this still happening? Any way I can help?

Kreyren commented 4 years ago

The Git repository is very messy. The Git repository now hosts the cheatsheets themselves, along with the Jekyll theme, and all the other build artifacts like vendor.js.map. This makes it very hard to navigate, and git greping around is very messy.

Referencing: https://github.com/rstacruz/cheatsheets/pull/1294

Kreyren commented 4 years ago

(...implement stalebot)

Referencing: https://github.com/RXT067/cheatsheets/pull/2 (Github doesn't allow this without set up authentification -> can't make a merge request)

EDIT: Why stalebot? Rather implement a better project management to handle all the issues

Kreyren commented 4 years ago

Jekyll is slow. Devhints today uses Jekyll to generate the website, since it's the default (and only) generator for GitHub Pages. However, it's been long since Devhints has outgrown Jekyll. It takes a long time to start a development server due to the sheer amount of files to be processed. Changing files are quite slow, too, due to the same reason.

Referencing: https://github.com/rstacruz/cheatsheets/pull/1295 seems to be pretty fast on my end

EDIT: did you file this in jekyll?

Kreyren commented 4 years ago

Any other issues? :p

rstacruz / cheatsheets