3 ms·
A couple of techniques I've found useful: 1. "New and Notable" philosophy. Clear focus on documenting what is new and notable about each update. Putting it in
by jonathaneunice 11y ago
A couple of techniques I've found useful:
1. "New and Notable" philosophy. Clear focus on documenting what is new and notable about each update. Putting it in a larger context than just "this branch/this sprint" and making it meaningful to those who may not be deeply embedded in the project. (Learned/adopted from the Eclipse project).
2. Tagged comments. Be disciplined about tagging comments for specific purposes, such as `# TODO:` or `# FIXME:`, so that those working inside code can quickly jot down their thoughts and observations as they have them, while working, yet they can also be consolidated by IDE views or external grep scripts into broader reports about outstanding issues and options.
3. Labeled commit messages. I often include "ATP" in commit messages, meaning "all tests pass." While you might rightfully assume that actual releases or even pushes to upstream repositories pass all tests as a condition of release/push, my projects follow a "commit early, commit often" protocol that sees many intermediate stages committed to local repos. Unless you're committed to regularly and extensively pruning/grooming repo history, even minor commits are going to be pushed upstream eventually. So I try to embed in the messages shorthand notes about testing status. (A variation on this theme is to include urls to CI test runs.)
4. Diffable formats. Encode as many design notes, change logs, and other project narrative information into Markdown, YAML, RST, or other formats that can be easily diffed and tracked by version control systems over time. Microsoft Office, LibreOffice, and Google Docs also have built-in change tracking and collaboration features, making them another evolvable option, albeit with slightly less transparency than pure text formats.
5. Constant vigilance. A disciplined, repeated return to, and updating of, change logs, release notes, design notes, to-do lists, tagged comments, architecture descriptions, and the other documents that form the project narrative.