Skip to content

Commit 0571c70

Browse files
AstorisTheBraveAstorisTheBrave
authored
Merge pull request #57 from greyfoundry/sd/docs-refresh-1.3.3
docs: refresh project documentation
2 parents 780d8c0 + b1dfcc3 commit 0571c70

15 files changed

Lines changed: 91 additions & 62 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ body:
6060
attributes:
6161
label: URSA version
6262
description: App version name, or the commit hash if you built it yourself.
63-
placeholder: e.g. 0.1.0 or commit abc1234
63+
placeholder: e.g. 1.3.3 or commit abc1234
6464
validations:
6565
required: true
6666

@@ -76,7 +76,7 @@ body:
7676
id: kuma-version
7777
attributes:
7878
label: Uptime Kuma version
79-
placeholder: e.g. 2.4.0
79+
placeholder: e.g. 2.5.5
8080
validations:
8181
required: true
8282

@@ -90,7 +90,9 @@ body:
9090
- Plain HTTP
9191
- Self-signed certificate
9292
- Reverse proxy (nginx / Caddy / Traefik / other)
93+
- Access proxy with custom headers (Pangolin / Cloudflare Access / other)
9394
- Cloudflare Tunnel
95+
- Tailscale or another mesh VPN
9496
- Other / not sure
9597
validations:
9698
required: true
@@ -102,9 +104,11 @@ body:
102104
options:
103105
- Login / authentication (incl. 2FA)
104106
- Monitor list / detail / heartbeats
105-
- Pause / resume
107+
- Monitor or maintenance management
106108
- Public status page viewer
107109
- Push notifications (UnifiedPush)
110+
- Widget / Quick Settings / shortcuts
111+
- Wear OS
108112
- Other
109113
validations:
110114
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,10 @@ body:
55
- type: markdown
66
attributes:
77
value: |
8-
URSA follows a focused roadmap (viewer -> actions -> push). Please check the
9-
README and existing issues first. Ideas that broaden scope may be deferred,
10-
but we still want to hear them.
8+
URSA is a focused native companion for monitoring and incident response.
9+
Please check the README, public roadmap, and existing issues first. Broad
10+
server-administration features may be deferred, but we still want to hear
11+
the underlying use case.
1112
1213
- type: checkboxes
1314
id: preflight

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,9 @@ Closes #
1313

1414
<!-- Unit tests, and how you exercised it on a device/emulator (Android version). -->
1515

16-
- [ ] `./gradlew :app:testDebugUnitTest` passes
17-
- [ ] `./gradlew :app:lintDebug` passes
16+
- [ ] `./gradlew :app:testFdroidDebugUnitTest :app:testGithubDebugUnitTest` passes
17+
- [ ] `./gradlew :app:lintFdroidDebug :app:lintGithubDebug` passes
18+
- [ ] Wear tests/lint pass if the change affects `:wear` or shared contracts
1819
- [ ] Tested on device/emulator (state Android version):
1920

2021
## Checklist

‎CONTRIBUTING.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,12 @@ Build and test:
3535

3636
```bash
3737
export JAVA_HOME="<path-to-jbr>" # e.g. Android Studio's bundled JBR
38-
./gradlew assembleDebug # build the debug APK
39-
./gradlew :app:testDebugUnitTest # run unit tests
40-
./gradlew :app:lintDebug # run Android Lint (must pass)
41-
./gradlew :wear:testDebugUnitTest :wear:lintDebug :wear:assembleDebug
38+
./gradlew :app:assembleFdroidDebug :app:assembleGithubDebug
39+
./gradlew :app:testFdroidDebugUnitTest :app:testGithubDebugUnitTest
40+
./gradlew :app:lintFdroidDebug :app:lintGithubDebug
41+
./gradlew :wear:assembleFdroidDebug :wear:assembleGithubDebug
42+
./gradlew :wear:testFdroidDebugUnitTest :wear:testGithubDebugUnitTest
43+
./gradlew :wear:lintFdroidDebug :wear:lintGithubDebug
4244
```
4345

4446
To run the app, install the debug APK and point it at an Uptime Kuma instance
@@ -77,7 +79,8 @@ The same check runs in CI, so enabling the hook locally saves a round trip.
7779
`feat(push): ...`.
7880
- **Tests**: add or update unit tests for logic changes. Wire-format parsing must
7981
stay covered.
80-
- **Lint**: `./gradlew :app:lintDebug` must be clean before you push.
82+
- **Lint**: both `fdroid` and `github` flavor lint tasks must be clean before you
83+
push.
8184

