docs(contributing): refactor scripts, update contributing docs

.github/workflows/build-test-release.yml

@@ -257,7 +257,7 @@ jobs:
           export PATH=$PATH:$CHROMEWEBDRIVER
           chromedriver --version
       - run: |
-          ./run_splunk.sh ${{ matrix.splunk.version }}
+          ./scripts/run_splunk.sh ${{ matrix.splunk.version }}
           until curl -Lsk "https://localhost:8088/services/collector/health" &>/dev/null ; do echo -n "Waiting for HEC-" && sleep 5 ; done
         timeout-minutes: 5
       - run: poetry run pytest tests/ui -m "${{ matrix.test-mark }}" --headless --junitxml=test-results/junit.xml
@@ -418,7 +418,7 @@ jobs:
           python3 -m pip install ./restapi_client_${{ matrix.splunk.version }}
       - run: mv out_${{ matrix.splunk.version }} output
       - run: |
-          ./run_splunk.sh ${{ matrix.splunk.version }}
+          ./scripts/run_splunk.sh ${{ matrix.splunk.version }}
           until curl -Lsk "https://localhost:8088/services/collector/health" &>/dev/null ; do echo -n "Waiting for HEC-" && sleep 5 ; done
         timeout-minutes: 5
       - run: python3 tests/testdata/expected_addons/expected_output_global_config_everything/client-test.py

.licenserc.yaml

@@ -46,8 +46,5 @@ header:
     - "splunk_add_on_ucc_framework/commands/init_template/**"
     - "splunk_add_on_ucc_framework/commands/import_from_aob.sh"
     - "splunk_add_on_ucc_framework/commands/imports.py"
-    - "scripts/compare_different_ucc_versions_output.sh"
-    - "scripts/include-rum.sh"
-    - "build-ui.sh"
     - "scripts/rum-script.html"
     - "mypy.ini"

docs/contributing.md

@@ -1,61 +1,34 @@
 # Contributing Guidelines
 
