Write a Manifest file in your software repos

In my source code repositories, in addition to the expected README file, I maintain a Manifest.org file.

In the shipping context, a manifest is a list of what's inside your ship. In a similar fashion, the manifest file of your software project should list the various files in your repos, along with a human readable explanation of their purpose.

A search reveals that I first had this idea in november of 2021.

find ~/src -iname "manifest.org" -printf "%T+ %p\n" | sort | head -n 1

2021-11-19+17:00:39.3819930460 /home/edouard/src/denatting/MANIFEST.org

but I was clearly not the first, as the wikipedia article on the matter was written in 2007.

But the wikipedia article is about manifest destined to be read by programs, whereas my manifests are written to be read by humans.

Indeed, denatting, the project that spawned the idea, was broken down in many files and I, who wrote the damn stuff, could hardly find my way around it.

Writing it all in a structured way as if I had to explain it to an unknowledgable third party forced me to adopt a clearer structure and to explicit some intuitive decisions I had made during the project's development.

I've since adopted the practice as routine, using an org-mode file. org-mode allows me to link not only to the files, but to specific parts of files in a regex-based manner, allowing me to be as detailed as I need in my manifests.

Also, I can link to resources external to the project: my timekeeping files for client billing, my zettelkasten notes, or even web resources.

I've recently found a new use for them: giving context to LLMs. For any serious use of LLMs in coding, I found myself tediously explaining to the LLM the context of the change I was about to make in the code. To help me now, I just add the manifest to the context, and because my emacs system also gives the LLM the name of the file I'm currently working on, I get way better answers than before, as the LLM is aware of the code organization and how the pieces fit together.

But a description of that system is a story for another day :)