Bernd Zeimetz <be...@bzed.de> writes: > So in general if there are such big and non-obvious changes to > documents, I think the best option would be to have (require?) a side by > side diff as PDF or in some other readable format available.
Wouter and I attempted to provide that via Salsa diffs, although the available formatting options may not have included the specific format you reference. I don't think any of our templates are currently set up for this, but I would love to see any proposed future foundational document changes come in merge request form or some equivalent, with links to available diff formats in the ballot email message. Chances are high that Gitlab or some other Git-based tool will have way more options for showing a diff in a useful format than I would be able to think up. I hadn't thought of that when we started this process, but it became obvious via the process that this is the most readable representation of the changes. I'm not sure what to do about the GR itself. Ideally, I think the merge request would be the text of the GR apart from any pre-amble or motivation section. I wrote the GR itself as essentially a set of change instructions, which was somewhat laborious to do and not very readable, and I was quite worried that I would accidentally introduce some inconsistency between the change instructions and the merge request that would sneak through unnoticed. It would be nice to not have to describe a change in two different ways and try to keep them in sync. -- Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>