I've worked in development and DevOps for decades, maintaining both application code and the systems' data. Occasionally, a project needs a bulk data operation that cannot reasonably be done through the normal UI and is unlikely to become a recurring feature.
For example, a recent task involved finding every object with properties X, Y, and either Z1 or Z2 in section S1, moving those objects to S2, and calculating a new value for X. Doing this manually for several hundred objects would be impractical, while writing code to perform it is fairly straightforward.
After testing and running the operation in production, what should happen to that code? Deleting it feels wasteful because it may provide a useful starting point for a future task, but keeping it alongside the regular application code also feels awkward. The code may depend directly on internal classes and Maven modules, so moving it to an independent utilities repository would make it difficult or impossible to compile and run.
I'm not asking about reusable scripts or production-ready migration tools. I mean preserving a snapshot of project-specific code for operational history and future reference, even if it is no longer runnable as-is. Would you keep it in the main repository under a dedicated directory, store it as a language-specific source file, use a text or Markdown file, or handle it another way?
4 Answers
Keep it in the repository it belongs to, but clearly separate from the application code—for example, an `ops/one-off/`, `maintenance/`, or `admin-tasks/` directory. Store the original source in its normal language-specific file format, even if it no longer builds, and include a README or comment explaining what it did, why it was needed, where it ran, when it ran, and whether it is safe to run again. That preserves the historical context without pretending the code is a supported feature.
Treat these as operational history rather than product code. A dedicated folder in the main repository keeps the code versioned and searchable while preserving access to the internal APIs and dependencies it used. Give each task a descriptive name or date, and keep customer-specific values and dataset identifiers out of the stored example where possible.
I agree that the historical record is valuable, especially when someone later asks why a large group of records changed. I also like keeping the exact task-specific code available as a starting point for related work.
A separate utilities or maintenance repository can work for genuinely independent scripts, with folders and a short README for each one. But if the code calls private application classes directly, putting it outside the project creates dependency and build problems. In that situation, a dedicated directory in the original repository is the more honest and maintainable location.
The important part is not whether the file can still be executed; it’s whether the next developer can understand it. Keep the source recognizable as Java, shell, or whatever language it was written in rather than hiding it in a generic text file. Add a small companion document containing the purpose, affected data, execution date, environment, relevant commit, and any warnings. That makes it searchable documentation with an attached implementation.
That matches what I’m looking for. In this case I would also record the original Java package and Maven module, since the preserved file would not be independently runnable.