sbp commented on PR #345: URL: https://github.com/apache/tooling-trusted-releases/pull/345#issuecomment-3572220397
Note that we already have a similar [convention for code comments](https://release-test.apache.org/docs/code-conventions): > Each sentence forming a comment must occupy its own line. But comments should be terse, so this helps as much to constrain verbosity as to formatting of rudimentary diff output. Documentation, on the other hand, is unavoidably long form. I think that the source and its presented output should match, for readability purposes, and that this criterion is of higher priority than making up for the shortcomings of diff tools. Although in some cases, such as #331, we make concessions when external tools fall short, in this case I think it is important that diffs be designed to show changes within lines. To put it another way, I don't think that we should encourage poor diff tools by sacrificing the readability of our documentation source. Note that e.g. the GitHub diff output shows changes within lines as well as changes between lines, so certainly not all diff tools get this wrong. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
