The `check-trans-update.py` scripts check whether a translated version
of a documentation is up-to-date with the english version.
The scripts use `git log` commit to find the latest english commit from
the translation commit (order by author date) and the latest english
commits from HEAD. If differences occurs, report the file and commits
need to be updated.
Signed-off-by: Cheng Ziqiu <[email protected]>
---
scripts/check-trans-update.py | 176 ++++++++++++++++++++++++++++++++++
1 file changed, 176 insertions(+)
create mode 100755 scripts/check-trans-update.py
diff --git a/scripts/check-trans-update.py b/scripts/check-trans-update.py
new file mode 100755
index 000000000000..0f913c5c4555
--- /dev/null
+++ b/scripts/check-trans-update.py
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+
+import os
+from argparse import ArgumentParser, BooleanOptionalAction
+from datetime import datetime
+
+flag_p_c = False
+flag_p_uf = False
+flag_debug = False
+
+
+def dprint(*args, **kwargs):
+ if flag_debug:
+ print("[DEBUG] ", end="")
+ print(*args, **kwargs)
+
+
+def get_origin_path(file_path):
+ paths = file_path.split("/")
+ tidx = paths.index("translations")
+ opaths = paths[:tidx]
+ opaths += paths[tidx + 2 :]
+ return "/".join(opaths)
+
+
+def get_latest_commit_from(file_path, commit):
+ command = "git log --pretty=format:%H%n%aD%n%cD%n%n%B {} -1 -- {}".format(
+ commit, file_path
+ )
+ dprint(command)
+ pipe = os.popen(command)
+ result = pipe.read()
+ result = result.split("\n")
+ if len(result) <= 1:
+ return None
+
+ dprint("Result: {}".format(result[0]))
+
+ return {
+ "hash": result[0],
+ "author_date": datetime.strptime(result[1], "%a, %d %b %Y %H:%M:%S %z"),
+ "commit_date": datetime.strptime(result[2], "%a, %d %b %Y %H:%M:%S %z"),
+ "message": result[4:],
+ }
+
+
+def get_origin_from_trans(origin_path, t_from_head):
+ o_from_t = get_latest_commit_from(origin_path, t_from_head["hash"])
+ while o_from_t is not None and o_from_t["author_date"] > t_from_head["author_date"]:
+ o_from_t = get_latest_commit_from(origin_path, o_from_t["hash"] + "^")
+ if o_from_t is not None:
+ dprint("tracked origin commit id: {}".format(o_from_t["hash"]))
+ return o_from_t
+
+
+def get_commits_count_between(opath, commit1, commit2):
+ command = "git log --pretty=format:%H {}...{} -- {}".format(commit1, commit2, opath)
+ dprint(command)
+ pipe = os.popen(command)
+ result = pipe.read().split("\n")
+ # filter out empty lines
+ result = list(filter(lambda x: x != "", result))
+ return result
+
+
+def check_per_file(file_path):
+ opath = get_origin_path(file_path)
+
+ if not os.path.isfile(opath):
+ dprint("Error: Cannot find the origin path for {}".format(file_path))
+ return
+
+ o_from_head = get_latest_commit_from(opath, "HEAD")
+ t_from_head = get_latest_commit_from(file_path, "HEAD")
+
+ if o_from_head is None or t_from_head is None:
+ print("Error: Cannot find the latest commit for {}".format(file_path))
+ return
+
+ o_from_t = get_origin_from_trans(opath, t_from_head)
+
+ if o_from_t is None:
+ print("Error: Cannot find the latest origin commit for {}".format(file_path))
+ return
+
+ if o_from_head["hash"] == o_from_t["hash"]:
+ if flag_p_uf:
+ print("No update needed for {}".format(file_path))
+ return
+ else:
+ print("{}".format(file_path), end="\t")
+ commits = get_commits_count_between(
+ opath, o_from_t["hash"], o_from_head["hash"]
+ )
+ print("({} commits)".format(len(commits)))
+ if flag_p_c:
+ print("\t", end="")
+ print("\n\t".join(commits))
+
+
+def main():
+ script_path = os.path.dirname(os.path.abspath(__file__))
+ linux_path = os.path.join(script_path, "..")
+
+ parser = ArgumentParser(description="Check the translation update")
+ parser.add_argument(
+ "-l",
+ "--locale",
+ help="Locale to check when file is not specified",
+ )
+ parser.add_argument(
+ "--print-commits",
+ action=BooleanOptionalAction,
+ default=True,
+ help="Print commits between origin and translation",
+ )
+
+ parser.add_argument(
+ "--print-updated-files",
+ action=BooleanOptionalAction,
+ default=False,
+ help="Print files no need to be updated",
+ )
+
+ parser.add_argument(
+ "--debug",
+ action=BooleanOptionalAction,
+ help="Print debug information",
+ default=False,
+ )
+
+ parser.add_argument(
+ "files", nargs="*", help="File to check, if not specified, check all"
+ )
+ args = parser.parse_args()
+
+ global flag_p_c, flag_p_uf, flag_debug
+ flag_p_c = args.print_commits
+ flag_p_uf = args.print_updated_files
+ flag_debug = args.debug
+
+ # get files related to linux path
+ files = args.files
+ if len(files) == 0:
+ if args.locale is not None:
+ files = (
+ os.popen(
+ "find {}/Documentation/translations/{} -type f".format(
+ linux_path, args.locale
+ )
+ )
+ .read()
+ .split("\n")
+ )
+ else:
+ files = (
+ os.popen(
+ "find {}/Documentation/translations -type f".format(linux_path)
+ )
+ .read()
+ .split("\n")
+ )
+
+ files = list(filter(lambda x: x != "", files))
+ files = list(map(lambda x: os.path.relpath(os.path.abspath(x), linux_path), files))
+
+ # cd to linux root directory
+ os.chdir(linux_path)
+
+ for file in files:
+ check_per_file(file)
+
+
+if __name__ == "__main__":
+ main()
--
2.34.1
Cheng Ziqiu <[email protected]> writes:
> The `check-trans-update.py` scripts check whether a translated version
> of a documentation is up-to-date with the english version.
>
> The scripts use `git log` commit to find the latest english commit from
> the translation commit (order by author date) and the latest english
> commits from HEAD. If differences occurs, report the file and commits
> need to be updated.
>
> Signed-off-by: Cheng Ziqiu <[email protected]>
> ---
> scripts/check-trans-update.py | 176 ++++++++++++++++++++++++++++++++++
> 1 file changed, 176 insertions(+)
> create mode 100755 scripts/check-trans-update.py
From a *quick* look I see how this could be a useful tool. I think a
real requirement, though, is that a script like this start with a nice
comment saying what it does and how to use it. Most people will simply
stumble across it while looking at files in scripts/; without such a
comment, they will be hard put to know what it's for.
Scripts for the documentation should be well documented :)
Thanks,
jon
在 2024/4/22 21:20, Jonathan Corbet 写道:
> Cheng Ziqiu <[email protected]> writes:
>
>> The `check-trans-update.py` scripts check whether a translated version
>> of a documentation is up-to-date with the english version.
>>
>> The scripts use `git log` commit to find the latest english commit from
>> the translation commit (order by author date) and the latest english
>> commits from HEAD. If differences occurs, report the file and commits
>> need to be updated.
>>
>> Signed-off-by: Cheng Ziqiu <[email protected]>
>> ---
>> scripts/check-trans-update.py | 176 ++++++++++++++++++++++++++++++++++
>> 1 file changed, 176 insertions(+)
>> create mode 100755 scripts/check-trans-update.py
> From a *quick* look I see how this could be a useful tool. I think a
> real requirement, though, is that a script like this start with a nice
> comment saying what it does and how to use it. Most people will simply
> stumble across it while looking at files in scripts/; without such a
> comment, they will be hard put to know what it's for.
>
> Scripts for the documentation should be well documented :)
Yes, Ziqiu, can you describe the specific function of your script? just
like:
1. What work does my tool replace?
2. How to use it?
3. What features did I implement?
4. What other features do I plan to add in the future?
Finally, it would be great if you could write it up as a
check_trans_update.rst and put it in the patch set,
but of course provide both English and Chinese.
Maybe we can put it here:
Documentation/doc-guide/ ?
Thanks,
Yanteng
在 2024/4/22 14:58, Cheng Ziqiu 写道:
> The `check-trans-update.py` scripts check whether a translated version
> of a documentation is up-to-date with the english version.
>
> The scripts use `git log` commit to find the latest english commit from
> the translation commit (order by author date) and the latest english
> commits from HEAD. If differences occurs, report the file and commits
> need to be updated.
>
> Signed-off-by: Cheng Ziqiu <[email protected]>
> ---
> scripts/check-trans-update.py | 176 ++++++++++++++++++++++++++++++++++
Because we'll be typing its name a lot, it's important to consider
tabulating the
name. If it's easy to understand, choose a name that will slow down the tab
button's wear.
I gave your script a quick test and got the following output:
[siyanteng@kernelserver linux-next]$ ./scripts/check-trans-update.py
Documentation/translations/zh_CN/process/1.Intro.rst
[siyanteng@kernelserver linux-next]$
It seems that your script can't handle documents that never get updated.
You need to print a warning or hint.
[siyanteng@kernelserver linux-next]$ ./scripts/check-trans-update.py
Documentation/translations/zh_CN/rust/arch-support.rst
Documentation/translations/zh_CN/rust/arch-support.rst (8 commits)
2f4fe71fdd25ebb4e41aee3b467b54fbef332643
This seems to be just a merge, try to drop it?
81889e8523e63395b388f285c77ff0c98ea04556
01848eee20c6396e5a96cfbc9061dc37481e06fd
724a75ac9542fe1f8aaa587da4d3863d8ea292fc
90868ff9cadecd46fa2a4f5501c66bfea8ade9b7
e5e86572e3f20222b5d308df9ae986c06f229321
04df97e150c83d4640540008e95d0229cb188135
0438aadfa69a345136f5ba4f582e0f769450ee0d
Hmmm, How about printing it this way?
We need to update the following commits.
commit 81889e8523e6 ("RISC-V: enable building 64-bit kernels with rust support")
commit 01848eee20c6 ("docs: rust: fix improper rendering in Arch Supportpage")
commit 724a75ac9542 ("arm64: rust: Enable Rust support for AArch64")
commit 90868ff9cade ("LoongArch: Enable initial Rust support")
commit e5e86572e3f2 ("rust: sort uml documentation arch support table")
commit 04df97e150c8 ("Documentation: rust: Fix arch support table")
commit 0438aadfa69a ("rust: arch/um: Add support for CONFIG_RUST under x86_64 UML")
Thanks,
Yanteng