Tuesday, October 24, 2017

[kawtunfn] Massively editing history

git blame (or similar in other version control tools) is code documentation: why is the code like this?

Then, much like other documentation, we probably want processes to make this documentation nice, and iteratively making revisions to improve it.  git commit --amend can make a new version of a commit message, but we cannot undo, cannot view the history of the history.

More complicated changes involve splitting or merging commits.

There's a temptation to clean up history, but recording the thing that didn't work is again useful as code documentation: why is the code like this?

Perhaps one path which documents how the code was actually made over time, and separate paths (arriving at the same destination) written by the documentation writers which provide the clearest story.  Paths can be continually revised by creating new paths, keeping old ones. Documentation writers can promote their path as the main line, even though it chronologically wasn't what happened.


No comments :