docs: refactor readme + guidelines

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,56 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/issue-templates/forms/platform-dependent/bug-report.yml
+# See: https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
+
+name: Bug report
+description: Report a problem with the code or documentation in this repository.
+labels:
+  - "type: imperfection"
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the problem
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: To reproduce
+      description: Provide the specific set of steps we can follow to reproduce the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What would you expect to happen after following those instructions?
+    validations:
+      required: true
+  - type: input
+    id: project-version
+    attributes:
+      label: Arduino App CLI version
+      description: |
+        Which version of Arduino App CLI are you using? (output of `arduino-app-cli version` executed inside the board)
+        _This should be the most recent version available._
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any additional information here.
+    validations:
+      required: false
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Issue checklist
+      description: Please double-check that you have done each of the following things before submitting the issue.
+      options:
+        - label: I searched for previous reports in [the issue tracker](https://github.com/arduino/arduino-app-cli/issues?q=)
+          required: true
+        - label: I verified the problem still occurs when using the latest version
+          required: true
+        - label: My report contains all necessary details
+          required: true

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,51 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/issue-templates/forms/platform-dependent/bug-report.yml
+# See: https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
+
+name: Feature request
+description: Suggest an enhancement to this project.
+labels:
+  - "type: enhancement"
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the request
+    validations:
+      required: true
+  - type: textarea
+    id: current
+    attributes:
+      label: Describe the current behavior
+      description: |
+        What is the current behavior of Arduino App CLI in relation to your request?
+        How can we reproduce that behavior?
+    validations:
+      required: true
+  - type: input
+    id: project-version
+    attributes:
+      label: Arduino App CLI version
+      description: |
+        Which version of Arduino App CLI are you using? (output of `arduino-app-cli version` executed inside the board)
+        _This should be the most recent version available._
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Add any additional information here.
+    validations:
+      required: false
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Issue checklist
+      description: Please double-check that you have done each of the following things before submitting the issue.
+      options:
+        - label: I searched for previous requests in [the issue tracker](https://github.com/arduino/arduino-app-cli/issues?q=)
+          required: true
+        - label: I verified the feature was still missing when using the latest version
+          required: true
+        - label: My request contains all necessary details
+          required: true

README.md

@@ -1,64 +1,43 @@
 # Arduino App CLI
 
-`arduino-app-cli` is a command line tool and a service running on Arduino UNO Q boards, that:
+`arduino-app-cli` is a command line tool running on the [Arduino UNO Q](https://docs.arduino.cc/hardware/uno-q/) boards, that manages and runs Arduino Apps (both Linux and microcontroller parts), provides a HTTP daemon mode to expose RestFul APIs, and auto-updates itself and other components.
 
-- manages and runs Arduino Apps on the board (both Linux and microcontroller parts)
-- provides multiple APIs to perform actions and fetch data, used by the front-end (ArduinoAppsLab)
-- auto-updates itself and other components
+[![Test Go status](https://github.com/arduino/arduino-app-cli/actions/workflows/go-test.yml/badge.svg)](https://github.com/arduino/arduino-app-cli/actions/workflows/go-test.yml)
 
-## Environment Variables
+## Docs
 
-The following environment variables are used to configure `arduino-app-cli`:
+For guidance on installation and development, see the [User documentation].
 
-### Application Directories
+## Quickstart
 
-- **`ARDUINO_APP_CLI__APPS_DIR`** Path to the directory where Arduino Apps created by the user are stored.\
-  **Default:** `/home/arduino/ArduinoApps`
+// TODO
 
-- **`ARDUINO_APP_CLI__DATA_DIR`** Path to the directory where internal data is stored.\
-  **Default:** `/home/arduino/.local/share/arduino-app-cli`\
-  This folder contains:
-  - **`examples/`** default example Apps (_e.g._ `/home/arduino/.local/share/arduino-app-cli/examples`)
-  - **`assets/`** contains a subfolder for each asset version (_e.g._ `/home/arduino/.local/share/arduino-app-cli/assets/0.4.5`)
-    - Each asset folder includes:
-      - `bricks-list.yaml`
-      - `models-list.yaml`
-  - **other data** such as `properties.msgpack` containing variable values
+## How to contribute
 
-- **`ARDUINO_APP_BRICKS__CUSTOM_MODEL_DIR`** Path to the directory where custom models are stored.\
-  **Default:** `$HOME/.arduino-bricks/ei-models`\
-  (_e.g._ `/home/arduino/.arduino-bricks/ei-models`)
+Contributions are welcome!
 
----
+Please read the [Contributor Guide] document, which will show you how to build the source code, run the tests, and
+contribute your changes to the project.
 
-### Execution Settings
+:sparkles: Thanks to all our [contributors]! :sparkles:
 
-- **`ARDUINO_APP_CLI__ALLOW_ROOT`** Allow running `arduino-app-cli` as root.\
-  **Default:** `false` **Not recommended to set to true.**
+## Security
 
----
+If you think you found a vulnerability or other security-related bug in the Arduino CLI, please read our [security
+policy] and report the bug to our Security Team 🛡️ Thank you!
 
-### External Services
+e-mail contact: security@arduino.cc
 
-- **`LIBRARIES_API_URL`** URL of the external service used to search libraries.\
-  **Default:** `https://api2.arduino.cc/libraries/v1/libraries`
+## License
 
----
+Arduino App CLI is licensed under the GPL-3.0 license.
 
-### Docker Settings
+You can be released from the requirements of the above license by purchasing a commercial license. Buying such a license
+is mandatory if you want to modify or otherwise use the software for commercial activities involving the Arduino
+software without disclosing the source code of your own applications. To purchase a commercial license, send an email to
+license@arduino.cc
 
-- **`DOCKER_REGISTRY_BASE`** Docker registry used to pull images.\
-  **Default:** `ghcr.io/arduino/`
-
-- **`DOCKER_PYTHON_BASE_IMAGE`** Tag of the Docker image for the Python runner.\
-  **Default:** `app-bricks/python-apps-base:<RUNNER_VERSION>`
-
-### App folder and persistent data
-
-When running an app, persistent files will be saved in the `data` folder inside the app folder; other supporting files, including the Python venv are saved in the `.cache` folder inside the app folder.
-
-### Docker images registry
-
-Arduino Apps bricks might required a docker image, in that case the orchestrator will pull those from the registry configured with the `DOCKER_REGISTRY_BASE` environment variable. By default this points to an Arduino GitHub Container Registry (ghcr.io/arduino).
-
-The only image that needs to be referenced directly is the base Python image (`DOCKER_PYTHON_BASE_IMAGE`), all other containers can be downloaded automatically by the orchestrator depending on the bricks specified as dependencies in the app.yml file.
+[user documentation]: https://github.com/arduino/arduino-app-cli/docs/user-documentation.md
+[contributor guide]: https://arduino.github.io/arduino-app-cli/latest/CONTRIBUTING/
+[security policy]: https://github.com/arduino/arduino-app-cli/security/policy
+[contributors]: https://github.com/arduino/arduino-app-cli/graphs/contributors

Taskfile.yml

@@ -123,11 +123,17 @@ tasks:
           echo "Examples successfully cloned."
     silent: false
 
-  arduino-app-cli:build:local:
+  build:
     desc: "Build the arduino-app-cli locally"
     cmds:
       - go build -v -o ./build/arduino-app-cli ./cmd/arduino-app-cli
 
+  start:
+    desc: "build and launch the arduino-app-cli in daemon mode"
+    cmds:
+      - task build
+      - ./build/arduino-app-cli daemon  --port 8800
+
   arduino-app-cli:release:
     desc: Create a tag on the current commit and push it to the remote to create the release
     cmds:
@@ -139,12 +145,6 @@ tasks:
       - git tag -a "{{.CLI_ARGS}}" -m "Release {{.CLI_ARGS}}"
       - git push origin "{{.CLI_ARGS}}"
 
-  arduino-app-cli:start:
-    desc: "build and launch the arduino-app-cli in daemon mode"
-    cmds:
-      - task arduino-app-cli:build:local
-      - ./build/arduino-app-cli daemon  --port 6060
-
   # To to forward a port, using ssh, you can use this command:
   # ssh -L 8800:localhost:8800 arduino@<BOARD_IP>
   arduino-app-cli:pprof:

docs/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributor Guide
+
+Thanks for your interest in contributing to this project!
+
+There are several ways you can get involved:
+
+| Type of contribution                      | Contribution method                             |
+| ----------------------------------------- | ----------------------------------------------- |
+| - Support<br/>- Question<br/>- Discussion | Post on the [**Arduino Forum**][forum]          |
+| - Bug report<br/>- Feature request        | Issue report (see the guide [**here**][issues]) |
+| Testing                                   | PR review (see the guide [**here**][prs])       |
+| - Bug fix<br/>- Enhancement               | Pull request (see the guide [**here**][prs])    |
+| Monetary                                  | [Buy official products][store]                  |
+
+[forum]: https://forum.arduino.cc
+[issues]: contributor-guide/issues.md#issue-report-guide
+[beta-testing]: contributor-guide/beta-testing.md#beta-testing-guide
+[prs]: contributor-guide/pull-requests.md#pull-request-guide
+[store]: https://store.arduino.cc
+
+## Resources
+
+- [**Development Guide**](development.md#development-guide)

docs/contributor-guide/development.md

@@ -0,0 +1,51 @@
+<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/other/development.md -->
+
+# Development Guide
+
+> [!NOTE]
+> The `arduino-app-cli` is designed to run on the Board and access peripherals that are not available on a development PC (e.g., the microcontroller).
+>
+> For easier testing, using an **Arduino UNO Q** is recommended, as local testing is limited to functionalities that do not require board-specific features.
+
+## Prerequisites
+
+The following development tools must be available in your local environment:
+
+- [Go](https://go.dev/dl/)
+- [Task](https://taskfile.dev/)
+- [adb client](https://developer.android.com/tools/adb) [optionally]
+
+## Building the Project
+
+- `task init`
+- `task build`
+- `task generate:assets` to download locally the assets of the [Arduino Bricks](`https://github.com/arduino/app-bricks-py`)
+- `ARDUINO_APP_CLI__DATA_DIR=debian/arduino-app-cli/home/arduino/.local/share/arduino-app-cli task start` to build and start the arduino-app-cli in daemon mode.
+
+## Running Checks
+
+Checks and tests are set up to ensure the project content is functional and compliant with the established standards.
+
+- `task fmt-check`
+- `task lint`
+- `task test`
+
+## Installing arduino-app-cli into the board
+
+This is reccomended way to test a local development version of the arduino-app-cli into a board.
+
+1. Connect an [Arduino UNO Q](https://docs.arduino.cc/hardware/uno-q/) board via USB.
+1. `task board:install` installs the current version of Arduino App CLI on the board (`adb` is needed). The password of the `arduino` username of the board is requested.
+
+## Automatic Corrections
+
+Tools are provided to automatically bring the project into compliance with some of the required checks.
+
+- `task fmt`
+
+## Generate API docs
+
+If a PR, change the HTTP API definitions, the following steps are needed:
+
+1. Open the `cmd/gendoc/docs.go` and modify/add/remove the definitions
+1. Run `task doc` to generate the docs (i.e., the files `internal/api/docs/openapi.yaml` and `internal/e2e/client/client.gen.go` are generated)

docs/contributor-guide/issues.md

@@ -0,0 +1,33 @@
+<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/general/contributor-guide/issues.md -->
+
+# Issue Report Guide
+
+---
+
+❗ Do you need help or have a question about using this project? Support requests should be made to the [Arduino Forum](https://forum.arduino.cc).
+
+---
+
+High quality bug reports and feature requests are valuable contributions to this project. These can be made by submitting an issue report to the project's GitHub repository:
+
+https://github.com/arduino/arduino-app-cli/issues/new/choose
+
+## Before Reporting an Issue
+
+- Give the latest development version t (pre-releases) a test drive to see if your issue was already resolved:<br />
+  https://github.com/arduino/arduino-app-cli/releases?q=prerelease%3Atrue
+- Search [existing pull requests and issues](https://github.com/arduino/arduino-app-cli/issues?q=) to see if it was already reported.<br />
+  If you have additional information to provide about an existing issue, please comment there instead of creating a duplicate. You can use [GitHub's "Reactions" feature](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) if you only want to express support 👍.
+
+## Qualities of an Excellent Report
+
+- Concise and descriptive issue title.<br />
+  Vague titles make it difficult to decipher the purpose of the issue when looking through the list of reports, which might result in your issue not being given proper attention.
+- Describe the issue and what behavior you were expecting.<br />
+  Include the full and exact text of any relevant error or warning messages you might have encountered.
+- Provide a full set of steps necessary to reproduce the issue.<br />
+  Demonstration code or commands should be complete and simplified to the minimum necessary to reproduce the issue.
+- Be responsive.<br />
+  We may need you to provide additional information in order to investigate and resolve the issue.<br />
+  Make sure your GitHub account is configured so that you will receive notifications of responses to your issue report.
+- If you find a solution to your problem, please comment on your issue report with an explanation of how you were able to fix it, then close the issue.