From 5a5b41be3002eaa3e8f4730ea57387cd66e2fd24 Mon Sep 17 00:00:00 2001 From: Guy Godfroy Date: Thu, 13 Aug 2026 16:09:21 +0200 Subject: [PATCH] docs: fix the quickstart a reader would paste, and add the files a public repo is judged on --- .editorconfig | 22 ++++++++++++++++++++++ .gitattributes | 7 +++++++ CODE_OF_CONDUCT.md | 31 +++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 +- README.md | 2 +- examples/curl/uhttpd_instances.sh | 16 ++++++++++++++-- 6 files changed, 76 insertions(+), 4 deletions(-) create mode 100644 .editorconfig create mode 100644 .gitattributes create mode 100644 CODE_OF_CONDUCT.md diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..106fdad --- /dev/null +++ b/.editorconfig @@ -0,0 +1,22 @@ +# ucode sources are tab-indented, which matters because a mixed file is hard to read in a +# language whose blocks are brace-delimited but whose comments carry the load. +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.uc] +indent_style = tab + +[Makefile] +indent_style = tab + +[*.{sh,py}] +indent_style = tab + +[*.{md,json,yml,yaml,html,css}] +indent_style = space +indent_size = 2 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..a692717 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +# Normalise to LF on checkin. The shipped tree lands on OpenWrt, where a CRLF in an init +# script or a uci-defaults hook fails at a shell that gives no useful error. +* text=auto eol=lf + +*.apk binary +*.png binary +*.zst binary diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a809552 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,31 @@ +# Code of conduct + +## The short version + +Be straightforward and be kind. Discuss the work, not the person doing it. + +## What is expected + +- Argue about the change, its evidence and its trade-offs. +- Say plainly when you are unsure, or when you were wrong. Both are useful signal here. +- Accept that a maintainer may decline a change that is correct but not wanted, and that the + reason will be given. + +## What is not acceptable + +Harassment, personal attacks, demeaning comments, or sustained disruption of a discussion. +Publishing someone's private information without permission. Sexualised language or imagery. + +## Scope + +Applies to issues, pull requests, commit messages, and any other space where someone is +participating in this project. + +## Reporting + +Report a concern to guy.godfroy@gugod.fr. Reports are read by the maintainer, kept +confidential, and answered. Security vulnerabilities go through `SECURITY.md` instead, which +has its own private disclosure path. + +Consequences for breaking this scale with the behaviour, from a request to stop, through +having a comment removed, to being blocked from the repository. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9cb0bb..fab0e1b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ uapi does NOT need `node`, `python`, or any JS toolchain. The OpenAPI spec is ge ## Dev loop ```sh -make test # lint + 600+ unit tests + coverage gate (~5 sec) +make test # lint + the unit suite + coverage gate (a few seconds) make openapi # regenerate build/openapi.json from src/resources/*.uc make stage # stage files into build/openwrt/uapi/files/ for APK packaging make help # full target list diff --git a/README.md b/README.md index 8842695..86c1656 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ curl -H "Authorization: Bearer $TOKEN" \ -X POST https:///api/v3/firewall/rules \ -d '{ "target": "ACCEPT", - "match": { "src_zone": "wan", "dest_port": [22], "proto": ["tcp"] } + "match": { "src_zone": "wan", "dest_port": ["22"], "proto": ["tcp"] } }' ``` diff --git a/examples/curl/uhttpd_instances.sh b/examples/curl/uhttpd_instances.sh index 2c3f9c8..11fb15f 100755 --- a/examples/curl/uhttpd_instances.sh +++ b/examples/curl/uhttpd_instances.sh @@ -16,9 +16,21 @@ echo echo "# DANGER: writes to the 'main' instance that strip /api/v3=/usr/share/uapi/main.uc" echo "# from ucode_prefix are rejected with 422 conflict (self-lockout protection)." echo -echo "# Example: PATCH that keeps the uapi entry and adds another listen address" +# Writing this instance restarts the server that is answering the request, so curl usually +# reports "Empty reply from server" (exit 52) even though the write committed. That is uhttpd +# closing the connection mid-response, not a failure, which is why the exit status is tolerated +# here and the result is confirmed by reading the instance back afterwards. +echo "# Example: PATCH that keeps the uapi entry and re-states the listen addresses" req -H "$H_JSON" -X PATCH "$UAPI_BASE/uhttpd/instances/main" -d '{ "listen_http": ["0.0.0.0:80", "[::]:80"], "listen_https": ["0.0.0.0:443", "[::]:443"], "ucode_prefix": ["/api/v3=/usr/share/uapi/main.uc"] -}'; echo +}' || echo "(connection dropped: uhttpd restarted, see below)" +echo + +echo "# Read it back once uhttpd is listening again" +for _ in 1 2 3 4 5 6 7 8 9 10; do + sleep 1 + req --max-time 5 "$UAPI_BASE/uhttpd/instances/main" && break +done +echo