Tom Insam

Rules for personal projects

Rules I try to adhere to when working on my personal stuff. They might not apply to you, but I have my reasons, so consider them.

  1. There should be a one-line command in the root of the checkout called run that starts the thing and does something useful. If it’s a web server it should start on some high-numbered port that’s unique to this particular project (so I can work on more than one and not care) and it should print the URL it’s running on so I can Command-double-click it and see something useful. It should also start anything else that needs to be running for the service to work. If I ctrl-C it, it should die nicely.

  2. There should be a one-line command to grab the current deployed ‘live’ database/state, or something close to it, and pull it to the local machine. That way I can debug problems that are happening to live. Ideally this command is the same for all my projects.

  3. There should be a one-line command that deploys the service to live (assuming there is a live). The service must ONLY be deployed with this command. It should do everything required to get the current version onto the live server - no multi-step fiddling. I’m not picky between “rsync local codebase” or “check out from Github to remote server” as long as what it’s doing is obvious and consistent. Again, this command should be the same for all projects.

  4. There should be a requirements.txt (Python) or a Makefile.PL (Perl) – or whatever the language I happen to be working in at the time uses as it’s local equivalent – in the local directory, and it should be an accurate and complete list of the project’s dependencies. (In fact, the deploy command from Rule 3 should use it to build the environment on every deploy.) Bootstrapping a mostly clean local environment to a working state should be a single command. This command should be the same for all projects.

  5. I’m allowed to assume a certain set of local running services. Databases and Redis and a system Python. Everything that’s peculiar to this project needs to be deployed according to Rule 4.

There’s a theme here. I don’t work on my personal stuff a lot. There are gaps between sessions of a few weeks, months sometimes. I do not want to spend time remembering how to do any of the incredibly boring boilerplate crap that is associated with coding. I want to cd into the folder, run a command that I know will be there no matter what the project is, and have it work. When I’ve fixed the problem or added a feature, I want to run a single other command and have the working code on the live server without having to remember anything fiddly about this particular setup.

Deployment is a particular bugbear of mine. I hate sysadmin stuff, so I spend a large amount of my time automating it out of existence. DEPLOYING YOUR CODEBASE SHOULD BE EASY AND CHEAP AND FOOLPROOF. Easy, so you can do it whenever you want. Cheap, so you’re never afraid to do it whenever you want. And foolproof, so you don’t leave a step out and break things.

Yes, these rules also apply to your day job projects.

No, I don’t manage them all perfectly. ASPIRE, GODDAMNIT.