8285
## Pull requests
8386

‎URSA_BUILD_SPEC.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@ snake/camel naming splits, and double-encoded configuration, belongs in
6060
| Component | Version |
6161
|---|---|
6262
| Kotlin | 2.4.10 |
63-
| Compose BOM | 2026.08.00 |
64-
| Android Gradle Plugin | 9.3.2 |
63+
| Compose BOM | 2026.09.00 |
64+
| Android Gradle Plugin | 9.4.1 |
6565
| Gradle | 9.7.1 |
6666
| compileSdk / targetSdk | 37 / 37 |
6767
| phone minSdk | 26 |
@@ -74,9 +74,11 @@ built-in Kotlin, so modules do not apply `org.jetbrains.kotlin.android`.
7474
## Verification gates
7575

7676
```bash
77-
./gradlew.bat :app:testDebugUnitTest :app:lintDebug :app:assembleDebug --no-daemon
78-
./gradlew.bat :wear:testDebugUnitTest :wear:lintDebug :wear:assembleDebug --no-daemon
79-
./gradlew.bat -PursaWearBridge=true :app:assembleDebug --no-daemon
77+
./gradlew.bat :app:testFdroidDebugUnitTest :app:testGithubDebugUnitTest --no-daemon
78+
./gradlew.bat :app:lintFdroidDebug :app:lintGithubDebug --no-daemon
79+
./gradlew.bat :wear:testFdroidDebugUnitTest :wear:testGithubDebugUnitTest --no-daemon
80+
./gradlew.bat :wear:lintFdroidDebug :wear:lintGithubDebug --no-daemon
81+
./gradlew.bat :app:assembleFdroidRelease --no-daemon
8082
```
8183

8284
Live release-candidate QA covers password/TOTP or token login, reconnect, direct

‎docs/architecture/index.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
last-updated: 2026-09-04
2+
last-updated: 2026-09-21
33
owner: astoris
4-
status: in-flux
4+
status: stable
55
---
66

