mirror of
https://github.com/Ujwal223/FocusGram.git
synced 2026-11-20 10:53:56 +01:00
- Added developer options with new options - make sure logs (debug build) doesnt containg any "sensitive" info - updated ALL Documentations to increase transparency even more. Special thanks to @petkofff
4.5 KiB
4.5 KiB
Contributing to FocusGram
Thank you for your interest in contributing to FocusGram! FocusGram is a free, open-source digital wellness tool built under the GNU Affero General Public License v3.0 (AGPL-3.0).
Pull Request Scope & Restrictions
Merge requests containing only the following changes will NOT be accepted:
- README or other supporting docs changes: Edits, additions, deletions, or typo fixes in documentation, guides, or Markdown files.
- Code comments changes: Additions, edits, deletions, or rephrasing of source code comments.
- Test changes: Adding, editing, or deleting unit, UI, or integration tests without accompanying functional implementation or bug fixes.
- License changes: Edits to license files, terms, or copyright headers.
- Cosmetic formatting & whitespace: Reformatting, linting adjustments, import reordering, or whitespace edits that introduce no functional or behavioral difference.
- Trivial refactoring & churn: Variable renaming, minor syntactic restructuring, or automated/bot-generated PRs without clear performance or correctness justification.
- Unsolicited dependency updates: Version bumps or build dependency updates without prior discussion or security advisory backing.
It is strongly recommended to open an issue instead to report typos, documentation gaps, missing test scenarios, or suggestions. Pull requests should focus on substantive bug fixes, core architectural improvements, or approved feature additions.
Architecture Principles
Every pull request must uphold these non-negotiable rules:
- Local-Only Operation: FocusGram never sends user data off-device. No user telemetry, no tracking analytics, and no remote crash loggers. Core Instagram traffic is strictly sandboxed. The only permitted external network calls are official GitHub release/notice checks and the isolated, user-initiated rewarded ad WebView.
- The Login Flow is a Black Box: Never write code or content scripts that read, intercept, or modify authentication form fields, credentials, cookies, or 2FA tokens.
- No Automation of Instagram Actions: FocusGram is an intentionality tool, not an automation bot. Do not contribute auto-likers, auto-followers, auto-scrollers, or mass-DM tools.
- Clean Web Sandboxing:
Web content manipulation is strictly client-side via Mozilla GeckoView content scripts (
app/src/main/assets/scripts/orapp/src/main/assets/extensions/content-engine/). Never inline large raw JavaScript strings directly in Kotlin source files. - FOSS Dependency Licensing: All dependencies must be compatible with AGPL-3.0 (e.g. Apache 2.0, MIT, BSD, MPL 2.0, LGPL/GPL).
Development Environment Setup
Prerequisites
- OS: Linux, macOS, or Windows
- JDK: OpenJDK 21 (Temurin or Adoptium recommended)
- Android SDK: API Level 26 minimum, API 35 target, Build-Tools 35.0.0
- Build System: Gradle (bundled wrapper
./gradlew)
Build Commands
# Clone the repository
git clone https://github.com/Ujwal223/FocusGram.git
cd FocusGram
# Run unit tests
./gradlew :app:testDebugUnitTest
# Build debug APK
./gradlew :app:assembleDebug
# Build standard release APKs (with ABI splits)
./gradlew :app:assembleRelease
# Build uncloned Instagram package edition (com.instagram.android)
./gradlew :app:assembleRelease -PuseInstaPackage=true
# Or use the interactive build script
./build-release.sh
Code Style & Standards
- Kotlin: Idiomatic Kotlin 2.0+ following official Kotlin code style.
- Compose: Jetpack Compose Material 3 using Unidirectional Data Flow (UDF),
StateFlow, and coroutines. - Storage: Use Jetpack DataStore Preferences for simple preferences and AndroidX Room for relational persistence (session snapshots, screen time records, reel history).
- Comments: Follow maintainer-voice commenting. Explain why something is designed the way it is, warn about platform traps, and delete restatements of code. Avoid decorative ASCII art or divider lines.
Submitting Pull Requests
- Fork the repository and create a branch with a descriptive name (
git checkout -b feature/your-feature). - Run
./gradlew :app:testDebugUnitTestto ensure all tests pass. - Keep diffs minimal, focused, and free of drive-by refactors.
- Open a Pull Request referencing any relevant issues.
- If using an AI coding assistant or autonomous agent, ensure it strictly adheres to the protocol, interrogation requirements, and scope checks defined in AGENTS.md.