doc-base icon indicating copy to clipboard operation
doc-base copied to clipboard

Strict `[skip-revcheck]`

Open alfsb opened this issue 7 months ago • 9 comments

This is a tentative PR to fix the issues below. This PR changes doc-base's revcheck.php to:

  1. Strictly checks for [skip-revcheck] as the first text on the first line of a commit message;
  2. Strictly ignore a sequence of [skip-revcheck] commits.

Issue one

First observe the contents of commit https://github.com/php/doc-en/commit/8f6fd5c55ab10709a4ff8daf6140dea422c1363c and after his commit message, below:

    Add missing libxml related constants (#3388)
    * [skip-revcheck] Fix whitespace
    * Add missing libxml related constants

This commit should mark the translations as outdated or be skiped?

As now, the code searches for [skip-revcheck] in any part of the commit message. See: https://github.com/php/doc-base/blob/8b3169819f3598ed6ac14597591d1630be4dff04/scripts/revcheck.php#L302-L305

Issue two

Observe these commit history:

  • https://github.com/php/doc-en/commits/765b2d6eec7dfbaeed900b32aa91a1360d73df42/language/context/parameters.xml
  • https://github.com/php/doc-en/commits/765b2d6eec7dfbaeed900b32aa91a1360d73df42/reference/ds/ds.deque.xml

That is, a sequence of commits marked with [skip-revcheck]. Should these files be marked as outdated each time there are two or more commits marked with [skip-revcheck] in sequence?

The current code always gets the commit -2 of history when the last commit is marked [skip-revcheck]. See: https://github.com/php/doc-base/blob/8b3169819f3598ed6ac14597591d1630be4dff04/scripts/revcheck.php#L384

Possible another issue

In the case of https://github.com/php/doc-en/commits/765b2d6eec7dfbaeed900b32aa91a1360d73df42/reference/ds/ds.deque.xml , with the hashes and messages as:

4d17b7 [skip-revcheck] Convert class markup to be compatible with DocBook 5.2
6cecca [skip-revcheck] Normalize &Constants; and &Methods; usage (#2703)
b2a26b These should include the namesapce

What hash should appear in revcheck as the "target" of translations and diffs? The most recent (4d17b7) or the last non-skipped (b2a26b)?


The first issue caused about 40 files to not be marked outdated in all translations. The second issue is harder to calculate, as it involves analysing the commit history of each file, against each revtag.

If this PR gets approval, it will generate about a hundred of files to be marked as outdated in all translations, and will also desynchronize the revcheck script of doc-base and web-doc.

I plan to, after merging this, to change the lib version of this code in doc-base/tree/master/scripts/translation to reflect the new strict rules on lib code, and to open issues against code duplication on doc-base and web-doc. I would also resolve the issue against doc-base, but I probably will not tackle the web-doc issue as I do not know to test or deploy this infrastructure.

alfsb avatar Jul 10 '24 19:07 alfsb