[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