[openstreetmap/openstreetmap-website] How to develop with decent velocity (Issue #6677)

[Andy Allan]

gravitystorm left a comment (openstreetmap/openstreetmap-website#6677)

When everything is running smoothly, rails will compile the assets (stylesheets, images and javascripts) on the fly, and take care of everything when the files are changed on disk. This is similar to the ruby code - e.g. you don't need to restart the rails webserver when you change a ruby code file - rails notices automatically, and takes care of everything.

Note the caveat with "running smoothly".

> `docker-compose run --rm web bundle exec rake assets:precompile`

When you precompile the assets, then rails will use those compiled versions in preference to anything else. So if you've run the `assets:precompile` at any stage, you then need to manually run it again any time you want to see your changes to stylesheets or javascript files. 

For this reason, it should only really be used for production, not development. However, there's various edge cases that can stop the automatic asset pipeline from working in the development environment and these situations can be hard to debug. So many people immediately reach for `rails assets:precompile`, especially if they are not working on anything related to the assets, and the problem (seemingly) goes away. This workaround then gets into our installation notes, into stackoverflow, into LLMs, etc etc and becomes normalised.

That's not to say we shouldn't mention it, because for example it took me months to figure out what was going wrong the last time the automatic assets system broke on my machine (and I relied on repeated `assets:precompile` until I figured out that something in `rails_dir/tmp` was causing hash mismatches in the urls). 

I'm very open to either changing or removing the mention of `assets:precompile` from DOCKER.md, I think it's probably unhelpful at present. There might also be something specific to our docker setup that's interfering with the automatic recompilation, in which case that should be investigated and fixed - or it might just be that avoiding precompilation makes everything work fine.

-- 
Reply to this email directly or view it on GitHub:
https://github.com/openstreetmap/openstreetmap-website/issues/6677#issuecomment-3709843888
You are receiving this because you are subscribed to this thread.

Message ID: <openstreetmap/openstreetmap-website/issues/6677/3709843888 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/rails-dev/attachments/20260105/5a550560/attachment.htm>