Re: [Feedback Request] Improving tracking of doc revisions

On Mon, 7 Dec 2020 at 16:31, Andreas Heigl <[email protected]> wrote:

> Hey George, hey List
>
> Am 07.12.20 um 17:11 schrieb G. P. B.:
> > 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?
>
> Nope. Your understanding was right, that currently translators would
> need to update a separate file along with the actually translated file.
> That file contains the relative path of the translated file as well as
> the hash of the english file this translation is based upon.
>
> But currently – even though we could pull the trigger at any time given
> that someone would actually react to the mails I'm writing to the
> different mailinglists – that would mean that we would loose the
> revcheck functionality as that is not yet completely implemented. Partly
> due to the fact that there are 2 completely different
> revcheck-implementations of which I already fixed one - sadly not the
> one used in production. During a call with Gabriel Caruso and Paul
> Dragoonis we had the idea of postponing the revcheck to a later state
> and first move the documentation over and then shortly afterward give
> the community the possibility to fix the revcheck.
>

ACK, sadly can't help with access nor pulling the trigger as I have no
access either.
Is the issue of the one in production only an issue about getting
access to the server and updating it or is it a completely different one?


> >
> > 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.
>
> Because implementing that at this stage of the project would more or
> less mean going back to the beginning.
>
> Though to be honest: The separate file was only a temporary solution as
> we couldn't rewrite the files themselves. The original idea was to
> replace the revision with the hash but that only works when moving in
> one go from SVN to git as rewriting the history is not the issue but
> merging the next revision into that changed history as the relation is
> lost. So the separate file was the easiest solution. If we want to
> modify that behaviour later that should not be a technical issue.
>
> Though I would give it a second thought as currently the single file has
> the advantage that there is one less git request per file necessary for
> building the revcheck-information.
>
> For the current transition I would rather not change anything more in
> the current setup as it is already complicated enough to keep everything
> together with the slow response cycles I see. So I'd rather get the
> current project finished and then optimize the result in a later step
> that trying to get perfection deployed as that will mean we will stay on
> SVN for a much longer time.
>
> So instead of bringing up new ideas and improvements I would aprechiate
> some actual decisions and implementations from those that are
> responsible. Whether that is via actions or via handing over the
> responsibility is irrelevant.
>
> Sorry George for the perhaps negative sounding response. I really like
> the idea! But let's try to move this in 2 steps!
>


Honestly, the idea is mostly based on how to work when the docs would
already be under git, so totally fine to have this in 2 steps instead of
one.
But liking the idea is already a good thing in my book. :-)

Best,

George P. Banyard

On Mon, 7 Dec 2020 at 16:31, Andreas Heigl <[email protected]> wrote:

> Hey George, hey List
>
> Am 07.12.20 um 17:11 schrieb G. P. B.:
> > 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?
>
> Nope. Your understanding was right, that currently translators would
> need to update a separate file along with the actually translated file.
> That file contains the relative path of the translated file as well as
> the hash of the english file this translation is based upon.
>
> But currently – even though we could pull the trigger at any time given
> that someone would actually react to the mails I'm writing to the
> different mailinglists – that would mean that we would loose the
> revcheck functionality as that is not yet completely implemented. Partly
> due to the fact that there are 2 completely different
> revcheck-implementations of which I already fixed one - sadly not the
> one used in production. During a call with Gabriel Caruso and Paul
> Dragoonis we had the idea of postponing the revcheck to a later state
> and first move the documentation over and then shortly afterward give
> the community the possibility to fix the revcheck.
> >
> > 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.
>
> Because implementing that at this stage of the project would more or
> less mean going back to the beginning.
>
> Though to be honest: The separate file was only a temporary solution as
> we couldn't rewrite the files themselves. The original idea was to
> replace the revision with the hash but that only works when moving in
> one go from SVN to git as rewriting the history is not the issue but
> merging the next revision into that changed history as the relation is
> lost. So the separate file was the easiest solution. If we want to
> modify that behaviour later that should not be a technical issue.
>
> Though I would give it a second thought as currently the single file has
> the advantage that there is one less git request per file necessary for
> building the revcheck-information.
>
> For the current transition I would rather not change anything more in
> the current setup as it is already complicated enough to keep everything
> together with the slow response cycles I see. So I'd rather get the
> current project finished and then optimize the result in a later step
> that trying to get perfection deployed as that will mean we will stay on
> SVN for a much longer time.
>
> So instead of bringing up new ideas and improvements I would aprechiate
> some actual decisions and implementations from those that are
> responsible. Whether that is via actions or via handing over the
> responsibility is irrelevant.
>
> Sorry George for the perhaps negative sounding response. I really like
> the idea! But let's try to move this in 2 steps!
>
>
> Cheers
>
> Andreas
> > 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
>
> --
>                                                               ,,,
>                                                              (o o)
> +---------------------------------------------------------ooO-(_)-Ooo-+
> | Andreas Heigl                                                       |
> | mailto:[email protected]                  N 50°22'59.5" E 08°23'58" |
> | https://andreas.heigl.org                                           |
> +---------------------------------------------------------------------+
> | https://hei.gl/appointmentwithandreas                               |
> +---------------------------------------------------------------------+
>
>