Change One Thing at a Time: The Builder Anti-Chaos Rule
There is one rule that saves builders from unnecessary pain:
Change one thing at a time.
Not five things.
Not “just a few quick edits.”
Not “I updated PHP, installed three extensions, changed CSS, moved the server, edited DNS, and now something is broken.”
That is not debugging.
That is creating a crime scene and then asking which fingerprint belongs to the spoon.
This post is a simple guide for making changes safely, especially when working on websites, forums, scripts, apps, servers, themes, plugins, extensions, and anything else that can break while looking innocent.
The anti-chaos rule
Before changing something, write down:
What I am changing:
Why I am changing it:
Where I am changing it:
What should happen after:
How I can undo it:
Example:
What I am changing:
Adding custom CSS to style discussion thumbnails.
Why I am changing it:
The thumbnails look too small and circular.
Where I am changing it:
Admin → Appearance → Custom Styles.
What should happen after:
Thumbnails become larger rounded squares.
How I can undo it:
Remove the CSS block I added.
That is clean.
Now if something breaks, you know exactly where to look.
Bad way to make changes
I installed 4 extensions, edited Custom CSS, changed cache settings, updated Composer, changed icons, and moved some files.
Now the homepage is broken.
That is builder soup.
Nobody knows which ingredient poisoned the bowl.
Better way to make changes
Step 1:
Install one extension.
Step 2:
Clear cache.
Step 3:
Test the site.
Step 4:
If it works, continue.
Step 5:
Only then make the next change.
Slow is smooth.
Smooth is fast.
Panic is usually expensive.
After every change, test
Do not assume the change worked.
Check:
- Homepage
- Login
- Signup
- Admin panel
- One discussion page
- Mobile view
- Dark/light mode if used
- Browser console
- Error logs if something looks wrong
For Flarum, useful checks:
php flarum info
php flarum cache:clear
php flarum assets:publish
Then hard refresh:
CTRL + F5
If you changed CSS and nothing happens, it may be cache.
If you changed PHP and everything dies, it may be your soul leaving the server.
Check logs.
Keep a change log
This does not need to be fancy.
Just write:
Date:
Changed:
Files/settings touched:
Result:
Undo notes:
Example:
Date:
9 July 2026
Changed:
Added thumbnail CSS.
Files/settings touched:
Admin → Appearance → Custom Styles.
Result:
Thumbnails changed from circles to rounded squares.
Undo notes:
Remove the block titled Fyrbloc — Discussion Thumbnail Polish.
This makes future debugging much easier.
Your future self will thank you.
Or at least stop calling your past self names.
Before installing extensions or plugins
Ask:
- Is it compatible with my version?
- Does it need migration?
- Does it change permissions?
- Does it add frontend assets?
- Does it affect signup/login?
- Does it affect posts or profiles?
- Can I remove it safely?
- Do I have a backup?
For Flarum, after installing an extension:
php flarum migrate
php flarum cache:clear
php flarum assets:publish
If Composer complains, do not force random things like a wizard with no training.
Read the error first.
Make backups before risky changes
Make a backup before:
- Major updates
- Extension upgrades
- PHP version changes
- Theme edits
- Database work
- Moving servers
- Permission changes
- Anything involving “it should be fine”
The phrase “it should be fine” has injured many projects.
A basic backup should include:
Files
Database
composer.json
composer.lock
config files
If you cannot restore it, it is not a real backup.
It is just a comforting folder.
When something breaks
Do not immediately change ten more things.
First ask:
What was the last change?
Then:
Can I undo only that change?
Then:
What does the log say?
Useful log command for many PHP apps:
tail -n 100 storage/logs/*.log
For server status:
systemctl status php8.4-fpm
For recent system errors:
journalctl -xe
Do not randomly reinstall things unless you want the bug to bring friends.
How to ask for help when a change breaks something
Use this:
What I changed:
Why I changed it:
Exact time it broke:
What broke:
Error message:
What I already tried:
Can I undo it?
Yes / No / Not sure
Screenshot/link:
Example:
What I changed:
Added custom JavaScript to the header.
Why I changed it:
Wanted a custom menu.
Exact time it broke:
After saving the header code.
What broke:
The menu no longer opens on mobile.
Error message:
No error, but browser console shows a TypeError.
What I already tried:
Cleared cache and removed the last CSS block.
Can I undo it?
Yes, I can remove the custom script.
Screenshot/link:
Added below.
That gives people a useful starting point.
The “do not do this live” list
Avoid doing these directly on a live site unless you have a backup and know the rollback plan:
- Big Composer updates
- PHP version changes
- Database edits
- Permission changes
- Removing core files
- Replacing theme folders
- Editing production config blindly
- Pasting unknown JavaScript
- Installing random plugins from mystery corners of the internet
Mystery code is not a feature.
It is a raccoon in a server cabinet.
Safe change checklist
Before changing:
After changing:
Final rule
If you change one thing and something breaks, you probably know what caused it.
If you change ten things and something breaks, congratulations — you have invented a puzzle.
Build carefully.
Change slowly.
Test often.
Keep notes.
Build. Change. Test. Fix. Launch.
