4 ms·

I find the temporarily localized documentation idea quite interesting – anyone else here tried that? > Such an approach only works if your system is small, I

by patrec 7y ago

I find the temporarily localized documentation idea quite interesting – anyone else here tried that? > Such an approach only works if your system is small, I see no reason why this wouldn't scale if you (and other people working on the same codebase) just maintain individual branches (say "dang-braindump"). Just do exploratory/documentation work on that and cherry-pick, rebase -i or git merge --ff --squash --no-commit to skip the reverts.

NateEag 7y ago
> I find the temporarily localized documentation idea quite interesting – anyone else here tried that? I've done this a bit. For several of my $DAYJOB projects I maintain documentation as Markdown files in the project, which get rendered into a website at build time. The project changelog is kept in version control the same way (https://keepachangelog.com https://keepachangelog.com). Several times I've tried an experiment or alternate approach that didn't work out and done exactly this, complete with documentation, so the state is preserved. It's easy to document a prototype if it just means throwing a few paragraphs into a text file with the prototype. Add a note in the changelog about adding the prototype then commit. Make the revert commit and add a note in the changelog that you've removed the prototype. Keeping a good, human-readable changelog as described above makes this strategy more scalable. You can document failed experiments you backed out, features that have been removed, and the like, in a few quick summary lines, keeping devs aware of them across the project's lifespan. New devs can review it for the big-picture history and use the changelog's revision history to see what commits they need to see for the details. Using a changelog this way also makes it reasonably possible to delete code but still remember it existed years later, something that's otherwise a surprisingly hard problem (especially if the project has high turnover).
- patrec 7y ago
  Thanks for sharing! I'm not a big fan of changelogs, personally, except for publicly released projects. I prefer to have workflows that use version control for this. Reverting on master, but tracking the prototype in the changelog is a nice hack, but has a cost in terms of clutter, ability to bisect etc. I think I would prefer something branch based, but I haven't yet properly thought about the best way of doing it. If you have a special prototype branch from which you merge in master and do your prototyping, reverting and optionally notes.md there, you might effectively be able to replace the changelog based flow with just doing git log --no-merges --first-parent. What do you think?
  - NateEag 7y ago
    I think as the number of branches grows, people will just start to drown in the huge list of unmerged branches and will start to work as if only trunk/master exists. With a text file that summarizes all the project's main line of history in a structured, linear way, it's very simple to extract just what you're interested in or find all the entries for a particular thread of research across history, quickly. I don't think the tooling around git branches really enables that kind of operation in a quick, easy way, partly due to the inherent nature of branches. I'd be interested to see what your hypothetical workflow turns out like in practice, though. It's certainly possible I'm just not seeing the potential.

by patrec 7y ago

NateEag 7y ago

> I find the temporarily localized documentation idea quite interesting – anyone else here tried that? I've done this a bit. For several of my $DAYJOB projects I maintain documentation as Markdown files in the project, which get rendered into a website at build time. The project changelog is kept in version control the same way (https://keepachangelog.com https://keepachangelog.com). Several times I've tried an experiment or alternate approach that didn't work out and done exactly this, complete with documentation, so the state is preserved. It's easy to document a prototype if it just means throwing a few paragraphs into a text file with the prototype. Add a note in the changelog about adding the prototype then commit. Make the revert commit and add a note in the changelog that you've removed the prototype. Keeping a good, human-readable changelog as described above makes this strategy more scalable. You can document failed experiments you backed out, features that have been removed, and the like, in a few quick summary lines, keeping devs aware of them across the project's lifespan. New devs can review it for the big-picture history and use the changelog's revision history to see what commits they need to see for the details. Using a changelog this way also makes it reasonably possible to delete code but still remember it existed years later, something that's otherwise a surprisingly hard problem (especially if the project has high turnover).

patrec 7y ago
Thanks for sharing! I'm not a big fan of changelogs, personally, except for publicly released projects. I prefer to have workflows that use version control for this. Reverting on master, but tracking the prototype in the changelog is a nice hack, but has a cost in terms of clutter, ability to bisect etc. I think I would prefer something branch based, but I haven't yet properly thought about the best way of doing it. If you have a special prototype branch from which you merge in master and do your prototyping, reverting and optionally notes.md there, you might effectively be able to replace the changelog based flow with just doing git log --no-merges --first-parent. What do you think?
- NateEag 7y ago
  I think as the number of branches grows, people will just start to drown in the huge list of unmerged branches and will start to work as if only trunk/master exists. With a text file that summarizes all the project's main line of history in a structured, linear way, it's very simple to extract just what you're interested in or find all the entries for a particular thread of research across history, quickly. I don't think the tooling around git branches really enables that kind of operation in a quick, easy way, partly due to the inherent nature of branches. I'd be interested to see what your hypothetical workflow turns out like in practice, though. It's certainly possible I'm just not seeing the potential.