Sometimes, getting old projects running again can be a real pain. Thankfully, doing a smidge of prep work while archiving a project will go a long way toward bringing the project back.
All it takes is writing down three things for your future self. I’ve found a project’s README file is often the best place for this. Project wikis are also a good home.
1. Write Down Prerequisites
What needs to be installed on the system in order to run this software? What versions?
Some prerequisite examples might be:
- Hardware – Does this run on PC or Apple hardware? Is it intended for a virtual machine? Does it connect to external hardware through USB or another interface?
- Operating system – What version of Windows X, macOS Y, or Linux Z is this intended for?
- Language runtime – What version of Ruby, NodeJS, or whatever is this meant to run in?
- Support tooling – What version of Bundler, Yarn, Vagrant, or whatever is needed to help get the app installed?
At a minimum, write down version numbers and dates. Even if those versions are not available in the future, at least we know what was intended.
2. Write Down “Quick Start” Steps
I like to call this the “don’t make me think” section.
Seriously. Don’t make me think. Write down a bunch of copy-and-paste steps I can run to get running.
These might look like:
svn co X Ycd Y- Install Ruby as prompted
gem install bundler -v X.Y.Zbundle install- … etc …
Of course, all of the above steps would be run within the environment described by the Prerequisites section.
3. Make It Easy to See Representative Data
Ok, great. We now know what to install and how to install it. But now that this app is running, what do we do with it? How do I start the app or log into it? What should I be seeing once I’m in?
Write down steps to start the app and see something realistic. These might look like:
- The name of the app to run from the Windows Start menu
- The URL to visit to see the web app
- Local login credentials
- How to get sample data loaded into the system and what it should look like
I find that last item–viewing sample data–to be the most important, as it demonstrates that the system is up and working as intended. Cloning data from production or staging sites is a great way to get some representative sample data locally.
Bring It All Together
Almost all of my project README files now start out looking something like this:
- What is this app?
- Prerequisites
- Quick start
- Loading sample data locally
Once you’ve got these steps in your README, ask a colleague to run through everything. There will likely be gaps. That’s okay, because those gaps are easy to fill while you’re still working on the project. Be grateful you aren’t running into them five years later when your memory of the app is long gone.
Getting legacy projects running again is never fun. Leave some breadcrumbs, and your colleagues & future self will thank you.