diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..924d028 --- /dev/null +++ b/.env.example @@ -0,0 +1,47 @@ +# ------------------------------------------------------- +# Eye Lab: Gaze Tracker API — Environment Variables +# ------------------------------------------------------- +# Copy this file to .env and fill in your actual values: +# cp .env.example .env +# +# ⚠️ Never commit your .env file — it's in .gitignore +# ------------------------------------------------------- + + +# --- Flask --- +# Set to 'development' for local dev, 'production' for deployment +FLASK_ENV=development + +# Set to 'true' to enable Flask debug mode (development only) +FLASK_DEBUG=true + +# Port Flask will run on (default: 5000) +FLASK_RUN_PORT=5000 + + +# --- Firebase --- +# Your Firebase project credentials +# Get these from: Firebase Console → Project Settings → General +FIREBASE_API_KEY=your-firebase-api-key +FIREBASE_AUTH_DOMAIN=your-project-id.firebaseapp.com +FIREBASE_PROJECT_ID=your-project-id +FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com +FIREBASE_MESSAGING_SENDER_ID=your-messaging-sender-id +FIREBASE_APP_ID=your-firebase-app-id + +# Firebase Cloud Function base URL (used for API calls to Firebase Functions) +# Example: https://us-central1-your-project-id.cloudfunctions.net +FIREBASE_FUNCTION_URL=https://us-central1-your-project-id.cloudfunctions.net + + +# --- Google Cloud (if deploying to GCP) --- +# Your Google Cloud project ID +GOOGLE_CLOUD_PROJECT=your-gcp-project-id + + +# --- Model / ML Config --- +# Path to store trained gaze estimation models +MODEL_STORAGE_PATH=./models + +# Temp directory for batch prediction files +TEMP_DIR=./tmp diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c075851 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,168 @@ +# Contributing to Eye Lab: Gaze Tracker API + +Thank you for your interest in contributing! 🎉 +Eye Lab is an open-source eye-tracking backend built with Python and Flask. Every contribution — big or small — is welcome. + +--- + +## 📋 Table of Contents + +- [Getting Started](#getting-started) +- [Setting Up Locally](#setting-up-locally) +- [How to Contribute](#how-to-contribute) +- [Branch Naming](#branch-naming) +- [Commit Message Style](#commit-message-style) +- [Pull Request Guidelines](#pull-request-guidelines) +- [Issue Guidelines](#issue-guidelines) +- [Code Style](#code-style) + +--- + +## Getting Started + +1. **Fork** this repository on GitHub +2. **Clone** your fork locally: + ```bash + git clone https://github.com//eye-tracker-api.git + cd eye-tracker-api + ``` +3. **Add upstream remote** to stay in sync: + ```bash + git remote add upstream https://github.com/ruxailab/eye-tracker-api.git + ``` + +--- + +## Setting Up Locally + +### Prerequisites +- Python 3.x +- pip + +### Steps + +```bash +# Create and activate a virtual environment +python3 -m venv venv +source venv/bin/activate # Linux/macOS +venv\Scripts\activate # Windows + +# Install dependencies +pip install -r requirements.txt + +# Copy environment variables +cp .env.example .env +# Edit .env and fill in your values + +# Run the Flask app +flask run +``` + +> **Note:** The project has a frontend counterpart at [web-eye-tracker-front](https://github.com/ruxailab/web-eye-tracker-front). Install it as well for the full application experience. + +--- + +## How to Contribute + +### Working on an existing issue +1. Go to the [Issues](https://github.com/ruxailab/eye-tracker-api/issues) tab +2. Find an unassigned issue you want to work on +3. **Comment on it** expressing your interest — the first person to comment gets preference +4. Wait for a maintainer to assign it to you before starting work + +### Raising a new issue +1. Check that the issue doesn't already exist +2. Open a new issue with a clear title and description +3. The person who raises an issue has **preference** to fix it +4. Tag it appropriately (`bug`, `enhancement`, `documentation`, etc.) + +--- + +## Branch Naming + +Use the following convention: + +| Type | Format | Example | +|------|--------|---------| +| Bug fix | `fix/` | `fix/hardcoded-file-paths` | +| New feature | `feat/` | `feat/auto-model-selection` | +| Documentation | `docs/` | `docs/add-contributing-guide` | +| Refactor | `refactor/` | `refactor/rename-typo-function` | +| Tests | `test/` | `test/add-predict-unit-tests` | + +--- + +## Commit Message Style + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +: + +# Examples: +fix: remove hardcoded Firebase URL and use environment variable +feat: add auto model selection for gaze estimation +docs: add CONTRIBUTING.md and .env.example +refactor: rename trian_and_predict to train_and_predict +test: add smoke test for Flask app startup +``` + +**Types:** `fix`, `feat`, `docs`, `refactor`, `test`, `chore`, `perf` + +--- + +## Pull Request Guidelines + +1. **One PR per issue** — keep your changes focused +2. **Link the issue** in your PR description using `Closes #` +3. **Describe your changes** clearly — what you changed and why +4. **Test your changes** locally before submitting +5. **Keep PRs small** — large PRs are harder to review and less likely to be merged quickly + +### PR Description Template + +```markdown +## What does this PR do? + + +## Related Issue +Closes # + +## Changes Made +- +- + +## How to Test + +``` + +--- + +## Issue Guidelines + +When opening an issue, please include: + +- **Clear title** summarizing the problem or proposal +- **Description** of what's happening vs. what's expected +- **Steps to reproduce** (for bugs) +- **Proposed solution** (if you have one) +- **Your environment** (OS, Python version) for bugs + +--- + +## Code Style + +- Follow [PEP 8](https://peps.python.org/pep-0008/) for Python code +- Use meaningful variable and function names +- Add docstrings to new functions +- Remove unused imports before submitting + +--- + +## Need Help? + +- Join our [Discord](https://discord.gg/fDFwcE6WD2) and introduce yourself +- Ask questions in [GitHub Discussions](https://github.com/ruxailab/RUXAILAB/discussions) +- Email us at `ruxailab@gmail.com` + +We look forward to your contributions! 🚀 \ No newline at end of file