The file you edit is not always the file that ships
You fix the bug, you reload, it is fixed. Someone runs the build and your fix is gone. Not reverted by a person, overwritten by a script that regenerates the file you were editing.
A site had three pages that looked like ordinary HTML. They were ordinary HTML. They were also output: a script read a template, resolved it, and wrote those three files on every build. Editing them worked perfectly until the next build, at which point the edit was gone without a trace in the history.
The same site had a JavaScript file in its assets folder. Same situation: written out of a string inside the build script. Nothing in either file said so.
Why this is worse than it sounds
A deleted file is obvious. An overwritten one is not, because the file is still there, still valid, still roughly what you remember. The failure arrives later and somewhere else, and the person who hits it is usually not the person who made the edit.
It is also the kind of bug that survives review. The change looks right in the diff, because it is right. It just will not last.
Make generated files announce themselves
The cheapest fix is a line of text. Put a banner at the top of every generated file naming the script that writes it and the source to edit instead. It costs one line and it ends the entire class of mistake for anyone who opens the file.
- A banner at the top of every generated file: what writes it, what to edit instead
- Keep generated output and hand-authored source in visibly different folders where you can
- After changing a source, run the build and read the diff: it should contain your change and nothing else
- If the diff carries surprises, something else is generating into the same file
The build-and-read-the-diff habit is the one that pays. It is how you discover that a generator you forgot about also writes the file you just touched.
The related trap
Once a file is generated, a second question follows: does the generator produce the same bytes twice from the same input? If it embeds a timestamp or a random identifier, every rebuild shows a diff, and a diff that is always noisy is a diff nobody reads. That is how a real change hides.