From ea9086ea6d0e20f821561f9485fb02a840ad1ad8 Mon Sep 17 00:00:00 2001 From: Daniel Falk Date: Wed, 6 Aug 2025 09:48:18 +0200 Subject: [PATCH 1/2] Add more instructions to coderabbit --- .coderabbit.yaml | 45 ++++++++++++- .github/workflows/prettier.yml | 2 +- .project_readme_template.md | 118 +++++++++++++++++++++++++++++++++ 3 files changed, 163 insertions(+), 2 deletions(-) create mode 100644 .project_readme_template.md diff --git a/.coderabbit.yaml b/.coderabbit.yaml index e134121..2b14266 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -14,6 +14,38 @@ reviews: dashboard usability, and proper licensing compliance. We should make sure that dashboards are portable and does not check in specific host names, or refer to other specific data from a single deployment. + - path: "project-*/**" + instructions: >- + Each example project for the FixedIT Data Agent should be self-contained and + designed as a standalone example / tutorial showing how to use the FixedIT Data Agent. + The project should be well documented and include all the necessary files to run the example. + A reader should be able to understand the background and the purpose of the project, and be able to + understand the implementation details and how to use it. If the project includes a + dashboard, it should be placed in a new folder in the repo-root/dashboard-deployments/ + directory instead of being included in the project folder. In the README for the project, + the first time the FixedIT Data Agent is mentioned, we should link to the product page: + https://fixedit.ai/products-data-agent/ + Emphasize that these solutions are accessible to system integrators and IT professionals + without requiring complex C/C++ ACAP development. Highlight that custom edge intelligence can be + implemented using familiar IT tools (configuration files, shell scripts, REST APIs) rather than + traditional embedded programming approaches. Note that bash does not exist on the Axis devices, + so .sh scripts should be written in portable shell syntax. + + **README Structure**: All project README files should follow the standardized template at + `.project_readme_template.md`. This template ensures consistent documentation that serves + both audiences: (1) IT professionals who want plug-and-play solutions, and (2) developers + who want to customize and extend the examples. The template enforces a logical structure: + 1) Introduction and background (project purpose, how it works, why choose this approach) + 2) Technical explanation and quick start guide (compatibility, setup, troubleshooting) + 3) Developer-oriented notes (local testing, implementation details) + + **Key Template Requirements**: + - Include compatibility sections for both AXIS OS and FixedIT Data Agent versions + - Explain host testing and its limitations and why certain parts require actual Axis devices + - Provide clear troubleshooting guidance right after the quick setup + - Use visual diagrams (mermaid) to explain system flows + - Emphasize "no C/C++ development required" value proposition + - Include comprehensive table of contents with proper anchor links - path: "**/*.md" instructions: >- Documentation files should clearly communicate the dual audience: (1) server-side @@ -31,7 +63,18 @@ reviews: developers (edge customization focus). If new features are added or existing ones changed significantly, ensure documentation clearly explains the intended audience and usage level. We use prettier for formatting of common file formats like markdown, - yaml, json, etc. + yaml, json, etc. Example projects should be placed in the repo-root in a directory named + project-*/. Whenever referencing Axis device model names like "D4100-VE mk II" or "M3045", + prefix it with "AXIS" in capital letters (e.g. "AXIS D4100-VE mk II"). When using Axis + as a company name, use "Axis Communications", note that all-caps is only used when "AXIS" is + used in their product names, not their company name. When using the name of an Axis product, + google on the name to verify that it is correctly identified. Avoid using 'cameras' or + 'Axis cameras' unless the solution in related to visual analytics, otherwise prefer using + 'Axis devices' to show that the FixedIT Data Agent also works with strobes, speakers, + door stations, etc. + Images used for the README should be placed in a directory called .images/ in the affected + project folder. These images might also be refered to from other sources like the top-level + README.md file. auto_review: enabled: true auto_incremental_review: true diff --git a/.github/workflows/prettier.yml b/.github/workflows/prettier.yml index 2335269..3ae2ca1 100644 --- a/.github/workflows/prettier.yml +++ b/.github/workflows/prettier.yml @@ -14,7 +14,7 @@ jobs: env: # List of files patterns that should be formatted by prettier. This should normally include: # workflow files (yml) and any other json/yml/markdown files, including hidden config files for tools. - PRETTIER_FILES: '"**/*.{json,yml,yaml,md}" ".github/**/*.{json,yml,yaml,md}" ".*.{yml,yaml}"' + PRETTIER_FILES: '"**/*.{json,yml,yaml,md}" ".github/**/*.{json,yml,yaml,md}" ".*.{yml,yaml,json,md}"' # Pin Prettier version to ensure deterministic CI runs and avoid unpredictable failures PRETTIER_VERSION: "3.6.0" diff --git a/.project_readme_template.md b/.project_readme_template.md new file mode 100644 index 0000000..52d01c1 --- /dev/null +++ b/.project_readme_template.md @@ -0,0 +1,118 @@ +# [Project Name] + +[Brief description - at least 3-4 sentences about what this project demonstrates and its practical use case] + +## How It Works + +[Brief explanation of the system flow with a simple mermaid diagram] + +```mermaid +flowchart TD + A["📥 Input Source
Collect data"] --> B["🔄 Process
Transform data"] + B --> C["�� Output Target
Send/control device"] + C --> D["⏳ Wait
Sleep for interval"] + D --> A + + style A fill:#e1f5fe + style B fill:#f3e5f5 + style C fill:#e8f5e8 + style D fill:#f1f8e9 +``` + +## Why Choose This Approach? + +**No C/C++ development required!** Explain why this project makes sense to implement with the FixedIT Data Agent instead of creating an ACAP from scratch. + +## Table of Contents + +- [Project Name](#project-name) +- [How It Works](#how-it-works) +- [Why Choose This Approach?](#why-choose-this-approach) +- [Compatibility](#compatibility) + - [AXIS OS Compatibility](#axis-os-compatibility) + - [FixedIT Data Agent Compatibility](#fixedit-data-agent-compatibility) +- [Quick Setup](#quick-setup) +- [Troubleshooting](#troubleshooting) +- [Files](#files) +- [Configuration Details](#configuration-details) +- [Local Testing on Host](#local-testing-on-host) + - [Prerequisites](#prerequisites) + - [Host Testing Limitations](#host-testing-limitations) + - [Test Commands](#test-commands) + +## Compatibility + +### AXIS OS Compatibility + +- **Minimum AXIS OS version**: [X.X] or later +- **Required tools**: [List any special commands like `jq`, etc. that does not exist in all AXIS OS versions] +- **Other notes**: [Specify if requires basic/digest auth, HTTPS support, etc.] + +### FixedIT Data Agent Compatibility + +- **Minimum Data Agent version**: [X.X] +- **Required features**: [Any specific agent features needed] + +## Quick Setup + +1. **Configure FixedIT Data Agent variables:** + + Configure the parameters `X` and `Y`. Set the custom environment variables in the `Extra env` parameter as a semicolon-separated list of key-value pairs: + + ```txt + VARIABLE_1=value1;VARIABLE_2=value2;VARIABLE_3=value3 + ``` + +2. **Upload the files to the FixedIT Data Agent** + +3. **Enable the configuration files** + +[Explain what should happen next] + +### Troubleshooting + +Enable the `Debug` option in the FixedIT Data Agent for detailed logs. [If applicable, debug files will appear in the `Uploaded helper files` section (refresh page to see updates).] + +**Note**: Don't leave debug enabled long-term as it creates large log files. + +## Files + +- `config_*.conf` - [Brief description of each config file's purpose] +- `*.sh` - [Brief description of shell scripts] + +## Configuration Details + +[Technical details about how the system works, environment variables, data formats, etc.] + +## Local Testing on Host + +You can test this project locally using Telegraf before deploying to your Axis device. + +### Prerequisites + +- Install Telegraf on your development machine +- [Any other local requirements] + +### Host Testing Limitations + +[Explain which parts work on host vs. require actual Axis device, and why] + +### Test Commands + +First, set up the environment variables: + +```bash +# Set up environment +export VARIABLE_1="test_value" +export HELPER_FILES_DIR="$(pwd)" +``` + +Then run the test: + +```bash +# Test configuration +telegraf --config config_*.conf --test + +# Run once +telegraf --config config_*.conf --once +``` From 5ba97a60a77da1f18729a7a7d40ca262db4ec3a6 Mon Sep 17 00:00:00 2001 From: Daniel Falk Date: Thu, 7 Aug 2025 13:47:40 +0200 Subject: [PATCH 2/2] Review fixes --- .coderabbit.yaml | 54 ++++++++++++++++++++++++------------- .project_readme_template.md | 8 +++--- 2 files changed, 40 insertions(+), 22 deletions(-) diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 2b14266..edd3fea 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -6,11 +6,11 @@ reviews: path_instructions: - path: "dashboard-deployments/**" instructions: >- - This directory contains server-side dashboard examples for visualizing data from - FixedIT Data Agent running on Axis devices. These are primarily for DevOps/IT - professionals comfortable with deploying Grafana dashboards and InfluxDB servers. - Some dashboards work directly with bundled agent configurations, others can be - customized. Licensed under Elastic License 2.0. Review for deployment complexity, + This directory contains server-side dashboard examples for visualizing data from + FixedIT Data Agent running on Axis devices. These are primarily for DevOps/IT + professionals comfortable with deploying Grafana dashboards and InfluxDB servers. + Some dashboards work directly with bundled agent configurations, others can be + customized. Licensed under Elastic License 2.0. Review for deployment complexity, dashboard usability, and proper licensing compliance. We should make sure that dashboards are portable and does not check in specific host names, or refer to other specific data from a single deployment. @@ -31,37 +31,55 @@ reviews: traditional embedded programming approaches. Note that bash does not exist on the Axis devices, so .sh scripts should be written in portable shell syntax. - **README Structure**: All project README files should follow the standardized template at - `.project_readme_template.md`. This template ensures consistent documentation that serves - both audiences: (1) IT professionals who want plug-and-play solutions, and (2) developers + **README Structure**: All project README files should follow the standardized template at + `.project_readme_template.md`. This template ensures consistent documentation that serves + both audiences: (1) IT professionals who want plug-and-play solutions, and (2) developers who want to customize and extend the examples. The template enforces a logical structure: 1) Introduction and background (project purpose, how it works, why choose this approach) 2) Technical explanation and quick start guide (compatibility, setup, troubleshooting) 3) Developer-oriented notes (local testing, implementation details) - **Key Template Requirements**: + **Key README Requirements**: - Include compatibility sections for both AXIS OS and FixedIT Data Agent versions - Explain host testing and its limitations and why certain parts require actual Axis devices - Provide clear troubleshooting guidance right after the quick setup - Use visual diagrams (mermaid) to explain system flows - Emphasize "no C/C++ development required" value proposition - Include comprehensive table of contents with proper anchor links + - Template values for environment variables should use format like `VAPIX_PASS="your_vapix_password"` + - In bash commands, use format like `--bucket ` for template values + - When using credentials, specify minimum required privileges (e.g., viewer/operator/admin) and + encourage not using higher than needed + - Always correctly capitalize "FixedIT Data Agent" in all documentation and always include "FixedIT" + + **Project Structure Requirements**: + - Test scripts for testing functionality or visualizing data should be placed in a + `test_scripts/` folder + - Configuration files used by default should be placed in the root of the project directory + - Optional files used for testing purposes (like mocked versions) can go in `test_files/` + - Each project should contain a license file with the appropriate license for that project + - If a project contains Python files, it should have a `requirements.txt` file with pinned + versions of the latest packages + - Python helper scripts should use `click` for argument parsing and have good help texts + - Use `pathlib` instead of `os.path` for platform portability in Python + - If the project contains Python files, ensure there's a GitHub Actions workflow called + `project--python-quality.yml` - path: "**/*.md" instructions: >- - Documentation files should clearly communicate the dual audience: (1) server-side - dashboard users who want to keep agent with bundled configs, and (2) edge device - developers who want to customize agent behavior. Ensure examples and instructions + Documentation files should clearly communicate the dual audience: (1) server-side + dashboard users who want to keep agent with bundled configs, and (2) edge device + developers who want to customize agent behavior. Ensure examples and instructions are appropriate for the intended skill level and use case. Since this is a public repository, we should not include any sensitive information, the instructions should be easily understandable for a wide audience, and we should avoid using any jargon or technical terms that are not commonly used. - path: "**/*" instructions: >- - This repository serves FixedIT Data Agent users across a spectrum from plug-and-play - dashboard deployment to advanced edge device customization. Consider whether changes - maintain accessibility for both DevOps professionals (server-side focus) and - developers (edge customization focus). If new features are added or existing ones - changed significantly, ensure documentation clearly explains the intended audience + This repository serves FixedIT Data Agent users across a spectrum from plug-and-play + dashboard deployment to advanced edge device customization. Consider whether changes + maintain accessibility for both DevOps professionals (server-side focus) and + developers (edge customization focus). If new features are added or existing ones + changed significantly, ensure documentation clearly explains the intended audience and usage level. We use prettier for formatting of common file formats like markdown, yaml, json, etc. Example projects should be placed in the repo-root in a directory named project-*/. Whenever referencing Axis device model names like "D4100-VE mk II" or "M3045", @@ -73,7 +91,7 @@ reviews: 'Axis devices' to show that the FixedIT Data Agent also works with strobes, speakers, door stations, etc. Images used for the README should be placed in a directory called .images/ in the affected - project folder. These images might also be refered to from other sources like the top-level + project folder. These images might also be referred to from other sources like the top-level README.md file. auto_review: enabled: true diff --git a/.project_readme_template.md b/.project_readme_template.md index 52d01c1..9b43668 100644 --- a/.project_readme_template.md +++ b/.project_readme_template.md @@ -9,7 +9,7 @@ ```mermaid flowchart TD A["📥 Input Source
Collect data"] --> B["🔄 Process
Transform data"] - B --> C["�� Output Target
Send/control device"] + B --> C["📤 Output Target
Send/control device"] C --> D["⏳ Wait
Sleep for interval"] D --> A @@ -21,7 +21,7 @@ flowchart TD ## Why Choose This Approach? -**No C/C++ development required!** Explain why this project makes sense to implement with the FixedIT Data Agent instead of creating an ACAP from scratch. +**No C/C++ development required!** Explain why this project makes sense to implement with the [FixedIT Data Agent](https://fixedit.ai/products-data-agent/) instead of creating an ACAP from scratch. ## Table of Contents @@ -45,8 +45,8 @@ flowchart TD ### AXIS OS Compatibility - **Minimum AXIS OS version**: [X.X] or later -- **Required tools**: [List any special commands like `jq`, etc. that does not exist in all AXIS OS versions] -- **Other notes**: [Specify if requires basic/digest auth, HTTPS support, etc.] +- **Required tools**: [List any special commands like `jq`, etc. that do not exist in all AXIS OS versions] +- **Other notes**: [Specify if it requires basic/digest auth, HTTPS support, etc.] ### FixedIT Data Agent Compatibility