When I've done it, I've done it as a status log at the bottom of the README, or in a separate file in the project. But I think your level of detail is just right: it doesn't look ridiculously time consuming, and yet it captures the real content & momentum of the project.

Thanks for the link, that's pretty interesting. Do you use a modification of this now, or have you simply codified that approach internally and commit intuitively?

I often run git blame to track down and reread old commit logs. But yeah the new codebase kinda dilutes the point because I'm changing so many things at once. It's an exercise in making a codebase as self-documenting and approachable to outsiders as possible in a variety of ways.

The numbered filenames are one example. Each file is intended to be self-contained, and later files build on earlier ones. No need to hack on makefiles to add a new file. Just create it, number it right, and it'll get compiled, with access to everything in earlier files.

Since this is a lisp interpreter the ethos translates to lisp functions as well. I can improve performance by deleting a lisp function, reimplementing it in a new .cc file, and restarting the interpreter. The interpreter will transparently run make, which will transparently compile the new file. And tests on the lisp function will continue to pass if I did the translation right.

There's a README (http://github.com/akkartik/wart#readme) that tries to convey my goals, but I haven't had too many people read it yet. I'd love to hear what isn't clear. You aren't supposed to know lisp to understand it.