Libellus Potionis

The project uses a publicly readable, version-controlled Git repository at a stable URL, gitlab.com/godisch/potillus — readable without an account and cloneable over HTTPS.

The project's source repository uses Git, which inherently records, for every commit, what changed (the diff/tree), who made the change (author and committer identity), and when (author and commit timestamps). The full history is publicly browsable on GitLab (commit list, diffs, and blame view) at gitlab.com/godisch/potillus/-/commits/main

The repository contains ongoing interim development commits on the main branch between releases, not only final release snapshots, so work in progress is publicly available for collaborative review. The full commit history is browsable at gitlab.com/godisch/potillus/-/commits/main

The project uses Git, the most widely used distributed version control system, hosted on GitLab. Repository: gitlab.com/godisch/potillus

Every user-facing release has a unique version identifier. The app carries a three-part versionName (MAJOR.MINOR.PATCH) and a strictly increasing integer versionCode, both defined in android/app/build.gradle.kts. CONTRIBUTING.md requires that the versionName, the top CHANGELOG.md entry, the README title, and the proguard-rules.pro header all carry the same version string and that versionCode increases by at least 1 each release; the tools/release-check.sh release gate enforces this consistency automatically. The iOS app shares the same single human-readable version: MARKETING_VERSION is derived from the top CHANGELOG.md entry (the same source of truth as Android's versionName), so a release carries one identical version string on both platforms.

Each release is identified within the version control system by a git tag on GitLab. Every published version has a corresponding tag of the form v<versionName>, so any release can be located and checked out directly from the repository history. Tags are browsable at gitlab.com/godisch/potillus/-/tags

Each release is accompanied by human-readable release notes in CHANGELOG.md: a curated summary (not raw version-control log output), with a concise subject line plus prose describing the major changes, typically separating user-facing changes from internal ones so users can judge the upgrade impact. Localized store release notes are additionally maintained per versionCode under fastlane/metadata/android/<locale>/changelogs/.

To date there have been no publicly known run-time vulnerabilities in the project's own results (as opposed to its dependencies) that had a CVE assignment or similar at release time and were fixed in a release. As the criterion permits, N/A is selected because there have been no such publicly known vulnerabilities. Should this ever change, the fixed CVE(s) will be named in the corresponding CHANGELOG.md entry.

Users submit bug reports through the project's GitLab issue tracker, with android@godisch.de offered as an alternative. This process is documented in the README's "Feedback & Contributing" section.

The project uses the GitLab issue tracker to track individual issues. The tracker is enabled and public, and users are directed to it: the README ("Feedback & Contributing") and CONTRIBUTING.md §2 point bug reports and enhancement suggestions there, while SECURITY.md routes security-sensitive reports to a private channel instead. Issue tracker: gitlab.com/godisch/potillus/-/issues

No bug reports have been submitted in the last 2–12 months, so there are no unacknowledged reports; the requirement to acknowledge a majority of submitted bug reports is therefore satisfied. The GitLab issue tracker is open and monitored for incoming reports: gitlab.com/godisch/potillus/-/issues

No enhancement requests have been submitted in the last 2–12 months, so there are none left unanswered; the requirement to respond to a majority (>50%) of enhancement requests is satisfied. Enhancement requests are accepted via the GitLab issue tracker: gitlab.com/godisch/potillus/-/issues

Reports and responses are publicly archived and searchable in the GitLab issue tracker: all issues and merge requests — open and closed — remain publicly visible, are full-text searchable, and are addressable by stable URLs for later reference.

The process for reporting vulnerabilities is published in SECURITY.md at the repository root (which GitLab surfaces as the project's security policy) and is linked from the README's "Security" section. Reporters are asked to disclose privately via PGP-encrypted e-mail to android@godisch.de rather than opening a public issue.

Private vulnerability reporting is the required path and SECURITY.md documents exactly how to send the information privately: a PGP-encrypted e-mail to android@godisch.de, using the maintainer's published key (fingerprint 1842 323B 4FCF 9B90 995F A17F A350 B991 F05A 4857), retrievable from the official Debian keyserver (hkps://keyring.debian.org:443). If a reporter cannot use PGP, the maintainer arranges a secure channel before any sensitive details are shared.

No vulnerability reports have been received in the last 6 months, so there is no initial response time to measure. SECURITY.md nevertheless commits to acknowledging any future vulnerability report within 14 days, so the requirement is covered in advance; this item will be marked Met once a report has been received and handled within that window.

The application is built from source with Gradle. The repository contains the full build definition (android/build.gradle.kts, android/app/build.gradle.kts, android/settings.gradle.kts), a checked-in Gradle wrapper (gradlew / gradlew.bat), and an orchestrating Makefile, so the software can be automatically rebuilt from source (e.g. ./gradlew assembleRelease). As independent evidence, F-Droid reproducibly builds the app from this same source (see its build recipe in fdroiddata). Repository: gitlab.com/godisch/potillus On iOS, make ios regenerates the Xcode project with XcodeGen and builds via the Swift toolchain, so a single documented command produces the app.

The project builds with the standard, widely used Android toolchain: Gradle (with the Kotlin DSL) and the Android Gradle Plugin, the Kotlin compiler, and the checked-in Gradle wrapper, orchestrated by a Makefile. These are the conventional build tools for Android applications. The iOS app uses the standard Apple toolchain: the Swift compiler and Swift Package Manager for the PotillusKit package, an Xcode project generated declaratively by XcodeGen from ios/project.yml, all driven by the same Makefile. These are conventional iOS build tools.

The build toolchain itself is FLOSS: Gradle, the Gradle wrapper, the Android Gradle Plugin, and the Kotlin compiler are all Apache-2.0 licensed. F-Droid builds and distributes the app entirely within its free-software build pipeline (see its build recipe in fdroiddata), demonstrating the project is buildable with FLOSS tooling. Note: some Android SDK components (build-tools, the platform android.jar) are under the non-OSI Android SDK License — a well-known caveat common to all Android apps — but the project itself introduces no proprietary build tools. The iOS build likewise relies on FLOSS or freely-available tooling: the open-source Swift toolchain and Swift Package Manager, XcodeGen (MIT), and SwiftLint (MIT); Xcode itself is the platform's free IDE.

The project ships a substantial automated test suite, released as FLOSS under GPL-3.0-or-later in the same repository: JVM unit tests in android/app/src/test/ (domain, data, l10n, util, and ViewModel layers, plus LocaleSyncTest) and instrumented tests in android/app/src/androidTest/ (Room migration validation, Compose UI components, on-device locale formatting), using FLOSS test frameworks (JUnit, AndroidX/Compose testing). How to run the tests is documented in CONTRIBUTING.md §5 "Testing strategy" (./gradlew :app:test for unit tests, ./gradlew :app:connectedAndroidTest for instrumented tests) and §7. The iOS side mirrors this: a broad PotillusKit unit-test suite plus app-target tests, sharing golden vectors with Android so the two implementations are held to the same expected results.

The test suite is invoked in the standard way for a Gradle/Android project: ./gradlew test runs the JVM unit tests and ./gradlew connectedCheck runs the instrumented tests on a device or emulator. This conventional invocation is documented in CONTRIBUTING.md (Section 5, "Testing strategy", and the change-submission checklist in Section 2). The iOS tests are invoked the standard way too: swift test runs the PotillusKit unit tests, and the app-target tests run under xcodebuild. Both are wired into the Makefile's iOS targets.

The project has an automated test suite on both platforms — JVM unit tests plus an instrumented suite on Android, and the PotillusKit suite on iOS — covering the major functionality. Statement coverage of the unit-testable code clears the enforced floors on both platforms — a 90% line floor on Android (Kover, koverVerify) and the same 90% line floor for PotillusKit (make -C ios cover-check); the current figures are printed by a make qa-android / make qa-ios run, so they are re-measured rather than quoted.

A GitLab CI pipeline (.gitlab-ci.yml) runs on every merge request targeting main and executes the project's device-free gates — tools/release-check.sh --Werror, make check-static and an osv-scanner source scan — so contributed changes are checked continuously rather than only at release time. The checks are enforced: Merge requests > "Pipelines must succeed" is enabled, so a red pipeline blocks the merge. Observed green at https://gitlab.com/godisch/potillus/-/pipelines/2700494992. The heavier half — the unit-test and lint suites, which need an SDK-bearing image and, for iOS, macOS — still runs locally before each release; widening the pipeline to cover it is tracked in docs/ROADMAP.md and is what the related automated_integration_testing (silver) still waits on.

The project has a written policy that new functionality ships with tests. CONTRIBUTING.md §5 ("Testing strategy") states that the domain layer is the coverage floor and that new domain logic ships with its own tests, and §2 (step 3) makes passing the tests and following the §5 testing conventions a precondition for accepting any change.

The add-tests policy is demonstrably followed. The test tree mirrors the source almost one-to-one: each non-trivial domain and utility class has a dedicated test (AlcoholCalculator, DayResolver, ChartBucketing, Trend, LocaleDetector, BackupManager, CsvExporter, …), every ViewModel has its own test class, schema changes are guarded by MigrationTest, and new locales/strings are guarded by LocaleSyncTest, which fails the build if a translation is incomplete. Recent releases include this test and QA work (see CHANGELOG.md). The commit history shows feature changes landing together with their tests. The iOS port carries its own XCTest suite (ios/PotillusKit/Tests), including schema-parity and calculator tests pinned to the shared golden vectors, so features land with tests on both platforms.

The project's documented instructions for change proposals include the test-addition policy. CONTRIBUTING.md §2 ("Submitting changes"), step 3, states that per the mandatory test policy in §5, major new functionality MUST include automated tests covering it in the same change, and that ./gradlew test must pass and the release gate must stay green. The full policy is defined in §5. The same policy covers the iOS Swift suite; make check-swift-tests guards that added Swift tests actually assert.

The project enables both a linter and strict compiler warnings, using FLOSS tools. Android Lint is run as a build gate (./gradlew lintDebug) configured in android/app/build.gradle.kts with abortOnError = true and warningsAsErrors = true, so lint warnings fail the build. In addition, the Kotlin compiler is configured with allWarningsAsErrors.set(true), promoting every compiler warning to a build-breaking error. The project deliberately uses no lint baseline (no silent suppression); the few exceptions are explicit and documented in the build file. On the iOS side SwiftLint — a FLOSS linter pinned to version 0.65.0 — runs as a make ios gate over the Swift sources, so lint findings are caught before a build ships.

Warnings are addressed by construction: because Android Lint is configured with warningsAsErrors = true and the Kotlin compiler with allWarningsAsErrors = true, any unaddressed warning breaks the build, so a release cannot be produced with outstanding warnings and the source tree stays warning-free. The few deliberate exceptions are explicit and reviewable in android/app/build.gradle.kts rather than hidden in a suppression baseline. On the iOS side SwiftLint — a FLOSS linter pinned to version 0.65.0 — runs as a make ios gate over the Swift sources, so lint findings are caught before a build ships.

The project is maximally strict with warnings. The Kotlin compiler runs with allWarningsAsErrors = true, so every compiler warning fails the build, and Android Lint runs with warningsAsErrors = true and abortOnError = true, promoting every lint warning to a build-breaking error. Rather than suppressing warnings, the project removes their causes and re-enables checks once underlying tooling bugs are fixed (e.g. the PluralsCandidate and WrongStartDestinationType lint checks were restored after workarounds were no longer needed). ktlint was additionally added as a style checker. These gates are configured in android/app/build.gradle.kts. On the iOS side the strictness gate is SwiftLint (a FLOSS linter pinned to version 0.65.0), run as part of make ios; Swift compiler warnings-as-errors are not currently enforced.

The project's primary developer (a Debian Developer) knows how to design secure software, and the application embodies established secure-design principles: least privilege and minimized attack surface (no network permission at all, no camera/microphone/location, and API 30 chosen so that even storage runtime permissions are unnecessary); fail-safe/secure defaults and data minimization (offline-only, no analytics or crash reporting, data confined to the app sandbox and encrypted at rest); reliance on vetted cryptography rather than home-grown implementations (hardware-backed Android Keystore, encrypted DataStore); defensive input validation and fail-secure behaviour (the JSON backup importer rejects too-new files and reads optional fields defensively, enums deserialize via runCatching{…}.getOrDefault(…)); and open design (fully GPL-3.0-or-later open source and auditable). The same understanding carries to the iOS port — Apple's App Sandbox, the iOS Keychain for the key (SecretKeyProviding), and the shared defensive backup parsing — with platform-specific iOS hardening refinements tracked in docs/ROADMAP.md.

A primary developer knows the common error classes that lead to vulnerabilities in an Android application (cf. the OWASP Mobile Top 10) and at least one mitigation for each, as reflected in the code: injection is avoided by using Room's parameterized queries rather than string concatenation; insecure data storage is mitigated by the app sandbox, encryption at rest, and keeping sensitive keys in the hardware-backed Android Keystore; unsafe deserialization / missing input validation is mitigated by defensive backup-import parsing (optional-field fallbacks, rejection of too-new files via VersionTooHigh, and runCatching{…}.getOrDefault(…) for enums); excessive attack surface is mitigated by a minimal permission profile with no network permission; insecure IPC is avoided by not exporting unnecessary components; and weak/home-grown cryptography is avoided by relying on the platform's vetted cryptographic facilities. The same understanding carries to the iOS port — Apple's App Sandbox, the iOS Keychain for the key (SecretKeyProviding), and the shared defensive backup parsing — with platform-specific iOS hardening refinements tracked in docs/ROADMAP.md.