Most Open edX repositories contain at least one Makefile defining common development tasks. Here are some notes on tools and practices that can help us keep these relatively clean and maintainable.

Templates

Many of our Makefiles were created from templates in GitHub - openedx/edx-cookiecutters: Open edx public templates for apps, libraries and services. (for example, https://github.com/openedx/edx-cookiecutters/blob/master/python-template/%7B%7Bcookiecutter.placeholder_repo_name%7D%7D/Makefile ). Whenever we decide to change some aspect of how we want our Makefiles to work, we should make sure to update all of the relevant Makefile templates in this repository.

Linting

There are two main Makefile linters that we’re currently aware of: GitHub - mrtazz/checkmake: experimental linter/analyzer for Makefiles (written in Go) and GitHub - mcandre/unmake: a makefile linter (written in Rust, very new). We don’t yet use either of them, although perhaps we should. The only form of Makefile linting we currently use is a “selfcheck” make target that we often run in CI just to ensure that the file isn’t egregiously malformed.

Repo Health Checks

We have implemented several repository health checks that parse each repository’s main Makefile and look for things that we specifically want to be in it (or don’t want to be in it). Most of these are implemented in edx-repo-health/repo_health/check_makefile.py at master · openedx/edx-repo-health .

Codemods

We sometimes want to make a specific change in a large percentage of our Makefiles, for example when making dependency management improvements or adding new development utilities. Unfortunately, there isn’t yet a good Makefile parser/editor for Python; in fact, we’re unaware of any decent ones implemented in any language other than Perl (Makefile::DOM, etc.). So when we want to do a bulk Makefile edit, we’ve historically resorted to sed for simple changes and manual effort for more complex ones.