Docs branching model – does it work well for Nette docs?
- BorekB
- Member | 3
(Asking this out of curiosity.)
We have a documentation system quite similar to Nette docs, i.e. text files converted to HTML on the fly, multiple language versions, multiple branches for various releases etc. What seems to be slightly unpleasant is to deal with the version branches, i.e., in Nette's world, maintaining content in all those 2.1, 2.2, 2.3 etc. releases, merging or cherry picking between them etc.
One possible alternative would be to use a concept similar to Feature Toggles, i.e. maintain just one set of documentation files (a single branch) and somehow marking various doc topics or maybe even their paragraphs as only suitable for certain versions. It would then be up to the public website to dynamically filter the contents appropriately.
Has this been considered for Nette docs or are you guys generally happy with the current process / system? Doesn't it happen that you sometimes forget to bring certain documentation from one branch to the other? Don't you have issues with merge conflicts if some of the content has been cherry-picked to another branch before?
Thanks.
- Filip Procházka
- Moderator | 4668
I'd say the process is fine for this type of OS project. There is always a possibility of forgetting to cherrypick something, but that's not a big deal and can be fixed easily :)
Nice idea with the “feature toggle”, that might be interesting to see in practice. But it might also end up beeing a big bloated file for every topic. Imagine if the page gets really complex for future version and then you'd want to split the page up. It might get more complicated than the current solution. But I don't know… we'd have to see that in practice :)
- Jan Tvrdík
- Nette guru | 2595
The problem with feature toggle approach is that it does not scale well. The more versions you have the harder it will be to manage. With the branching model you can simply ignore the old versions. The older the version is the less updates it will receive.