Automate all the things

All the tasks around your project should be automated, to improve accessibility, reliability, maintainability; and maybe even save you some time.

Regardless of the technology, most project involve the following tasks:

  • Setting up the local development environment: Get the sources, dependencies, config files
  • Building the project: Generate code, compile code, bundle assets, etc.
  • Running the project: Start the executable with the right parameters
  • Testing the project: Run unit-tests, measure code coverage, perform static analysis (lint the code)
  • Publishing the project: Publish a library, an executable, update documentation, a website, a service

These tasks can be more granular or only applied to sub-components. Depending on the technology, some tasks (building, running) may be trivial at first but can get complex as the project grows. Of course, you may also have other tasks around your project (to handle backups for example).

To work on a project, you need to perform these tasks. There's no point in writing code if you don't know how to build the project. That's why it is very important to know how to perform these tasks.

Automation in this context means that you can perform any action with a single command (or even no command at all). The amount of manual work is reduced to a minimum.

The first reason to automate project tasks is accessibility. Reducing a complex process to a single command means that anybody should be able to use. It highly reduces the barrier to participation. If the project requires complex steps that only a few people can perform, this group of people can become a point of failure for the project. If they become inactive, the project dies out.

Simplifying these processes is not only needed for users or occasional contributors, but also for core maintainers. It's easy to forget a step in a manual process, or do any other kind of mistake. Manual process are tedious and error-prone. Automation is a tool to improve reliability of your project.

Reliability through automation is an extremely important notion. By automating a task, you can trigger it whenever you want. Manually, but also at some specific events. For example you can run your tests when you do a commit or build and publish your project as part of continuous deployment; more on that later.

Finally, having a script to run a tasks is useful for documentation. I'd say that it helps on two fronts. For the users, it is easier to maintain and read a list of simple commands with their description. You only need a high level description of effects, and abstract the details. And for those actually adding or updating the task scripts, having them as code means that your steps are described formally according to the semantics of the language used to write them. Basically, this is the same argument as why you should avoid code comments on the "how" and should strive to write "self-explaining code": it's hard to keep comments/documentation in sync with your code. The code is what is ultimately executed and therefore is your source of truth. It unambiguously describes how to build, run, test, deploy your project.

What about automation as a way to save time? In my experience, it will save time for others, but as a project maintainer it will be time consuming. The more users you have, the more time you'll save overall; but even if it is a solo project I consider the accessibility, reliability and documentation benefits are worth the time investment.

Automation

XKCD