Skip to content

Commit 537694f

Browse files
dido18per1234lucarin91
authored
docs: refactor readme + guidelines (#58)
* docs: update README and add user documentation * docs: enhance contribution guidelines in README * docs: tidy up README and user documentation formatting * docs: enhance contributor guide with detailed contribution methods and resources * docs: update development guide with additional instructions and resources * Update docs/contributor-guide/development.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update docs/contributor-guide/development.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update docs/contributor-guide/development.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update docs/contributor-guide/development.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update docs/contributor-guide/issues.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update docs/contributor-guide/issues.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update docs/user-documentation.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update README.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update README.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update README.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update README.md Co-authored-by: Per Tillisch <accounts@perglass.com> * docs: clarify terminology in Docker images registry section of user documentation * docs: simplify description of arduino-app-cli in README.md * docs: update contributor guide for clarity and accuracy * docs: update development guide and issue report instructions for clarity * docs: restructure environment variables section for clarity and organization * docs: improve clarity and consistency in user documentation * docs: add bug report and feature request issue templates for better user feedback * docs: improve formatting and clarity in environment variables section * docs: update contribution methods for testing section in CONTRIBUTING.md * docs: fix formatting in contribution methods table for consistency * docs: clarify description of temporary files in user documentation * fix: correct contributors link in README.md * feat: enhance issue templates by adding additional context field and clarifying version prompts * Update docs/contributor-guide/development.md Co-authored-by: Luca Rinaldi <l.rinaldi@arduino.cc> * Update docs/contributor-guide/development.md Co-authored-by: Luca Rinaldi <l.rinaldi@arduino.cc> * docs: update development guide for clarity and completeness * docs: improve clarity in development guide by restructuring build instructions * Update docs/contributor-guide/development.md Co-authored-by: Per Tillisch <accounts@perglass.com> * docs: update development guide for clarity and accuracy in build instructions * revmoe task0 g * docs: clarify building instructions and fix command syntax in development guide * Update docs/user-documentation.md Co-authored-by: Per Tillisch <accounts@perglass.com> * Update docs/user-documentation.md Co-authored-by: Per Tillisch <accounts@perglass.com> * docs: improve clarity and correctness in development guide * docs: update links to user documentation and contributor guide for consistency * docs: add a blank line for better readability in the development guide * docs: update link to the Development Guide in the Contributor Guide * Update docs/contributor-guide/development.md Co-authored-by: Per Tillisch <accounts@perglass.com> --------- Co-authored-by: Per Tillisch <accounts@perglass.com> Co-authored-by: Luca Rinaldi <l.rinaldi@arduino.cc>
1 parent ec13ed1 commit 537694f

File tree

10 files changed

+526
-53
lines changed

10 files changed

+526
-53
lines changed

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/issue-templates/forms/platform-dependent/bug-report.yml
2+
# See: https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
3+
4+
name: Bug report
5+
description: Report a problem with the code or documentation in this repository.
6+
labels:
7+
- "type: imperfection"
8+
body:
9+
- type: textarea
10+
id: description
11+
attributes:
12+
label: Describe the problem
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: reproduce
17+
attributes:
18+
label: To reproduce
19+
description: Provide the specific set of steps we can follow to reproduce the problem.
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: expected
24+
attributes:
25+
label: Expected behavior
26+
description: What would you expect to happen after following those instructions?
27+
validations:
28+
required: true
29+
- type: input
30+
id: project-version
31+
attributes:
32+
label: Arduino App CLI version
33+
description: |
34+
Which version of Arduino App CLI are you using? (output of `arduino-app-cli version` executed inside the board)
35+
_This should be the most recent version available._
36+
validations:
37+
required: true
38+
- type: textarea
39+
id: additional
40+
attributes:
41+
label: Additional context
42+
description: Add any additional information here.
43+
validations:
44+
required: false
45+
- type: checkboxes
46+
id: checklist
47+
attributes:
48+
label: Issue checklist
49+
description: Please double-check that you have done each of the following things before submitting the issue.
50+
options:
51+
- label: I searched for previous reports in [the issue tracker](https://github.com/arduino/arduino-app-cli/issues?q=)
52+
required: true
53+
- label: I verified the problem still occurs when using the latest version
54+
required: true
55+
- label: My report contains all necessary details
56+
required: true

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Source: https://github.com/arduino/tooling-project-assets/blob/main/issue-templates/forms/platform-dependent/bug-report.yml
2+
# See: https://docs.github.com/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
3+
4+
name: Feature request
5+
description: Suggest an enhancement to this project.
6+
labels:
7+
- "type: enhancement"
8+
body:
9+
- type: textarea
10+
id: description
11+
attributes:
12+
label: Describe the request
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: current
17+
attributes:
18+
label: Describe the current behavior
19+
description: |
20+
What is the current behavior of Arduino App CLI in relation to your request?
21+
How can we reproduce that behavior?
22+
validations:
23+
required: true
24+
- type: input
25+
id: project-version
26+
attributes:
27+
label: Arduino App CLI version
28+
description: |
29+
Which version of Arduino App CLI are you using? (output of `arduino-app-cli version` executed inside the board)
30+
_This should be the most recent version available._
31+
validations:
32+
required: true
33+
- type: textarea
34+
id: additional
35+
attributes:
36+
label: Additional context
37+
description: Add any additional information here.
38+
validations:
39+
required: false
40+
- type: checkboxes
41+
id: checklist
42+
attributes:
43+
label: Issue checklist
44+
description: Please double-check that you have done each of the following things before submitting the issue.
45+
options:
46+
- label: I searched for previous requests in [the issue tracker](https://github.com/arduino/arduino-app-cli/issues?q=)
47+
required: true
48+
- label: I verified the feature was still missing when using the latest version
49+
required: true
50+
- label: My request contains all necessary details
51+
required: true

‎README.md‎

Lines changed: 25 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,43 @@
11
# Arduino App CLI
22

3-
`arduino-app-cli` is a command line tool and a service running on Arduino UNO Q boards, that:
3+
`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.
44

5-
- manages and runs Arduino Apps on the board (both Linux and microcontroller parts)
6-
- provides multiple APIs to perform actions and fetch data, used by the front-end (ArduinoAppsLab)
7-
- auto-updates itself and other components
5+
[![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)
86

9-
## Environment Variables
7+
## Docs
108

11-
The following environment variables are used to configure `arduino-app-cli`:
9+
For guidance on installation and development, see the [User documentation].
1210

13-
### Application Directories
11+
## Quickstart
1412

15-
- **`ARDUINO_APP_CLI__APPS_DIR`** Path to the directory where Arduino Apps created by the user are stored.\
16-
**Default:** `/home/arduino/ArduinoApps`
13+
// TODO
1714

18-
- **`ARDUINO_APP_CLI__DATA_DIR`** Path to the directory where internal data is stored.\
19-
**Default:** `/home/arduino/.local/share/arduino-app-cli`\
20-
This folder contains:
21-
- **`examples/`** default example Apps (_e.g._ `/home/arduino/.local/share/arduino-app-cli/examples`)
22-
- **`assets/`** contains a subfolder for each asset version (_e.g._ `/home/arduino/.local/share/arduino-app-cli/assets/0.4.5`)
23-
- Each asset folder includes:
24-
- `bricks-list.yaml`
25-
- `models-list.yaml`
26-
- **other data** such as `properties.msgpack` containing variable values
15+
## How to contribute
2716

28-
- **`ARDUINO_APP_BRICKS__CUSTOM_MODEL_DIR`** Path to the directory where custom models are stored.\
29-
**Default:** `$HOME/.arduino-bricks/ei-models`\
30-
(_e.g._ `/home/arduino/.arduino-bricks/ei-models`)
17+
Contributions are welcome!
3118

32-
---
19+
Please read the [Contributor Guide] document, which will show you how to build the source code, run the tests, and
20+
contribute your changes to the project.
3321

34-
### Execution Settings
22+
:sparkles: Thanks to all our [contributors]! :sparkles:
3523

36-
- **`ARDUINO_APP_CLI__ALLOW_ROOT`** Allow running `arduino-app-cli` as root.\
37-
**Default:** `false` **Not recommended to set to true.**
24+
## Security
3825

39-
---
26+
If you think you found a vulnerability or other security-related bug in the Arduino CLI, please read our [security
27+
policy] and report the bug to our Security Team 🛡️ Thank you!
4028

41-
### External Services
29+
e-mail contact: security@arduino.cc
4230

43-
- **`LIBRARIES_API_URL`** URL of the external service used to search libraries.\
44-
**Default:** `https://api2.arduino.cc/libraries/v1/libraries`
31+
## License
4532

46-
---
33+
Arduino App CLI is licensed under the GPL-3.0 license.
4734

48-
### Docker Settings
35+
You can be released from the requirements of the above license by purchasing a commercial license. Buying such a license
36+
is mandatory if you want to modify or otherwise use the software for commercial activities involving the Arduino
37+
software without disclosing the source code of your own applications. To purchase a commercial license, send an email to
38+
license@arduino.cc
4939

50-
- **`DOCKER_REGISTRY_BASE`** Docker registry used to pull images.\
51-
**Default:** `ghcr.io/arduino/`
52-
53-
- **`DOCKER_PYTHON_BASE_IMAGE`** Tag of the Docker image for the Python runner.\
54-
**Default:** `app-bricks/python-apps-base:<RUNNER_VERSION>`
55-
56-
### App folder and persistent data
57-
58-
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.
59-
60-
### Docker images registry
61-
62-
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).
63-
64-
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.
40+
[user documentation]: docs/user-documentation.md
41+
[contributor guide]: docs/CONTRIBUTING.md
42+
[security policy]: https://github.com/arduino/arduino-app-cli/security/policy
43+
[contributors]: https://github.com/arduino/arduino-app-cli/graphs/contributors

‎Taskfile.yml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -128,11 +128,17 @@ tasks:
128128
echo "Examples successfully cloned."
129129
silent: false
130130

131-
arduino-app-cli:build:local:
131+
build:
132132
desc: "Build the arduino-app-cli locally"
133133
cmds:
134134
- go build -v -o ./build/arduino-app-cli ./cmd/arduino-app-cli
135135

136+
start:
137+
desc: "build and launch the arduino-app-cli in daemon mode"
138+
cmds:
139+
- task build
140+
- ./build/arduino-app-cli daemon --port 8800
141+
136142
arduino-app-cli:release:
137143
desc: Create a tag on the current commit and push it to the remote to create the release
138144
cmds:
@@ -144,12 +150,6 @@ tasks:
144150
- git tag -a "{{.CLI_ARGS}}" -m "Release {{.CLI_ARGS}}"
145151
- git push origin "{{.CLI_ARGS}}"
146152

147-
arduino-app-cli:start:
148-
desc: "build and launch the arduino-app-cli in daemon mode"
149-
cmds:
150-
- task arduino-app-cli:build:local
151-
- ./build/arduino-app-cli daemon --port 6060
152-
153153
# To to forward a port, using ssh, you can use this command:
154154
# ssh -L 8800:localhost:8800 arduino@<BOARD_IP>
155155
arduino-app-cli:pprof:

‎docs/CONTRIBUTING.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Contributor Guide
2+
3+
Thanks for your interest in contributing to this project!
4+
5+
There are several ways you can get involved:
6+
7+
| Type of contribution | Contribution method |
8+
| ----------------------------------------- | ----------------------------------------------- |
9+
| - Support<br/>- Question<br/>- Discussion | Post on the [**Arduino Forum**][forum] |
10+
| - Bug report<br/>- Feature request | Issue report (see the guide [**here**][issues]) |
11+
| Testing | PR review (see the guide [**here**][prs]) |
12+
| - Bug fix<br/>- Enhancement | Pull request (see the guide [**here**][prs]) |
13+
| Monetary | [Buy official products][store] |
14+
15+
[forum]: https://forum.arduino.cc
16+
[issues]: contributor-guide/issues.md#issue-report-guide
17+
[beta-testing]: contributor-guide/beta-testing.md#beta-testing-guide
18+
[prs]: contributor-guide/pull-requests.md#pull-request-guide
19+
[store]: https://store.arduino.cc
20+
21+
## Resources
22+
23+
- [**Development Guide**](contributor-guide/development.md#development-guide)

‎docs/contributor-guide/assets/checks.png‎

39.1 KB
Loading

‎docs/contributor-guide/development.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/other/development.md -->
2+
3+
# Development Guide
4+
5+
> [!NOTE]
6+
> The `arduino-app-cli` is designed to run on the Board and access peripherals that are not available on a development PC.
7+
>
8+
> For easier testing, using an **Arduino UNO Q** is recommended, as local testing is limited to functionalities that do not require board-specific features.
9+
10+
## Prerequisites
11+
12+
The following development tools must be available in your local environment:
13+
14+
- [Go](https://go.dev/dl/)
15+
- [Docker](https://docs.docker.com/engine/install/)
16+
- [adb client](https://developer.android.com/tools/adb) [optionally]
17+
18+
## Building the Project
19+
20+
---
21+
❗ Building on Windows machines is not supported.
22+
---
23+
24+
Build the project (run once):
25+
26+
- `go tool task init`
27+
- `go tool task build`
28+
- `go tool task generate:assets` to download locally the assets of the [Arduino Bricks](https://github.com/arduino/app-bricks-py)
29+
30+
Start the arduino-app-cli in daemon mode:
31+
32+
- `ARDUINO_APP_CLI__DATA_DIR=debian/arduino-app-cli/home/arduino/.local/share/arduino-app-cli go tool task start`
33+
34+
NOTE: only a subset of HTTP APIs are working by running the daemon mode on a development PC. To run Arduino App CLI on the board see the **Running Arduino App CLI on the board** section below.
35+
36+
## Running Checks
37+
38+
> [!NOTE]
39+
> Since Arduino App CLI runs on a Debian-based OS, some tests do not work on Windows and macOS
40+
41+
Checks and tests are set up to ensure the project content is functional and compliant with the established standards.
42+
43+
- `go tool task fmt-check`
44+
- `go tool task lint`
45+
- `go tool task test`
46+
47+
In particular, `go tool task test` runs the following tests
48+
49+
- `test:pkg` which exposes a cross-platform API for working with the board (those should run for every platform)
50+
- `test:internal` runs tests of the internal components, which targets only Linux
51+
52+
## Running Arduino App CLI on the board
53+
54+
This is reccomended way to test a local development version of Arduino App CLI on a board.
55+
56+
1. Connect an [Arduino UNO Q](https://docs.arduino.cc/hardware/uno-q/) board via USB.
57+
1. `go tool 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.
58+
59+
## Automatic Corrections
60+
61+
Tools are provided to automatically bring the project into compliance with some of the required checks.
62+
63+
- `go tool task fmt`
64+
65+
## Generate API docs
66+
67+
If a PR, change the HTTP API definitions, the following steps are needed:
68+
69+
1. Open the `cmd/gendoc/docs.go` and modify/add/remove the definitions
70+
1. Run `go tool 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‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!-- Source: https://github.com/arduino/tooling-project-assets/blob/main/documentation-templates/contributor-guide/general/contributor-guide/issues.md -->
2+
3+
# Issue Report Guide
4+
5+
---
6+
7+
❗ 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).
8+
9+
---
10+
11+
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:
12+
13+
https://github.com/arduino/arduino-app-cli/issues/new/choose
14+
15+
## Before Reporting an Issue
16+
17+
- Give the latest development version t (pre-releases) a test drive to see if your issue was already resolved:<br />
18+
https://github.com/arduino/arduino-app-cli/releases?q=prerelease%3Atrue
19+
- Search [existing pull requests and issues](https://github.com/arduino/arduino-app-cli/issues?q=) to see if it was already reported.<br />
20+
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 👍.
21+
22+
## Qualities of an Excellent Report
23+
24+
- Concise and descriptive issue title.<br />
25+
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.
26+
- Describe the issue and what behavior you were expecting.<br />
27+
Include the full and exact text of any relevant error or warning messages you might have encountered.
28+
- Provide a full set of steps necessary to reproduce the issue.<br />
29+
Demonstration code or commands should be complete and simplified to the minimum necessary to reproduce the issue.
30+
- Be responsive.<br />
31+
We may need you to provide additional information in order to investigate and resolve the issue.<br />
32+
Make sure your GitHub account is configured so that you will receive notifications of responses to your issue report.
33+
- 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.

0 commit comments

Comments
 (0)