Contributing

Contributing

How to file an issue, open a PR, and what to expect.

---

Branch strategy

main is the only active branch. There used to be a master carrying a minimal Hello-World + Google Sign-In starter — it's been deleted from the remote. If a master ever reappears, it's not authoritative; work on main.

There are occasional feature / experiment branches with names like codex/fix-review-findings from automated tooling. Treat those as scratch space — they're not promoted directly.

---

Filing an issue

Before opening, check:

• Troubleshooting for your symptom.
• Known Issues for in-flight known bugs.
• Existing GitHub issues.

A good issue includes:

• App version (versionCode + versionName) — visible in Settings → About at the bottom.
• Device + Android version + locale.
• Steps to reproduce.
• Actual vs expected behaviour.
• Logcat for crashes (filter on tag AndroidRuntime for the stack trace).

---

Opening a PR

1. Fork the repository on GitHub.

2. Branch off main:

   git checkout main
   git pull
   git checkout -b feature/your-thing

3. Build secrets (you'll need them to actually run / sign anything):

   ./retrieve_secrets.sh

   Requires Bitwarden vault access — see Getting Started. External contributors who don't have vault access can still develop against the existing google-services.json if it's been committed for them; sign-in will only work for SHA-1 fingerprints already registered in Firebase. Contact the maintainer to register your debug keystore.

4. Write code. Keep PRs small and focused — one logical change per PR is the norm.

5. Local checks before pushing:

   ./gradlew :app:lintDebug
   ./gradlew :app:testDebugUnitTest
   ./gradlew :app:assembleDebug

6. Commit using Conventional Commits (see below).

7. Push + open a PR. In the description, include:

   • What changed and why.
   • Screenshots / screen recording for UI changes.
   • Manual test steps.
   • Any analytics events added (so the next audit pass is complete).

---

Commit message style

The existing history uses Conventional Commits. Standard prefixes:

Prefix	When
feat:	New user-visible feature
fix:	Bug fix
chore:	Version bumps, dep bumps, project hygiene without behaviour change
docs:	README / wiki / comment / planning-doc changes
refactor:	Internal restructuring, no behaviour change
style:	Formatting, whitespace, pure UI polish
test:	Test-only changes
build:	Gradle, signing, ProGuard, GPP config
ci:	CI config (none today)

Subject ≤ 72 characters, imperative mood ("add splash screen", not "added splash screen"). Body lines wrap at ~72 characters.

Example:

feat(payments): outlier-robust average for Payment History hero

Replace the naive `total / months` mean with a Tukey-fences (IQR×1.5)
filtered mean so a single anomalous month doesn't distort the
displayed "Average Monthly Expense". Falls back to plain mean for
≤3 months of history.

Refs #42.

---

Code style

• Kotlin — official JetBrains style (kotlin.code.style=official in gradle.properties). Let Studio's default formatter (Ctrl+Alt+L / ⌘⌥L) handle the rest.
• XML resources — 4-space indent. Don't bother re-sorting attributes; keep the diff small.
• Strings — every user-visible string goes in res/values/strings.xml or is set dynamically in code. Don't hard-code literals in layouts (lint will flag).
• Comments — default to none. Add one when the why is non-obvious (workaround, invariant, surprise). Don't restate what the code already says with its names.

---

Analytics discipline

If your change adds, removes, or repurposes a user-visible flow:

• Adding a flow: add a matching Analytics.xxx() method in util/Analytics.kt and fire it at the action site. Use snake_case event names grouped by surface (screen_*, subscription_*, payment_*, etc.). Scalar params only — see Analytics & Audit.
• Removing a flow: also remove the matching Analytics.xxx() method. Don't leave orphan wrappers.
• Renaming: pick one of (a) keep the old event name for continuity, (b) rename and add a comment noting the historical mapping. Either is fine; just don't silently break a dashboard chart someone might be watching.

---

What gets rejected (or asked to be split)

• Drive-by reformatting bundled with a behaviour change.
• New dependencies without a clear use case in the same PR.
• Lowering minSdk / compileSdk / targetSdk without an issue discussing it first (the deliberate Android-15+ minimum exists for a reason).
• New Firebase products (Crashlytics, RemoteConfig, App Distribution, etc.) without prior agreement — they have implications for privacy disclosure and the build pipeline.
• New CI without checking — CI minutes are real money, and the build needs secrets management.
• Reintroducing the legacy GoogleSignInClient API. Credential Manager is the canonical path.

---

Updating this wiki

The wiki lives in its own repository:

https://github.com/aarshps/varisankya-android.wiki.git

To edit it locally:

git clone https://github.com/aarshps/varisankya-android.wiki.git
cd varisankya-android.wiki
# edit any of the .md files
git add .
git commit -m "docs: clarify the rules-deploy step in Firebase Setup"
git push

Pushes go straight to master of the wiki repo and show up immediately at https://github.com/aarshps/varisankya-android/wiki. There's no PR flow — be a little careful.

If your code change behaviour-shifts something documented here, update the wiki in the same PR's lifetime so the two stay in sync. The wiki documenting the wrong thing is worse than no wiki.

---

Licence

The repo's README.md declares the MIT Licence. A formal LICENSE file has not been committed yet — treat the MIT terms as the intent. Don't paste in third-party code you don't have rights to.