Files
FocusGram-Android/CONTRIBUTING.md
T
Ujwal223 cfc59ecc4e feat(changes for v3.1):
- 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
2026-11-12 15:14:54 +05:45

90 lines
4.5 KiB
Markdown

# 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:
1. **README or other supporting docs changes:** Edits, additions, deletions, or typo fixes in documentation, guides, or Markdown files.
2. **Code comments changes:** Additions, edits, deletions, or rephrasing of source code comments.
3. **Test changes:** Adding, editing, or deleting unit, UI, or integration tests without accompanying functional implementation or bug fixes.
4. **License changes:** Edits to license files, terms, or copyright headers.
5. **Cosmetic formatting & whitespace:** Reformatting, linting adjustments, import reordering, or whitespace edits that introduce no functional or behavioral difference.
6. **Trivial refactoring & churn:** Variable renaming, minor syntactic restructuring, or automated/bot-generated PRs without clear performance or correctness justification.
7. **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:
1. **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.
2. **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.
3. **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.
4. **Clean Web Sandboxing:**
Web content manipulation is strictly client-side via Mozilla GeckoView content scripts (`app/src/main/assets/scripts/` or `app/src/main/assets/extensions/content-engine/`). Never inline large raw JavaScript strings directly in Kotlin source files.
5. **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
```bash
# 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
1. Fork the repository and create a branch with a descriptive name (`git checkout -b feature/your-feature`).
2. Run `./gradlew :app:testDebugUnitTest` to ensure all tests pass.
3. Keep diffs minimal, focused, and free of drive-by refactors.
4. Open a Pull Request referencing any relevant issues.
5. 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](AGENTS.md)**.