doc-base
doc-base copied to clipboard
Strict `[skip-revcheck]`
This is a tentative PR to fix the issues below. This PR changes doc-base's revcheck.php
to:
- Strictly checks for
[skip-revcheck]
as the first text on the first line of a commit message; - 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.