77
## what this is
@@ -27,7 +27,7 @@ distributor (ntfy) ──push──▶ core.push (UnifiedPush receiver) ──
2727
core.push (validated endpoint) -> data.repository -> core.network -> Kuma Webhook provider
2828
```
2929

30-
**layers (M1 implemented unless noted)**
30+
**layers**
3131
- `core.network` → `.../core/network/` (KumaClient, KumaParse, StatusPageClient) -
3232
see `docs/modules/network.mdx`.
3333
- `core.storage` → `.../core/storage/` (ConnectionStore, encrypted caches,

‎docs/infrastructure/deployment.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
last-updated: 2026-09-20
2+
last-updated: 2026-09-21
33
owner: astoris
44
status: in-flux
55
---

‎docs/infrastructure/env.mdx‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
last-updated: 2026-07-03
2+
last-updated: 2026-09-21
33
owner: astoris
44
status: stable
55
---
@@ -15,15 +15,14 @@ toolchain and the local dev servers.
1515
**build env**
1616
- `JAVA_HOME` → Android Studio's bundled JBR:
1717
`C:/Program Files/Android/Android Studio/jbr`
18-
- Android SDK: `C:/Users/User/AppData/Local/Android/Sdk`
19-
(pointed to by `local.properties` → `sdk.dir`, gitignored).
20-
- Installed: platform android-36.1, build-tools 36.1.0/37.0.0. No cmdline-tools
21-
(so no `sdkmanager` - install android-37 via Studio's SDK Manager if needed).
18+
- Android SDK platform 37 and build-tools 37.0.0.
19+
- A gitignored `local.properties` points `sdk.dir` at the machine's Android SDK.
20+
- Android Studio's bundled JBR 21 runs the build; source and bytecode target 17.
2221

2322
**dev servers (Docker)**
24-
- `uptime-kuma-dev` → `louislam/uptime-kuma:2` on `:3001`.
25-
Admin `ursadev` / `UrsaDev123!`. Seed `data/db-config.json = {"type":"sqlite"}`
26-
then restart to skip the 2.x DB-setup wizard.
23+
- Use an official `louislam/uptime-kuma` image on host port `3001`. The current
24+
compatibility baseline is tag `2.5.5`; create disposable QA credentials during
25+
setup or pass them through local environment variables.
2726
- `ntfy-dev` → `binwiederhier/ntfy` on `:8080` (UnifiedPush distributor test).
2827
- From emulator reach the host at `10.0.2.2`; Kuma reaches ntfy at
2928
`host.docker.internal:8080`.
@@ -32,5 +31,5 @@ toolchain and the local dev servers.
3231

3332
- `local.properties` must escape the Windows drive colon for lint:
3433
`sdk.dir=C\:/Users/User/AppData/Local/Android/Sdk`. Gradle accepts the
35-
unescaped form but `lintDebug` fails on it.
34+
unescaped form but Android lint tasks fail on it.
3635
- No secrets live in the repo. Kuma JWTs are stored encrypted on-device only.

‎docs/modules/push.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
last-updated: 2026-09-04
2+
last-updated: 2026-09-21
33
owner: astoris
44
status: stable
55
---
@@ -64,7 +64,7 @@ connection: push works while the app is closed.
6464
create/update/test/remove actions and per-monitor alert-mode state.
6565

6666
**depends on**
67-
- `org.unifiedpush.android:connector:3.3.4` (excludes JVM `tink`; we ship
67+
- `org.unifiedpush.android:connector:3.3.5` (excludes JVM `tink`; we ship
6868
`tink-android`). See `docs/references/unifiedpush.mdx` (verified from source).
6969
- `androidx.core` (NotificationManagerCompat), `MainActivity` (content intent).
7070

@@ -149,7 +149,7 @@ connection: push works while the app is closed.
149149
incident to the event log.
150150
- Kuma 2.5.1's Pinglet and SMS Gateway additions are separate outbound providers;
151151
the existing Webhook provider still sends the same `{ heartbeat, monitor, msg }`
152-
body, verified live through Kuma 2.5.3. URSA should keep the provider-neutral
152+
body, verified live through Kuma 2.5.5. URSA should keep the provider-neutral
153153
Webhook to UnifiedPush path rather than depend on a third-party provider.
154154
- Managed alerts derive a stable, hashed notification ID from server scope and
155155
monitor ID, so a new status replaces the old one without colliding across servers.

‎docs/overview.mdx‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
last-updated: 2026-09-04
2+
last-updated: 2026-09-21
33
owner: astoris
4-
status: in-flux
4+
status: stable
55
---
66

77
## what this is
@@ -43,11 +43,13 @@ and the module docs under `docs/modules/`.
4343
notification Pause/Resume actions, local TLS-expiry reminders, home-screen widget,
4444
Quick Settings tile, app shortcuts, and full i18n. See
4545
`docs/planning/m4-native-depth.mdx`.
46-
- Builds green (`assembleDebug`, `lintDebug`); parsers unit-tested. Monitor list and
47-
detail flows are smoke-tested on a Pixel 8 emulator. See `docs/sessions/log.mdx`.
46+
- Both `fdroid` and `github` phone/Wear flavors build, test, and lint cleanly; the
47+
F-Droid release flavor is also built in CI. Monitor list and detail flows are
48+
device-tested. See `docs/sessions/log.mdx`.
4849
- Competitor-parity items CP-001 through CP-046 are complete, except the explicitly
49-
partial CP-031 advanced monitor-type creation boundary. This includes fleet
50-
incidents/reliability, certificate/domain dashboards, and the filtered global
50+
partial CP-031 advanced monitor-type creation boundary. Native SFTP creation and
51+
editing are included; less common type-specific forms remain in Kuma. This includes
52+
fleet incidents/reliability, certificate/domain dashboards, and the filtered global
5153
event log, an explainable 30-day uptime/latency aggregate, and a persisted
5254
favourite-monitor live-heartbeat panel, encrypted local incident notes, and a
5355
redacted native share summary, one-tap managed Kuma Webhook setup for the
@@ -60,8 +62,8 @@ and the module docs under `docs/modules/`.
6062
offers an opt-in always-on fleet glance display with explicit power and burn-in
6163
guidance, and the separate Wear OS app now provides an attention-first dashboard,
6264
monitor details, complications, and optionally paired private actions. Advanced
63-
monitor-type-specific create fields remain the open CP-031 boundary. Scoped app
64-
deep links, compact rows, connection guidance, a manual update check, advanced
65+
monitor-type-specific create fields other than SFTP remain the open CP-031
66+
boundary. Scoped app deep links, compact rows, connection guidance, a manual update check, advanced
6567
filters with saved views, and actionable typed connection failures are complete.
6668
- Security posture mapped to OWASP MASVS: `docs/security.mdx`.
6769
- Local reference material (gitignored): `docs/kuma-notes/`, `archive/uptime-kuma/`,

0 commit comments

Comments
 (0)