-## Development flow
-
-The instructions below utilize the [GitHub CLI tool](https://cli.github.com/), which you can install via HomeBrew:
-```bash
-brew install gh
-gh auth login
-```
-
-* The default development branch is `develop`. Use this branch for creating pull requests (PRs) for your features, fixes, documentation updates, etc. PRs to the `develop` branch should be merged using the squash option on GitHub.
-* When it's time for a release (handled by the UCC team), create a PR from `develop` to `main` using the following commands:
-```bash
-gh pr create --title "chore: merge develop into main" --body "" --head develop --base main
-# set automerge with merge commit to avoid accidentally squashing PR
-gh pr merge develop --auto --merge
-```
-
-* Ensure CI passes and await team review.
-* PR should be merged using **merge commit** option in GitHub (already included in the command)
-* Releases are made automatically (both on GitHub and PyPI), and a bot will push a commit to `main` with all necessary changes  (i.e. [like this](https://github.com/splunk/addonfactory-ucc-generator/commit/0c5e6802e1e52c37bf7131baf1b8264e5db30545))
-* After the release, backport the bot's changes to the `develop` branch (i.e. [#974](https://github.com/splunk/addonfactory-ucc-generator/pull/974)):
-
-```bash
-gh pr create --title "chore: merge main into develop" --body "" --head main --base develop
-# set automerge with merge commit to avoid accidentally squashing PR
-gh pr merge main --auto --merge
-```
-
-* If a release encounters issues requiring a quick bug fix (handled by the UCC team):
-  * Create a PR to the main branch with the fix, including tests that reproduce and then fix the issue.
-  * Ensure CI passes and await team review.
-  * Merge the PR using the merge commit option on GitHub.
-  * Backport the bug fix PR to the develop branch.
-
 ## Build and Test
 
 Prerequisites:
-- Node.js LTS version ([NodeJS](https://nodejs.org/en/download), or use [nvm](https://github.com/nvm-sh/nvm))
+- Node.js LTS version ([Node.js](https://nodejs.org/en/download), or use [nvm](https://github.com/nvm-sh/nvm))
 - Yarn Classic (`npm install --global yarn`)
 - Poetry 1.5.1. [Installation guide](https://python-poetry.org/docs/#installing-with-the-official-installer)
 
 If you are interested in contributing to the UI, the `ui` folder has a separate README.md.
 
-Build the UI in the `ui/dist` folder and copy the files to the static folder of the UCC.
+
+Script for building the backend, frontend, and spinning up the Docker container all at once:
+```bash
+./scripts/quick_start_ui.sh
 ```
-./build-ui.sh
+
+Build the UI in the `ui/dist` folder and copy the files to the static folder of the UCC.
+```bash
+./scripts/build_ui.sh
 ```
 
 Build a new local version of `ucc-gen`:
 
-```
+```bash
 poetry build
 ```
 
 ### Unit tests
 
-```
+```bash
 poetry run pytest tests/unit
 ```
 
@@ -65,17 +38,17 @@ If you need to run UI tests for the PR, add a "run-ui-tests" label before the PR
 UI tests will run automatically for any PR towards the `main` / `develop` branches, and on the `main` / `develop` branch as well. 
 
 1. With local version of ucc-gen, create a UCCExample add-on for the output directory:
-    ```
+    ```bash
     poetry run ucc-gen build --source tests/testdata/test_addons/package_global_config_everything/package
     ```
 2. Install docker, and run containerized Splunk Enterprise using script:
-    ```
-    ./run_splunk.sh
+    ```bash
+    ./scripts/run_splunk.sh
     ```
    There are mapped default Splunk ports to host. To use a different configuration, see [docker-splunk](https://splunk.github.io/docker-splunk/). Remember to mount the output package to the Splunk apps directory.
 3. Install any browser specific to this browser driver, such as [chromedriver](https://chromedriver.chromium.org/getting-started/) for Chrome.
 4. Run tests using the following command:
-    ```
+    ```bash
     poetry run pytest tests/ui
     ```
    Default test parameters use Splunk connection details and credentials from the earlier step, and `chromedriver` is used as a default webdriver.  
@@ -88,7 +61,7 @@ Consult with `pre-commit` documentation about what is the best way to install th
 
 To run it locally:
 
-```
+```bash
 pre-commit run --all-files
 ```
 
@@ -98,8 +71,8 @@ Documentation changes are also welcome!
 
 To verify changes locally:
 
-```
-poetry run mkdocs serve
+```bash
+poetry run mkdocs serve -a localhost:8001
 ```
 
 ## Issues and bug reports
@@ -117,3 +90,37 @@ To do the changes you think are needed, run the previous steps (build / test / l
 After you create a PR, all the needed reviewers will be added automatically by GitHub.
 
 Gotcha: The `semgrep` and `fossa` steps might fail if you are an external contributor. This is expected for now.
+
+## Release flow
+
+The instructions below utilize the [GitHub CLI tool](https://cli.github.com/), which you can install via HomeBrew:
+```bash
+brew install gh
+gh auth login
+```
+
+* The default development branch is `develop`. Use this branch for creating pull requests (PRs) for your features, fixes, documentation updates, etc. PRs to the `develop` branch should be merged using the squash option on GitHub.
+* When it's time for a release (handled by the UCC team), create a PR from `develop` to `main` using the following commands:
+```bash
+gh pr create --title "chore: merge develop into main" --body "" --head develop --base main
+# set automerge with merge commit to avoid accidentally squashing PR
+gh pr merge develop --auto --merge
+```
+
+* Ensure CI passes and await team review.
+* PR should be merged using **merge commit** option in GitHub (already included in the command)
+* Releases are made automatically (both on GitHub and PyPI), and a bot will push a commit to `main` with all necessary changes  (i.e. [like this](https://github.com/splunk/addonfactory-ucc-generator/commit/0c5e6802e1e52c37bf7131baf1b8264e5db30545))
+* After the release, backport the bot's changes to the `develop` branch (i.e. [#974](https://github.com/splunk/addonfactory-ucc-generator/pull/974)):
+
+```bash
+gh pr create --title "chore: merge main into develop" --body "" --head main --base develop
+# set automerge with merge commit to avoid accidentally squashing PR
+gh pr merge main --auto --merge
+```
+
+* If a release encounters issues requiring a quick bug fix (handled by the UCC team):
+  * Create a PR to the main branch with the fix, including tests that reproduce and then fix the issue.
+  * Ensure CI passes and await team review.
+  * Merge the PR using the merge commit option on GitHub.
+  * Backport the bug fix PR to the develop branch.
+

scripts/build_ui.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# Copyright 2024 Splunk Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+SCRIPT_DIR=$(cd $(dirname ${BASH_SOURCE[0]}) && pwd)
+REPO_ROOT_DIR=$(cd "$SCRIPT_DIR/.." && pwd)
+
+cd $REPO_ROOT_DIR/ui
+yarn run setup
+cd $REPO_ROOT_DIR
+
+cp -n -R ui/dist/build/ splunk_add_on_ucc_framework/package/appserver/static/js/build/

scripts/compare_different_ucc_versions_output.sh

@@ -1,4 +1,19 @@
 #! /usr/bin/env bash
+
+# Copyright 2024 Splunk Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # The script installs 2 different version of the `splunk-add-on-ucc-framework`,
 # builds the add-on, cleans up some folders and then prints the difference between
 # the 2 built versions.

scripts/include-rum.sh

@@ -1,5 +1,19 @@
 #!/bin/bash
 
+# Copyright 2024 Splunk Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Ensure there are exactly two arguments provided
 if [[ "$#" -ne 3 ]]; then
   echo "Usage: $0 <path to base HTML file> <path to script HTML file> <rum_access_token>"

scripts/quick_start_ui.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+
+# Copyright 2024 Splunk Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+SCRIPT_DIR=$(cd $(dirname ${BASH_SOURCE[0]}) && pwd)
+REPO_ROOT_DIR=$(cd "$SCRIPT_DIR/.." && pwd)
+
+"$SCRIPT_DIR/build_ui.sh"
+
+CONTAINER_NAME=splunk-ucc
+APP_NAME=Splunk_TA_UCCExample
+SPLUNK_PASSWORD='Chang3d!'
+
+# Remove running docker container
+docker rm -f $CONTAINER_NAME &>/dev/null
+
+cd $REPO_ROOT_DIR
+
+# Remove built package
+rm -rf output
+poetry install
+poetry run ucc-gen build --source tests/testdata/test_addons/package_global_config_everything/package
+
+chmod -R 777 output/
+
+# running on ARM Mac
+if [[ $(uname -m) == 'arm64' ]]; then
+  export DOCKER_DEFAULT_PLATFORM=linux/amd64
+fi
+
+docker run \
+  -v "$REPO_ROOT_DIR/output/$APP_NAME:/opt/splunk/etc/apps/$APP_NAME" \
+  -p 8000:8000 \
+  -p 8088:8088 \
+  -p 8089:8089 \
+  -p 9997:9997 \
+  -e "SPLUNK_START_ARGS=--accept-license" \
+  -e "SPLUNK_PASSWORD=$SPLUNK_PASSWORD" \
+  -e "SPLUNK_HEC_TOKEN=4a8a737d-5452-426c-a6f7-106dca4e813f" \
+  -e "SPLUNK_DISABLE_POPUPS=true" \
+  -d \
+  --name $CONTAINER_NAME splunk/splunk:9.1.2
+
+echo -n "Waiting Splunk for run"
+until curl -Lsk "https://localhost:8088/services/collector/health" &>/dev/null ; do echo -n "." && sleep 5 ; done
+
+# disable caching UI assets for quick reload
+curl -k -sS -u "admin:$SPLUNK_PASSWORD" https://localhost:8089/servicesNS/nobody/system/configs/conf-web/settings \
+  -d cacheEntriesLimit=0 \
+  -d cacheBytesLimit=0 \
+  > /dev/null
+
+python3 -m webbrowser "http://localhost:8000/en-GB/app/$APP_NAME"

run_splunk.sh → scripts/run_splunk.sh

@@ -1,4 +1,5 @@
-#
+#!/bin/bash
+
 # Copyright 2024 Splunk Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,9 +13,17 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-#
+
+SCRIPT_DIR=$(cd $(dirname ${BASH_SOURCE[0]}) && pwd)
+REPO_ROOT_DIR=$(cd "$SCRIPT_DIR/.." && pwd)
+
+# running on ARM Mac
+if [[ $(uname -m) == 'arm64' ]]; then
+  export DOCKER_DEFAULT_PLATFORM=linux/amd64
+fi
+
 docker run \
-  -v "$PWD/output/Splunk_TA_UCCExample:/opt/splunk/etc/apps/Splunk_TA_UCCExample" \
+  -v "$REPO_ROOT_DIR/output/Splunk_TA_UCCExample:/opt/splunk/etc/apps/Splunk_TA_UCCExample" \
   -p 8000:8000 \
   -p 8088:8088 \
   -p 8089:8089 \
@@ -24,5 +33,4 @@ docker run \
   -e "SPLUNK_HEC_TOKEN=4a8a737d-5452-426c-a6f7-106dca4e813f" \
   -e "SPLUNK_DISABLE_POPUPS=true" \
   -d \
-  --rm \
-  --name splunk splunk/splunk:${1:-latest}
+  --name splunk splunk/splunk:${1:-"9.1.2"}

tests/testdata/test_addons/package_global_config_everything/globalConfig.json

@@ -1559,9 +1559,9 @@
     "meta": {
         "name": "Splunk_TA_UCCExample",
         "restRoot": "splunk_ta_uccexample",
-        "version": "5.39.1R9d22385c",
+        "version": "5.40.0Rfd67bf22a",
         "displayName": "Splunk UCC test Add-on",
         "schemaVersion": "0.0.3",
-        "_uccVersion": "5.39.1"
+        "_uccVersion": "5.40.0"
     }
 }

ui/README.md

@@ -4,6 +4,8 @@
 
 This project includes a UI framework that dynamically renders UI components based on the provided `globalConfig.json`.
 
+For a quickstart, please check [quick_start_ui.sh](../scripts/quick_start_ui.sh)
+
 ## Getting Started
 
 1. Clone the repo.