gen-addon-readme: add --keep-source-digest

tests/test_gen_addon_readme.py

@@ -5,13 +5,15 @@
 import shutil
 import subprocess
 import sys
+from pathlib import Path
 
 import pytest
 
 from tools.gen_addon_readme import (
     get_fragment_format,
     get_fragments_format,
     safe_remove,
+    _get_source_digest,
 )
 
 
@@ -81,6 +83,36 @@ def test_gen_addon_readme_if_fragments_changed(addons_dir):
         assert not readme_file.read().endswith("trailer")
 
 
+def test_gen_addon_readme_keep_source_digest(addons_dir):
+    cmd = [
+        sys.executable,
+        "-m",
+        "tools.gen_addon_readme",
+        "--addon-dir",
+        "addon1",
+        "--repo-name",
+        "server-tools",
+        "--branch",
+        "12.0",
+    ]
+    readme_filename = os.path.join(addons_dir, "addon1", "README.rst")
+    assert not os.path.exists(readme_filename)
+    subprocess.check_call(cmd, cwd=str(addons_dir))
+    assert os.path.exists(readme_filename)
+    source_digest = _get_source_digest(readme_filename)
+    # change something and check the previous source digest is preserved
+    chunk_path = Path(addons_dir, "addon1", "readme", "DESCRIPTION.rst")
+    with chunk_path.open("a") as f:
+        f.write("* CHUNK\n")
+    subprocess.check_call([*cmd, "--keep-source-digest"], cwd=str(addons_dir))
+    assert _get_source_digest(readme_filename) == source_digest
+    # change something again and check the source digest is changed
+    with chunk_path.open("a") as f:
+        f.write("* CHUNK2\n")
+    subprocess.check_call([*cmd], cwd=str(addons_dir))
+    assert _get_source_digest(readme_filename) != source_digest
+
+
 def test_gen_addon_readme_acme(addons_dir):
     cmd = [
         sys.executable,
@@ -167,3 +199,13 @@ def test_safe_ramove(tmp_path):
     safe_remove(file_path)
     assert not file_path.exists()
     safe_remove(file_path)  # removing non-existent file does not raise
+
+
+def test_get_source_digest(tmp_path):
+    readme_path = tmp_path / "README.rst"
+    readme_path.write_text("blah\n!! source digest: sha256:abc123\n...")
+    assert _get_source_digest(str(readme_path)) == "sha256:abc123"
+    readme_path.unlink()
+    assert _get_source_digest(str(readme_path)) is None
+    readme_path.write_text("!! source digest: ")
+    assert _get_source_digest(str(readme_path)) is None

tools/gen_addon_readme.py

@@ -8,6 +8,7 @@
 import re
 import sys
 import tempfile
+from pathlib import Path
 from typing import Union
 from urllib.parse import urljoin
 
@@ -433,6 +434,21 @@ def _source_digest_match(readme_filename, source_digest):
     return False
 
 
+def _get_source_digest(readme_filename: str) -> Union[str, None]:
+    """Get the source digest from the given readme file.
+
+    Return None if the file does not exist, or if the digest is not found.
+    """
+    readme_path = Path(readme_filename)
+    if not readme_path.is_file():
+        return None
+    digest_re = re.compile(r"!! source digest: (?P<digest>sha256:\w+)")
+    mo = digest_re.search(readme_path.read_text(encoding="utf8"))
+    if not mo:
+        return None
+    return mo.group("digest")
+
+
 @click.command()
 @click.option("--org-name", default="OCA", help="Organization name, eg. OCA.")
 @click.option("--repo-name", required=True, help="Repository name, eg. server-tools.")
@@ -458,6 +474,16 @@ def _source_digest_match(readme_filename, source_digest):
     default=False,
     help="Only generate if source fragments or manifest changed.",
 )
+@click.option(
+    "--keep-source-digest",
+    is_flag=True,
+    default=False,
+    help=(
+        "Do not update the source digest in the generated file. "
+        "Useful to avoid merge conflicts when changes that do not impact "
+        "the generated file are made to the manifest."
+    ),
+)
 @click.option(
     "--commit/--no-commit",
     help="git commit changes to README.rst and index.html, if any.",
@@ -491,6 +517,7 @@ def gen_addon_readme(
     template_filename,
     if_fragments_changed,
     convert_fragments_to_markdown,
+    keep_source_digest,
 ):
     """Generate README.rst from fragments.
 
@@ -523,6 +550,8 @@ def gen_addon_readme(
         if if_fragments_changed:
             if _source_digest_match(readme_filename, source_digest):
                 continue
+        if keep_source_digest:
+            source_digest = _get_source_digest(readme_filename) or source_digest
         gen_one_addon_readme(
             org_name,
             repo_name,