I've worked in development and DevOps for decades, often maintaining both the application and its data. Occasionally, a system such as a CMS, DMS, CRM, or IAM platform needs a bulk data operation that the normal UI cannot handle efficiently. For example, a task might identify all objects matching several properties in one section, move them to another section, and calculate a new value for one of their fields.
If this is likely to become a recurring operation, I would turn it into a proper product feature with a supported interface. The harder case is a specialized job that may not be needed again for months or years. It is easy to write code for it, but deleting that code afterward feels wasteful because it may provide a useful starting point later.
The code often depends directly on internal classes from a compiled application, so it may not be possible to move it into a standalone script repository without extracting artifacts or restructuring dependencies. I'm specifically asking about preserving a snapshot of the actual task-specific code for documentation and future reference, not necessarily keeping it runnable as-is. Where do you store this kind of code, what do you call the directory or repository, and do you keep it as a language-specific source file such as `.java`, or as documentation such as `.txt` or `.md`?
4 Answers
Put small jobs in a clearly named folder in the related repository, such as `scripts/`, `maintenance/`, or `data-fixes/`, with a date and short description in the filename. A header comment can record the original problem, target environment, assumptions, and execution date. For compiled code, keep the proper extension even if the file is now archival; the extension tells future readers what language and syntax they are looking at. Use Markdown for the explanation, not for the source itself.
A dedicated utilities or operations repository also works, especially if several teams need to find this material. Use descriptive directories and filenames, and commit the context with each item: what it did, when it was used, and what project or version it depended on. For code that relies on private application classes, I would still preserve the original source file and record the package, module, dependencies, and invocation details in a Markdown file. That is more honest and useful than pretending the extracted snippet is independently runnable.
I would call the repository something unambiguous like `ops-tools`, `maintenance-jobs`, or `engineering-utilities`, rather than a vague scratch area. The important part is that it is versioned, searchable, and has enough surrounding explanation for someone else to recognize its purpose.
There is a useful distinction between reusable tooling and a historical record. Reusable helpers should become normal utilities with tests and a supported way to run them. A one-time data mutation can remain an archived source file with a short record of the change. Keeping it in version control is valuable because months later people may need to understand why hundreds of records changed, even if nobody should execute that exact code again. If an operation keeps recurring, that is the signal to promote it into a proper feature or maintained tool.
Keep it in the main project repository, but clearly separate from the application code in a directory such as `ops/one_off/`, `maintenance/`, or `admin-tasks/`. Store the source in its original language so it remains readable, and add a README or nearby note explaining what it changed, why it was needed, when and where it ran, which commit contained it, and whether rerunning it is safe. Even if it is not meant to run again unchanged, preserving the original source alongside its context makes it useful operational history rather than forgotten scratch code.
That matches how I think about it as operational history. In this case I probably would not spend time making the code idempotent or adding a dry-run mode, since the exact operation is not intended to be rerun. I was mainly unsure whether the historical snapshot should remain a `.java` file or be converted to documentation.
The directory name does not have to imply that every file is a shell script. `maintenance` or `one_off` is clearer when the files include Java or other compiled-language code that was originally part of a specific module.