Re: [Feedback Request] Improving tracking of doc revisions

Andreas Heigl <[email protected]> Mon, 7 Dec 2020 17:30:57 +0100
Newsgroups	gmane.comp.php.documentation.general
Message-ID	<[email protected]>
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                               |
+---------------------------------------------------------------------+
signature.asc (application/pgp-signature, 833 B)