[Feedback Request] Improving tracking of doc revisions

Hello the documentation list, I've been thinking about ways to improve the tracking of revisions for translations. I've read one of the previous discussions [1] referenced in bug 44903. [2] I agree with the following point which has been made, the revision number/id should be performed automatically, as it is way too easy to forget to do it manually, even with a pre-commit hook. However, just basing ourselves on the commit revision/ID as it's currently done is a massive pain points for translations, mistakes can arise and the commit revert of vrana's changes is an unfortunate example, moreover, any whitespace changes or auto correction of code formatting is currently IMHO a no go as it would wreck the "up to date" status of translations which cannot blindly apply the script and update their revision number except if they are 100% up to date before said commit. An added benefit would also be if we figure out a system which allows a revision to pass without messing up the translation status we can freely apply typo fixes to the English revision and/or rewrite sections to adhere to the style guide (a big one would be using "as of" instead of "since"). [3] Another concern I have is with the migration from SVN to git, I've CCed Andreas as the leader of this project from my understanding. I haven't totally kept up with the project's status, but it seems close to pulling the trigger. I might be wrong but I saw mentions for translators to need to update a separate file then the one they are translating, is this just a misunderstanding from my part? Or is this file only generated once to be used as a hash map for SVN revision to git commit ID for the revcheck script/status? If the former, why not use the git attribute "ident" [4] (something I've learned the existence of only recently) which would allow us to work similarly to how it is currently done on SVN. Now onto my idea/proposal for improving this situation, as brought up in the discussion from a couple of years I propose that we "abuse" of the DocBooks revhistory tag, [5] by including only one revision child element [6] that is used as an anchor. The revision tag would contain the following child elements: - revnumber, [7] which is generated by the git indent attribute to populate the git commit - date, [8] the date the commit identified by revnumber is **applied*, I would imagine a git filter [9] could be used to achieve this automatically - author or authorinitials, [10][11] this would replace the "maintainer" tag we currently have for translations. For this to work only the doc-en repo would have the ident attribute [4] set, as this is only relevant for the English revision, this would hopefully also make structural changes, such as the current union type declarations changes, easier to automatically apply for translations as a patch command would also handle the revision tag update. An added benefit for adding the date element is that down the line we could start rendering the last time this file has been "reviewed" in the online docs and build tooling around looking at potentially very outdated docs. Looking at how we would migrate to the new system I envisioned the following: - Only add this revision tag on new updates (no mass edit to not mess up with the translation status), for this a pre-commit check on doc-en would be put in place to ensure all files being edited have the new system in place. - Translations update the file as normal when they get round to hit and this file is then on the new system. This would imply that the revcheck script would first look for this new tag, then fallback to the current way of operating to establish the commit ID/revision. The translations should also have a git filter [9] to automatically update the date. To add "skipping commits" capability, it looks to me, from my limited understanding or git attributes, that the ident attribute [4] behaviour can be modified with a filter [9] in which changes comprised of only whitespaces or the commit message prefixed with something akin to "[typo]" would not change the id in the revnumber tag. I hope this long email makes enough sense that I can get opinions/feedback about this proposal/change to the doc handling. Best regards, George P. Banyard [1] http://php.markmail.org/message/3t2pmgoq35h5ogep [2] https://bugs.php.net/bug.php?id=44903 [3] http://doc.php.net/tutorial/style.php [4] https://git-scm.com/docs/gitattributes#_ident [5] https://tdg.docbook.org/tdg/5.1/revhistory.html [6] https://tdg.docbook.org/tdg/5.1/revision.html [7] https://tdg.docbook.org/tdg/5.1/revnumber.html [8] https://tdg.docbook.org/tdg/5.1/date.html [9] https://git-scm.com/docs/gitattributes#_filter [10] https://tdg.docbook.org/tdg/5.1/author.html [11] https://tdg.docbook.org/tdg/5.1/authorinitials.html