feat: deprecate .uccignore and upgrade additional_package (#1415)

**Issue number:** ADDON-75701 ## Summary ### Changes > The `.uccignore` gets deprecated (while still doing its job) and would warn users can now use `cleanup_output_files` of `additional_packaging.py` to do the same job. ### User experience > Users using `.uccignore` would get a deprecation notice and it would work as it is. Moreover, they would be redirected to the reference showing the example of how to do the same job as `.uccignore`. ## Checklist If your change doesn't seem to apply, please leave them unchecked. * [x] I have performed a self-review of this change * [x] Changes have been tested * [x] Changes are documented * [x] PR title follows [conventional commit semantics](https://www.conventionalcommits.org/en/v1.0.0/) --------- Signed-off-by: Viktor Tsvetkov <[email protected]> Co-authored-by: Kamil Kędziak <[email protected]> Co-authored-by: Viktor Tsvetkov <[email protected]> Co-authored-by: sgoral-splunk <[email protected]> Co-authored-by: srv-rr-github-token <[email protected]> Co-authored-by: soleksy-splunk <[email protected]> Co-authored-by: spanchal-crest <[email protected]>
splunk · Nov 13, 2024 · f6dd96f · f6dd96f
1 parent b94b228
commit f6dd96f
Show file tree

Hide file tree

Showing 9 changed files with 125 additions and 14 deletions.
diff --git a/.gitignore b/.gitignore
@@ -14,7 +14,7 @@ pip-wheel-metadata/UNKNOWN.dist-info/top_level.txt
 pip-wheel-metadata/UNKNOWN.dist-info/METADATA
 .vscode/settings.json
 .DS_Store
-.venv
+.venv*
 output
 # The following files should never be checked into git but can not be in the
 # ignore file due to poetry issues

diff --git a/docs/additional_packaging.md b/docs/additional_packaging.md
@@ -2,9 +2,22 @@
 
 To extend the build process, you can create a `additional_packaging.py` file in the same file level where you have your globalConfig file.
 
-This file should have the `additional_packaging` function, which accepts add-on name as its only argument.
+This file should at least have:
+
+- the `cleanup_output_files` function, which accepts `output_path` (str), `add-on name` (str) as its arguments.
+- the `additional_packaging` function, which accepts `add-on name` (str) as its only argument.
+
+First the `cleanup_output_files` function would be called from `ucc-gen` build process and then `additional_packaging` function.
 
 See the following example for proper usage:
 
-* Build custom UI after `ucc-gen` finishes all its necessary steps.
-* Use a workaround for a `ucc-gen` feature that has not been implemented.
+- Build custom UI after `ucc-gen` finishes all its necessary steps.
+- Use a workaround for a `ucc-gen` feature that has not been implemented.
+
+## Example
+
+Below is an example of additional_packaging.py containing both the implementations of functions.
+
+```python
+--8<-- "tests/testdata/test_addons/package_global_config_everything_uccignore/additional_packaging.py"
+```
diff --git a/docs/uccignore.md b/docs/uccignore.md
@@ -1,5 +1,8 @@
 # `.uccignore` file
 
+!!! warning "Deprecation Notice"
+    This feature has been deprecated from UCC framework as of v5.53.0 as the feature is ambiguous. You can achieve the same functionality using [additional_packaging.py](./additional_packaging.md). The `cleanup_output_files` provides a feature to clean up files after the source code has been copied.
+
 This feature can be used to remove files from the output **after** the UCC template files were copied and **before** the source of the
 add-on recursively overrides the output folder.
 

diff --git a/splunk_add_on_ucc_framework/commands/build.py b/splunk_add_on_ucc_framework/commands/build.py
@@ -176,6 +176,11 @@ def _get_ignore_list(
     if not os.path.exists(ucc_ignore_path):
         return []
     else:
+        logger.warning(
+            "The `.uccignore` feature has been deprecated from UCC and is planned to be removed after May 2025. "
+            "To achieve the similar functionality use additional_packaging.py."
+            "\nRefer: https://splunk.github.io/addonfactory-ucc-generator/additional_packaging/."
+        )
         with open(ucc_ignore_path) as ignore_file:
             ignore_list = ignore_file.readlines()
         ignore_list = [
@@ -629,15 +634,24 @@ def generate(
         os.path.abspath(os.path.join(source, os.pardir, "additional_packaging.py"))
     ):
         sys.path.insert(0, os.path.abspath(os.path.join(source, os.pardir)))
+        try:
+            from additional_packaging import cleanup_output_files
+
+            cleanup_output_files(output_directory, ta_name)
+        except ImportError:
+            logger.info(
+                "additional_packaging.py is present but does not have `cleanup_output_files`. Skipping clean-up."
+            )
+
         try:
             from additional_packaging import additional_packaging
 
             additional_packaging(ta_name)
-        except ImportError as e:
-            logger.exception(
-                "additional_packaging.py is present but not importable.", e
+        except ImportError:
+            logger.info(
+                "additional_packaging.py is present but does not have `additional_packaging`. "
+                "Skipping additional packaging."
             )
-            raise e
 
     if global_config:
         logger.info("Generating OpenAPI file")

diff --git a/tests/smoke/test_ucc_build.py b/tests/smoke/test_ucc_build.py
@@ -464,8 +464,8 @@ def summarize_types(raw_expected_logs):
 
 def test_ucc_generate_with_everything_uccignore(caplog):
     """
-    Checks the functioning of .uccignore present in a repo.
-    Compare only the files that shouldn't be present in the output directory.
+    Checks the deprecation warning of .uccignore present in a repo with
+    its functionality still working.
     """
     with tempfile.TemporaryDirectory() as temp_dir:
         package_folder = path.join(
@@ -476,6 +476,16 @@ def test_ucc_generate_with_everything_uccignore(caplog):
             "package_global_config_everything_uccignore",
             "package",
         )
+        # create `.uccignore` temporarily
+        ucc_file = path.join(path.dirname(package_folder), ".uccignore")
+        f = open(ucc_file, "w+")
+        f.write(
+            """**/**one.py
+bin/splunk_ta_uccexample_rh_example_input_two.py
+bin/wrong_pattern
+"""
+        )
+        f.close()
         build.generate(source=package_folder, output_directory=temp_dir)
 
         expected_warning_msg = (
@@ -492,9 +502,22 @@ def test_ucc_generate_with_everything_uccignore(caplog):
         removed = set(
             caplog.text.split("Removed:", 1)[1].split("INFO")[0].strip().split("\n")
         )
+        exp_msg = (
+            "The `.uccignore` feature has been deprecated from UCC and is planned to be removed after May 2025. "
+            "To achieve the similar functionality use additional_packaging.py."
+            "\nRefer: https://splunk.github.io/addonfactory-ucc-generator/additional_packaging/."
+        )
+        exp_info_msg = (
+            "additional_packaging.py is present but does not have `additional_packaging`."
+            " Skipping additional packaging."
+        )
 
+        assert exp_msg in caplog.text
+        assert exp_info_msg in caplog.text
         assert expected_warning_msg in caplog.text
         assert edm_paths == removed
+        # on successful assertion, we delete the file
+        os.remove(ucc_file)
 
         actual_folder = path.join(temp_dir, "Splunk_TA_UCCExample")
         # when custom files are provided, default files shouldn't be shipped
@@ -508,6 +531,36 @@ def test_ucc_generate_with_everything_uccignore(caplog):
             assert not path.exists(actual_file_path)
 
 
+def test_ucc_generate_with_everything_cleanup_output_files():
+    """
+    Checks the functioning of addtional_packaging.py's `cleanup_output_files`  present in a repo.
+    Compares only the files that shouldn't be present in the output directory.
+    """
+    with tempfile.TemporaryDirectory() as temp_dir:
+        package_folder = path.join(
+            path.dirname(path.realpath(__file__)),
+            "..",
+            "testdata",
+            "test_addons",
+            "package_global_config_everything_uccignore",
+            "package",
+        )
+        build.generate(source=package_folder, output_directory=temp_dir)
+
+        actual_folder = path.join(temp_dir, "Splunk_TA_UCCExample")
+        # when custom files are provided, default files shouldn't be shipped
+        files_should_be_absent = [
+            ("bin", "example_input_one.py"),
+            ("bin", "splunk_ta_uccexample_rh_example_input_one.py"),
+            ("bin", "splunk_ta_uccexample_rh_example_input_two.py"),
+            ("default", "redundant.conf"),
+            ("default", "nav", "views", "file_copied_from_source_code.xml"),
+        ]
+        for af in files_should_be_absent:
+            actual_file_path = path.join(actual_folder, *af)
+            assert not path.exists(actual_file_path)
+
+
 def test_ucc_generate_only_one_tab():
     package_folder = path.join(
         path.dirname(path.realpath(__file__)),

diff --git a/tests/testdata/test_addons/package_global_config_everything_uccignore/.uccignore b/tests/testdata/test_addons/package_global_config_everything_uccignore/.uccignore
diff --git a/...s/testdata/test_addons/package_global_config_everything_uccignore/additional_packaging.py b/...s/testdata/test_addons/package_global_config_everything_uccignore/additional_packaging.py
@@ -0,0 +1,22 @@
+
+from os.path import sep, exists, dirname, realpath, join
+from os import remove, system, _exit, WEXITSTATUS
+
+def cleanup_output_files(output_path: str, ta_name: str) -> None:
+    """
+    prepare a list for the files to be deleted after the source code has been copied to output directory
+    """
+    files_to_delete = []
+    files_to_delete.append(sep.join([output_path, ta_name, "default", "redundant.conf"]))
+    files_to_delete.append(sep.join([output_path, ta_name, "bin", "splunk_ta_uccexample_rh_example_input_two.py"]))
+    files_to_delete.append(sep.join([output_path, ta_name, "bin", "example_input_one.py"]))
+    files_to_delete.append(sep.join([output_path, ta_name, "bin", "splunk_ta_uccexample_rh_example_input_one.py"]))
+    files_to_delete.append(sep.join([output_path, ta_name, "bin", "file_does_not_exist.py"]))
+    files_to_delete.append(sep.join([output_path, ta_name, "default", "nav", "views", "file_copied_from_source_code.xml"]))
+
+    for delete_file in files_to_delete:
+        try:
+            remove(delete_file)
+        except (FileNotFoundError):
+            # simply pass if the file doesn't exist
+            pass
diff --git a/...al_config_everything_uccignore/package/default/nav/views/file_copied_from_source_code.xml b/...al_config_everything_uccignore/package/default/nav/views/file_copied_from_source_code.xml
@@ -0,0 +1,6 @@
+<note>
+    <to>World</to>
+    <from>Python</from>
+    <heading>Hello</heading>
+    <body>Hello World!</body>
+</note>
diff --git a/...ata/test_addons/package_global_config_everything_uccignore/package/default/redundant.conf b/...ata/test_addons/package_global_config_everything_uccignore/package/default/redundant.conf
@@ -0,0 +1,4 @@
+[redundant]
+key = value
+content_type = json
+parser = json