Re: [Feedback Request] Improving tracking of doc revisions

On Mon, 7 Dec 2020 at 16:31, Andreas Heigl <andreas@heigl.org> 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 <andreas@heigl.org> 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:andreas@heigl.org N > 50°22'59.5" E 08°23'58" | > | https://andreas.heigl.org > | > +---------------------------------------------------------------------+ > | https://hei.gl/appointmentwithandreas > | > +---------------------------------------------------------------------+ > >