From 5f217611fab9f297b2d8a76c7fbeaed23c4e3349 Mon Sep 17 00:00:00 2001 From: Shane Brown Date: Wed, 19 Feb 2025 14:44:15 -0700 Subject: [PATCH 1/5] Add examples configs with unit tests --- .gitignore | 3 ++- examples/README.rst | 37 +++++++++++++++++++++++++++ examples/build/basic/buildrunner.yaml | 6 +++++ examples/run/basic/buildrunner.yaml | 5 ++++ tests/test_buildrunner_files.py | 23 +++++++++++++++++ 5 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 examples/README.rst create mode 100644 examples/build/basic/buildrunner.yaml create mode 100644 examples/run/basic/buildrunner.yaml diff --git a/.gitignore b/.gitignore index 950df6c1..67502dc9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ vendor* -build +build/* dist *.egg-info *.egg @@ -13,6 +13,7 @@ dist .eggs venv* +.venv .act* buildrunner/version.py diff --git a/examples/README.rst b/examples/README.rst new file mode 100644 index 00000000..54404cbc --- /dev/null +++ b/examples/README.rst @@ -0,0 +1,37 @@ +================================== +Buildrunner Example Configurations +================================== + +This directory contains several example configuration files for Buildrunner. + +Running Buildrunner with Example Configuration Files +"""""""""""""""""""""""""""""""""""""""""""""""""""" + +To run Buildrunner using the example configuration files, execute the following commands from +the top-level directory within the Buildrunner repository. + + +1. **Install Buildrunner:** + + .. code-block:: sh + + pip install . + +2. **Run Buildrunner:** + + .. code-block:: sh + + ./bin/buildrunner -f examples/ + + For example: + + .. code-block:: sh + + ./bin/buildrunner -f examples/configs/build/basic/buildrunner.yaml + +Adding New Example Configuration Files +"""""""""""""""""""""""""""""""""""""" +To add a new example configuration file, add a new file under the `examples/` directory. The new file should end with ``buildrunner.yaml`` to ensure that +the unit tests can automatically detect and run the new example configuration file. The new file should contain a valid Buildrunner configuration and should be able +to run successfully using the instructions provided above with no other manual setup. If needed, add a README.rst file to the same directory as the configuration file +to provide additional information. Any additional files needed by the configuration should be colocated with the configuration file. \ No newline at end of file diff --git a/examples/build/basic/buildrunner.yaml b/examples/build/basic/buildrunner.yaml new file mode 100644 index 00000000..f1db9802 --- /dev/null +++ b/examples/build/basic/buildrunner.yaml @@ -0,0 +1,6 @@ +steps: + simple-build-step: + build: + dockerfile: | + FROM busybox:latest + RUN echo Hello World diff --git a/examples/run/basic/buildrunner.yaml b/examples/run/basic/buildrunner.yaml new file mode 100644 index 00000000..56b8c32b --- /dev/null +++ b/examples/run/basic/buildrunner.yaml @@ -0,0 +1,5 @@ +steps: + simple-run-step: + run: + image: busybox:latest + cmd: echo Hello World \ No newline at end of file diff --git a/tests/test_buildrunner_files.py b/tests/test_buildrunner_files.py index 1f028ce4..69965393 100644 --- a/tests/test_buildrunner_files.py +++ b/tests/test_buildrunner_files.py @@ -117,6 +117,21 @@ def _get_test_runs( ] +def _get_example_runs(test_dir: str) -> List[Tuple[str, str, Optional[List[str]], int]]: + file_names = [] + # Walk through the examples directory and find all files ending with buildrunner.yaml + for root, _, files in os.walk(test_dir): + for file in files: + file_name = os.path.join(root, file) + if file_name.endswith("buildrunner.yaml"): + file_names.append(file_name) + + return [ + (test_dir, file_name, _get_test_args(file_name), _get_exit_code(file_name)) + for file_name in file_names + ] + + def _test_buildrunner_file(test_dir, file_name, args, exit_code): print(f"\n>>>> Testing Buildrunner file: {file_name}") with tempfile.TemporaryDirectory(prefix="buildrunner.results-") as temp_dir: @@ -194,3 +209,11 @@ def test_buildrunner_arm_dir(test_dir: str, file_name, args, exit_code): def test_buildrunner_scan_dir(test_dir: str, file_name, args, exit_code): # The scan tests can be flaky, with errors like "TOOMANYREQUESTS: retry-after: 804.543µs, allowed: 44000/minute" _test_buildrunner_file(test_dir, file_name, args, exit_code) + + +@pytest.mark.parametrize( + "test_dir, file_name, args, exit_code", + _get_example_runs(test_dir=f"{TEST_DIR}/../examples"), +) +def test_example_configs(test_dir: str, file_name, args, exit_code): + _test_buildrunner_file(test_dir, file_name, args, exit_code) From 0bae85d1a433220304ba1abf0abae7809112ca0d Mon Sep 17 00:00:00 2001 From: Shane Brown Date: Thu, 20 Feb 2025 15:37:43 -0700 Subject: [PATCH 2/5] Add better documentation for examples --- examples/README.rst | 40 ++++++++++++++++++--------- examples/build/basic/buildrunner.yaml | 1 + examples/run/basic/buildrunner.yaml | 1 + 3 files changed, 29 insertions(+), 13 deletions(-) diff --git a/examples/README.rst b/examples/README.rst index 54404cbc..9502218c 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -2,26 +2,28 @@ Buildrunner Example Configurations ================================== -This directory contains several example configuration files for Buildrunner. +This directory contains example configuration files for Buildrunner, demonstrating various use cases and best practices. These examples serve as references for users looking to configure and execute Buildrunner effectively. Running Buildrunner with Example Configuration Files -"""""""""""""""""""""""""""""""""""""""""""""""""""" +==================================================== -To run Buildrunner using the example configuration files, execute the following commands from -the top-level directory within the Buildrunner repository. +To run Buildrunner using an example configuration file, follow these steps from the root directory of the Buildrunner repository: +1. **Navigate to the Buildrunner repository directory.** -1. **Install Buildrunner:** +2. **Install Buildrunner (Recommended: Use a Virtual Environment)** + + It is recommended to install Buildrunner within a virtual environment to avoid conflicts with system-wide dependencies. .. code-block:: sh pip install . -2. **Run Buildrunner:** +3. **Execute Buildrunner with a specified configuration file:** .. code-block:: sh - ./bin/buildrunner -f examples/ + ./bin/buildrunner -f examples/ For example: @@ -29,9 +31,21 @@ the top-level directory within the Buildrunner repository. ./bin/buildrunner -f examples/configs/build/basic/buildrunner.yaml -Adding New Example Configuration Files -"""""""""""""""""""""""""""""""""""""" -To add a new example configuration file, add a new file under the `examples/` directory. The new file should end with ``buildrunner.yaml`` to ensure that -the unit tests can automatically detect and run the new example configuration file. The new file should contain a valid Buildrunner configuration and should be able -to run successfully using the instructions provided above with no other manual setup. If needed, add a README.rst file to the same directory as the configuration file -to provide additional information. Any additional files needed by the configuration should be colocated with the configuration file. \ No newline at end of file +Adding a New Example Configuration File +======================================= + +To contribute a new example configuration file, adhere to the following guidelines: + +1. **File Location & Naming** + - Place the new file in the ``examples/`` directory. + - Ensure the filename ends with ``.buildrunner.yaml`` to allow automatic detection and execution by unit tests. + +2. **Configuration Validity** + - The configuration file must contain a valid Buildrunner configuration. + - It should execute successfully using the standard instructions provided in this repository without requiring any manual intervention. + +3. **Documentation & Additional Files** + - If necessary, include a ``README.rst`` file in the same directory as the configuration file to provide additional details or instructions. + - Any supporting files required for the configuration should be placed alongside the configuration file. + +Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users. diff --git a/examples/build/basic/buildrunner.yaml b/examples/build/basic/buildrunner.yaml index f1db9802..dcaff78f 100644 --- a/examples/build/basic/buildrunner.yaml +++ b/examples/build/basic/buildrunner.yaml @@ -1,3 +1,4 @@ +# Basic buildrunner configuration to build a simple Docker image. steps: simple-build-step: build: diff --git a/examples/run/basic/buildrunner.yaml b/examples/run/basic/buildrunner.yaml index 56b8c32b..5c06aae4 100644 --- a/examples/run/basic/buildrunner.yaml +++ b/examples/run/basic/buildrunner.yaml @@ -1,3 +1,4 @@ +# Basic buildrunner configuration to run a simple Docker image. steps: simple-run-step: run: From fbb01bf69613d3e54323ef2f13b764e2742fdaf8 Mon Sep 17 00:00:00 2001 From: Shane Brown Date: Fri, 21 Feb 2025 12:52:19 -0700 Subject: [PATCH 3/5] Update README files --- README.rst | 5 +++++ examples/README.rst | 19 +++++++++---------- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/README.rst b/README.rst index 90647873..f133b96a 100755 --- a/README.rst +++ b/README.rst @@ -1128,6 +1128,11 @@ Common Issues See `docs/common-issues `_. +Example Configurations +====================== + +See `examples `_. + Contributing ============ diff --git a/examples/README.rst b/examples/README.rst index 9502218c..c2c86f6f 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -11,23 +11,22 @@ To run Buildrunner using an example configuration file, follow these steps from 1. **Navigate to the Buildrunner repository directory.** -2. **Install Buildrunner (Recommended: Use a Virtual Environment)** +2. **Install Buildrunner:** + .. code-block:: sh - It is recommended to install Buildrunner within a virtual environment to avoid conflicts with system-wide dependencies. + pip install . - .. code-block:: sh + *Tip: It is recommended to install Buildrunner within a virtual environment to avoid conflicts with system-wide dependencies.* - pip install . 3. **Execute Buildrunner with a specified configuration file:** + .. code-block:: sh - .. code-block:: sh - - ./bin/buildrunner -f examples/ + ./bin/buildrunner -f examples/ - For example: + *Example:* - .. code-block:: sh + .. code-block:: sh ./bin/buildrunner -f examples/configs/build/basic/buildrunner.yaml @@ -48,4 +47,4 @@ To contribute a new example configuration file, adhere to the following guidelin - If necessary, include a ``README.rst`` file in the same directory as the configuration file to provide additional details or instructions. - Any supporting files required for the configuration should be placed alongside the configuration file. -Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users. +Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users. \ No newline at end of file From dd35ec51180c7799d1ebb04f53890ccedf2acf1a Mon Sep 17 00:00:00 2001 From: Shane Brown Date: Fri, 21 Feb 2025 14:20:59 -0700 Subject: [PATCH 4/5] Update example readme with how to run buildrunner --- examples/README.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/examples/README.rst b/examples/README.rst index c2c86f6f..b9129a0b 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -23,12 +23,14 @@ To run Buildrunner using an example configuration file, follow these steps from .. code-block:: sh ./bin/buildrunner -f examples/ + or + buildrunner -f examples/ *Example:* .. code-block:: sh - ./bin/buildrunner -f examples/configs/build/basic/buildrunner.yaml + buildrunner -f examples/configs/build/basic/buildrunner.yaml Adding a New Example Configuration File ======================================= From 0dcc360a418b9471523e9c07d413b64c7cc9d2d2 Mon Sep 17 00:00:00 2001 From: Shane Brown Date: Fri, 21 Feb 2025 14:53:57 -0700 Subject: [PATCH 5/5] Simplify running example configs instructions --- examples/README.rst | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/examples/README.rst b/examples/README.rst index b9129a0b..ae93b32e 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -11,26 +11,16 @@ To run Buildrunner using an example configuration file, follow these steps from 1. **Navigate to the Buildrunner repository directory.** -2. **Install Buildrunner:** +2. **Execute Buildrunner with a specified configuration file:** .. code-block:: sh - pip install . - - *Tip: It is recommended to install Buildrunner within a virtual environment to avoid conflicts with system-wide dependencies.* - - -3. **Execute Buildrunner with a specified configuration file:** - .. code-block:: sh - - ./bin/buildrunner -f examples/ - or - buildrunner -f examples/ + PYTHONPATH=. ./bin/buildrunner -f examples/ *Example:* .. code-block:: sh - buildrunner -f examples/configs/build/basic/buildrunner.yaml + PYTHONPATH=. ./bin/buildrunner -f examples/build/basic/buildrunner.yaml Adding a New Example Configuration File =======================================