From 30612a0d874f0a6d0a28f18baaf8dbab668d58b9 Mon Sep 17 00:00:00 2001 From: librelad Date: Sun, 31 May 2026 00:48:38 +0100 Subject: [PATCH] docs: organize docs/ into purpose folders with consistent naming Sort docs/ into guide/ contributing/ architecture/ roadmap/ and rename to consistent kebab-case (USER->guide/install-and-use, FOOTPRINT-> architecture/system-footprint, frontend-modularization->architecture/ webui-architecture, etc.). Add a docs/README.md index and a docs/ CONTRIBUTING.md pointer so the forge still surfaces the contributing guide. Fix every reference (README, init.sh comments, frontend code comments, and the USER<->DEVELOPMENT cross-links). History preserved via git mv. Root stays README.md + CLAUDE.md. Co-Authored-By: Claude Opus 4.8 Signed-off-by: librelad --- README.md | 10 ++--- .../frontend/components/backup/index.js | 2 +- .../frontend/components/manifest.dev.json | 2 +- .../core/kernel/js/feature-registry.js | 2 +- .../frontend/core/kernel/js/lifecycle.js | 2 +- containers/libreportal/frontend/index.html | 2 +- docs/CONTRIBUTING.md | 42 ++----------------- docs/README.md | 19 +++++++++ .../system-footprint.md} | 0 .../webui-architecture.md} | 0 docs/contributing/contributing.md | 40 ++++++++++++++++++ .../development.md} | 2 +- docs/{USER.md => guide/install-and-use.md} | 4 +- docs/{PROMISE.md => guide/promise.md} | 0 .../updates-and-distribution.md} | 0 init.sh | 8 ++-- 16 files changed, 80 insertions(+), 55 deletions(-) create mode 100644 docs/README.md rename docs/{FOOTPRINT.md => architecture/system-footprint.md} (100%) rename docs/{frontend-modularization.md => architecture/webui-architecture.md} (100%) create mode 100644 docs/contributing/contributing.md rename docs/{DEVELOPMENT.md => contributing/development.md} (99%) rename docs/{USER.md => guide/install-and-use.md} (95%) rename docs/{PROMISE.md => guide/promise.md} (100%) rename docs/{updates-and-distribution-roadmap.md => roadmap/updates-and-distribution.md} (100%) diff --git a/README.md b/README.md index a43ccf5..f06fe6a 100755 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ toggle — it's the whole point. The entire platform is **free software under the [GNU AGPLv3](LICENSE)**. Self-host it and you get **everything** — every feature, no paywalls, no -telemetry. See [our Promise](docs/PROMISE.md) for exactly what that means. +telemetry. See [our Promise](docs/guide/promise.md) for exactly what that means. ## What you get @@ -45,9 +45,9 @@ data on separate disks with `--system-dir=` / `--containers-dir=` / `--backups-d ## Documentation -- **[docs/USER.md](docs/USER.md)** — install, place data on separate disks/drives, +- **[docs/guide/install-and-use.md](docs/guide/install-and-use.md)** — install, place data on separate disks/drives, update, back up, uninstall. -- **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** — run a dev copy, cut stable/edge +- **[docs/contributing/development.md](docs/contributing/development.md)** — run a dev copy, cut stable/edge releases, and test them before publishing. ## LibrePortal Connect (optional) @@ -59,11 +59,11 @@ different: we work like a **courier carrying a sealed box.** We move your data between your devices and store backup copies, but it stays locked and *you* hold the only key — we can't open it, and we never run your apps for you. **Everything we offer, you can also set up yourself for free.** -[Our Promise](docs/PROMISE.md) spells out exactly where that line sits. +[Our Promise](docs/guide/promise.md) spells out exactly where that line sits. ## Contributing -PRs welcome — see [CONTRIBUTING.md](docs/CONTRIBUTING.md). We use a lightweight +PRs welcome — see [CONTRIBUTING.md](docs/contributing/contributing.md). We use a lightweight DCO sign-off (`git commit -s`), no CLA. ## Acknowledgments diff --git a/containers/libreportal/frontend/components/backup/index.js b/containers/libreportal/frontend/components/backup/index.js index 1121955..50483b0 100644 --- a/containers/libreportal/frontend/components/backup/index.js +++ b/containers/libreportal/frontend/components/backup/index.js @@ -1,6 +1,6 @@ // components/backup/index.js — Backup Center as a self-contained feature module. // -// FIRST page migrated to the feature-module contract (docs/frontend-modularization.md). +// FIRST page migrated to the feature-module contract (docs/architecture/webui-architecture.md). // The kernel drives mount()/unmount() for the /backup route instead of // spa.js's handleBackup(). The heavy controller (backup-page.js, ~129KB) is // still lazy-loaded on first mount, so cold-load cost is unchanged. diff --git a/containers/libreportal/frontend/components/manifest.dev.json b/containers/libreportal/frontend/components/manifest.dev.json index 9c9752f..ce7b70e 100644 --- a/containers/libreportal/frontend/components/manifest.dev.json +++ b/containers/libreportal/frontend/components/manifest.dev.json @@ -1,6 +1,6 @@ { "version": 1, - "note": "Phase-0 hand-committed manifest (to be replaced by the generated /data/webui/generated/features.json once the scan generator lands — see docs/frontend-modularization.md). 'module' is the feature's self-registering index.js; the kernel loads these from here so they no longer need + docs/architecture/webui-architecture.md. --> diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 33ac7e9..9fe527b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,40 +1,6 @@ -# Contributing to LibrePortal +# Contributing -Thanks for wanting to help — LibrePortal is built in the open, and -contributions are genuinely welcome. +The contributing guide lives at **[contributing/contributing.md](contributing/contributing.md)**. -## Ground rules - -- LibrePortal is **AGPLv3**. By contributing, your work is offered under that - same license (see the DCO below). -- **Match the surrounding code** — keep it simple and readable, and follow - the style of the file you're editing. -- Keep pull requests focused: one change per PR where you can. - -## Developer Certificate of Origin (DCO) - -We use the [DCO](https://developercertificate.org/) instead of a CLA — no -paperwork, just a sign-off certifying you have the right to submit your code. - -Add a `Signed-off-by` line to every commit by committing with `-s`: - -```bash -git commit -s -m "your message" -``` - -That appends: - -``` -Signed-off-by: Your Name -``` - -By signing off, you agree to the DCO: that you wrote the patch (or otherwise -have the right to submit it) and that it may be included under the project's -AGPLv3 license. - -## Bugs & ideas - -Open an issue — clear steps to reproduce and your environment details help a -lot. - -Thanks for helping keep self-hosting free and open. 🕊️ +(This pointer stays at `docs/` so the forge surfaces it in the new-issue/PR flow; +the full guide and the rest of the docs are sorted under [docs/](README.md).) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..3471cb0 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ +# LibrePortal docs + +Sorted by audience. Start with **guide/** if you're running LibrePortal, +**contributing/** if you're hacking on it. + +## guide/ — using LibrePortal +- [install-and-use.md](guide/install-and-use.md) — install, place data on separate disks, update, back up, uninstall. +- [promise.md](guide/promise.md) — the LibrePortal Promise: free/open, no paywalls, no telemetry, in plain language. + +## contributing/ — working on LibrePortal +- [contributing.md](contributing/contributing.md) — how to contribute (DCO sign-off, no CLA). +- [development.md](contributing/development.md) — run a dev copy, cut stable/edge releases, test before publishing. + +## architecture/ — how it's built +- [system-footprint.md](architecture/system-footprint.md) — everything LibrePortal places outside its data roots, and who owns it. +- [webui-architecture.md](architecture/webui-architecture.md) — the WebUI component-module system (as-built). + +## roadmap/ — where it's going +- [updates-and-distribution.md](roadmap/updates-and-distribution.md) — vision for hotfixes, the "Updates & Improvements" front door, and registry-not-marketplace distribution. diff --git a/docs/FOOTPRINT.md b/docs/architecture/system-footprint.md similarity index 100% rename from docs/FOOTPRINT.md rename to docs/architecture/system-footprint.md diff --git a/docs/frontend-modularization.md b/docs/architecture/webui-architecture.md similarity index 100% rename from docs/frontend-modularization.md rename to docs/architecture/webui-architecture.md diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md new file mode 100644 index 0000000..33ac7e9 --- /dev/null +++ b/docs/contributing/contributing.md @@ -0,0 +1,40 @@ +# Contributing to LibrePortal + +Thanks for wanting to help — LibrePortal is built in the open, and +contributions are genuinely welcome. + +## Ground rules + +- LibrePortal is **AGPLv3**. By contributing, your work is offered under that + same license (see the DCO below). +- **Match the surrounding code** — keep it simple and readable, and follow + the style of the file you're editing. +- Keep pull requests focused: one change per PR where you can. + +## Developer Certificate of Origin (DCO) + +We use the [DCO](https://developercertificate.org/) instead of a CLA — no +paperwork, just a sign-off certifying you have the right to submit your code. + +Add a `Signed-off-by` line to every commit by committing with `-s`: + +```bash +git commit -s -m "your message" +``` + +That appends: + +``` +Signed-off-by: Your Name +``` + +By signing off, you agree to the DCO: that you wrote the patch (or otherwise +have the right to submit it) and that it may be included under the project's +AGPLv3 license. + +## Bugs & ideas + +Open an issue — clear steps to reproduce and your environment details help a +lot. + +Thanks for helping keep self-hosting free and open. 🕊️ diff --git a/docs/DEVELOPMENT.md b/docs/contributing/development.md similarity index 99% rename from docs/DEVELOPMENT.md rename to docs/contributing/development.md index ed8e921..0389167 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/contributing/development.md @@ -1,7 +1,7 @@ # LibrePortal — Development & Releases How to run a development copy, cut stable/edge releases, and test them before they -go out. For installing/using LibrePortal, see [USER.md](USER.md). +go out. For installing/using LibrePortal, see [install & use guide](../guide/install-and-use.md). ## Mental model (read this first) diff --git a/docs/USER.md b/docs/guide/install-and-use.md similarity index 95% rename from docs/USER.md rename to docs/guide/install-and-use.md index f05b657..4483474 100644 --- a/docs/USER.md +++ b/docs/guide/install-and-use.md @@ -1,11 +1,11 @@ # LibrePortal — Install & Use How to install, place, update, and remove LibrePortal. For building releases or -running a dev copy, see [DEVELOPMENT.md](DEVELOPMENT.md). +running a dev copy, see [development guide](../contributing/development.md). > **Note:** the `get.libreportal.org` host isn't live yet. Until it is, install > from a local release artifact or a git/local checkout — see -> [DEVELOPMENT.md](DEVELOPMENT.md). The commands below are the intended public flow. +> [development guide](../contributing/development.md). The commands below are the intended public flow. ## Requirements diff --git a/docs/PROMISE.md b/docs/guide/promise.md similarity index 100% rename from docs/PROMISE.md rename to docs/guide/promise.md diff --git a/docs/updates-and-distribution-roadmap.md b/docs/roadmap/updates-and-distribution.md similarity index 100% rename from docs/updates-and-distribution-roadmap.md rename to docs/roadmap/updates-and-distribution.md diff --git a/init.sh b/init.sh index 37a90eb..7da64a5 100755 --- a/init.sh +++ b/init.sh @@ -133,7 +133,7 @@ command_symlink="/usr/local/bin/libreportal" # systemd unit, sudoers). BUMP THIS whenever you change any of those — a plain # `update apply` runs as the manager and CANNOT rewrite root-owned files, so a bump # tells the updater the new release needs a root re-install (which re-bakes them). -# Recorded at install in $lp_lib_dir/.footprint_version. See docs/DEVELOPMENT.md. +# Recorded at install in $lp_lib_dir/.footprint_version. See docs/contributing/development.md. footprint_version=3 footprint_marker="$lp_lib_dir/.footprint_version" @@ -895,7 +895,7 @@ initUsers() # op the manager can't modify), and a fixed system-binary set. Excluded: # bash/su + tee/cp/chmod/chown/sed/mv/rm/install (each root-equivalent). Also # clears legacy broad grants (a NOPASSWD: ALL in the main /etc/sudoers, sudo-group -# membership). See docs/FOOTPRINT.md. +# membership). See docs/architecture/system-footprint.md. initScopedSudoers() { local sudoers_dropin="/etc/sudoers.d/${sudo_user_name}" @@ -1620,7 +1620,7 @@ completeInitMessage() # containers run AS the docker-install user and the rootless daemon is that user's # systemd --user service, so stop those BEFORE removing the users. Self-contained: # uses only init.sh's inline helpers, so it still works as it deletes /docker. -# Keep in sync with docs/FOOTPRINT.md. +# Keep in sync with docs/architecture/system-footprint.md. # Discover where THIS box was actually installed — custom installs put the roots # anywhere, and a bare `init.sh uninstall` has no LP_*_DIR in scope. The systemd # unit is the authoritative baked record (Environment=LP_*_DIR + User=). @@ -1731,7 +1731,7 @@ runFullUninstall() fi fi - # 3. Remove the out-of-/docker footprint (see docs/FOOTPRINT.md). + # 3. Remove the out-of-/docker footprint (see docs/architecture/system-footprint.md). rm -f /usr/local/bin/libreportal /usr/local/bin/libreportal-uninstall rm -rf /usr/local/lib/libreportal rm -f "/etc/sudoers.d/$mgr"