Files
Sparkledns/CONTRIBUTING.md
kalarina 1db29ee44a Redesign the app
New look based on the SparkleDNS concept: a dark theme, a floating
bottom panel with Home, Activity and Settings, and pages for the
blocklists, apps and About.

- Home: big ON/OFF switch, the current server, 24-hour stats and chart
- Activity: requests, blocked, average time and cache share for 24 hours
  or 7 days, company dominance, and the live log with search and filter
- Blocklists: HaGeZi Pro preset next to Pro++ and TIF, lists can be
  switched off without deleting them, automatic updates (daily or
  weekly, optionally Wi-Fi only) through JobScheduler
- Settings: server list, custom server, server test and per-app DNS
- Hourly numbers for the charts are kept on the device, without domains

The server list now ships with the app; it is no longer downloaded
from the repository.
2026-10-30 19:58:08 +02:00

4.2 KiB

Contributing to SparkleDNS

Thanks for wanting to help! This guide explains where to contribute, what fits the project and how to send changes.

Where to contribute

Issues and pull requests go to the repository on Gitea.

Ways to help

  • Report a bug — use the Bug report template.
  • Add a DoH server — open an issue with the DoH server or blocklist template, see Adding a DoH server.
  • Suggest a blocklist — use the DoH server or blocklist template.
  • Suggest a feature — use the Feature request template; check Out of scope first.
  • Fix a translation — use the Translation fix template or send a pull request.
  • Write code — see Pull requests.

Before you start

  • Small changes (typos, obvious bugs, translation fixes): send a pull request directly.
  • Anything bigger (new features, UI changes, new dependencies): open an issue first and wait for a go-ahead, so your work isn't wasted.

Ground rules

  • No ads, analytics, telemetry, trackers or accounts.
  • DNS queries may only go to the DoH server the user selected — never anywhere else.
  • No Google Play Services, Firebase or other proprietary libraries — the app must stay buildable for F-Droid.
  • New dependencies must be open source and justified in the pull request.
  • Be respectful in issues and reviews.

Out of scope

These will not be accepted:

  • Changing the default DoH server.
  • Logging, uploading or sharing users' DNS queries.
  • Features that require Google Play Services or a proprietary SDK.

Adding a DoH server

Servers ship with the app in Providers.kt, so a new server reaches users with the next release. The app never downloads a server list.

To suggest a server, open an issue with the DoH server or blocklist template, or send a pull request that adds one entry to Providers.builtIn with the server's name, DoH URL, privacy policy link, bootstrap IPs, whether it supports HTTP/3 and, optionally, the operator's own donation page.

The server must:

  • be public and free, without an account;
  • support RFC 8484;
  • publish what it logs, and not sell or share query data;
  • be run by a non-profit, a community or an individual rather than a large company.

Before sending, check that it works: in the app choose Custom server, enter the URL and tap Test server.

If you are unsure whether a server fits, open an issue with the DoH server or blocklist template first.

Blocklists

Blocklist presets must be public, actively maintained and licensed for this kind of use. Use the DoH server or blocklist template and include a link to the list's homepage.

Translations

SparkleDNS is available in exactly six languages: English, Russian, German, Japanese, Lithuanian and Chinese. Fixes to these are welcome; new languages are not accepted.

  • App strings: app/src/main/res/values-<lang>/strings.xml (English is values/).
  • Store listing: fastlane/metadata/android/<locale>/.

If your code adds new strings, add them to values/strings.xml. Translations for the other languages are welcome but not required — mention missing ones in the pull request.

Pull requests

  1. Fork the repository and create a branch from main.
  2. Keep one topic per pull request.
  3. Follow the existing Kotlin and Jetpack Compose style; keep comments short and in English; don't reformat unrelated code.
  4. Make sure ./gradlew assembleDebug testDebugUnitTest passes, and test on a device or emulator. For changes that may affect speed or memory, scripts/bench.sh compares two APKs on a rooted device or emulator (scripts/bench-build.sh builds them from two revisions).
  5. Write short, plain commit messages in English (for example Fix tunnel restart after server switch).
  6. Add screenshots for UI changes.

Security

Please don't post details of security issues publicly. Open a short issue titled "Security contact" without any details, and the maintainer will reach out privately.

License

By contributing, you agree that your contribution is licensed under the GNU General Public License v3.0 or later, the same as the rest of the project.