Chore: Wiki/Reflections from a Rails-newcomer

MaoShizhong commented 2 months ago

Checks

[X] I have thoroughly read and understand The Odin Project Contributing Guide
[X] The title of this issue follows the Chore: brief description of chore format, e.g. Chore: Lesson complete button does not update on click
[ ] Would you like to work on this issue?

Chore description

Our web app wiki is great for getting started with setting up and starting the server for hosting the web app locally. However, my experience going through it indicated to me it's missing some additional instructions for things that aren't the most obvious to someone taking a dive into the codebase coming from something like Node-only experience.

Things I came across that the wiki doesn't make clear or mentions entirely, that I feel would be very helpful for anyone reading it:

Replace foreman start with bin/dev, since the latter includes Procfile.dev
- Perhaps also briefly summarise what some of the Procfile.dev commands do? e.g. running yarn build:css
- Maybe also some gem for restarting the server upon file changes, like Nodemon for Node? I came across the rerun gem - not sure if there is a better alternative in Rails-land.
Changes to some files (e.g. Kramdown converter files) would require rails curriculum:update_content to reflect in the app (brief summary of process for converting the lesson files and storing in DB, then just pulling HTML from DB in the web app instead of live-converting?).
- Mention best way to check Kramdown file changes would be via the markdown preview tool, as that does live-convert.
For CSS changes to reflect in the app, even after making sure the CSS gets built, I needed to run rails assets:precompile to build into public/assets, as that was taking priority over app/assets.

Basically without needing to "teach Rails", the wiki could do with further instructions on how to actually use the app and code base. Very helpful for those like me with non-Rails experience but want to test a few things locally.

Of course, there may be other things I'm completely unaware of. e.g. I don't know what other things might require rails assets:precompile, or if there's an alternative to that command I just wasn't aware of. Or if rails curriculum:update_content would be needed for other files than just the Kramdown ones. Or if changes to any other files/directories would require additional steps and what those steps would be.

Acceptance criteria

[ ] Improve wiki with further instructions for using the codebase.

Additional Comments

Damn, is Ruby and RoR fun.

JoshDevHub commented 2 months ago

Bit of overlap with this issue maybe #4328 (just posting so both are linked)

replace foreman start with bin/dev

Absolutely agree.

Perhaps also briefly summarise what some of the Procfile.dev commands do? e.g. running yarn build:css

This is fair too. If you wanted any explanation about this stuff, it's basically just a way to spin up all the necessary processes in one terminal window instance. Otherwise you'd have to open dedicated terminals for serving the Rails app, building the CSS, running the background worker, etc.

Could probably be a short explanation on why this exists and what the commands in the Procfile do.

Changes to some files (e.g. Kramdown converter files) would require rails curriculum:update_content to reflect in the app (brief summary of process for converting the lesson files and storing in DB, then just pulling HTML from DB in the web app instead of live-converting?). Mention best way to check Kramdown file changes would be via the markdown preview tool, as that does live-convert.

This seems good to me as well. Definitely the most convenient way to check with this stuff is through using the preview tool.

I maybe don't think this should be something that's talked about in the contributing guide or the wiki's "Running the Project Locally." This is just because it's not super common that contributions are changing Kramdown (although of course, it's the first thing you're doing :laugh:). But maybe there can be another page on the wiki dedicated to Kramdown where this type of documentation could live?

For CSS changes to reflect in the app, even after making sure the CSS gets built, I needed to run rails assets:precompile to build into public/assets, as that was taking priority over app/assets.

That sounds correct to me.

I could probably work on getting some of this settled over the weekend.

MaoShizhong commented 2 months ago

@JoshDevHub Sounds good to me - I'm sure you and/or others more familiar with Rails and the web app code base would know best how to handle this.

The most important thing I think is to at least end up with instructions that allows someone with experience but not any Rails experience (e.g. someone like me coming from the Node side of things) to be able to dive in and play around. There are a few things that aren't obvious as to how things are done (e.g. the Kramdown stuff) and/or someone without Rails experience might not know is necessary for something that wouldn't need an additional step elsewhere (e.g. had no idea that yarn build:css would not be sufficient without rails assets:precompile).

Like, the details can of course be figured out through exploring, but having the necessary commands for certain actions/changes beyond just "get the server up and running for the first time" would be extremely valuable.

KevinMulhern commented 2 months ago

Great write up @MaoShizhong, thanks for putting this together!

I've been running into CSS changes not taking effect a lot too. Clearing out the assets with rails assets:clobber gets rid of it for a while. But I think its caused with a bug in our CSS setup, I noticed it starting happening right after we started using the CSS bundling gem.

I think we should try fixing that one before documenting it - I'll put an issue together for it. But I agree with the rest, it would be great to get our Kramdown and Procfile setups documented.

MaoShizhong commented 2 months ago

Enjoyed exploring Rails for a bit! And if it's a bug, that makes sense since given the commands like yarn build:css, you'd have thought that'd be sufficient for CSS changes to reflect in the app.

JoshDevHub commented 1 month ago

Alright finally got some time to work on this :rocket:

TheOdinProject / theodinproject