mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-20 05:10:26 -05:00
Dries Peeters
fb734fa91c
Fix stale build-guide links, document the implemented quotes API scopes/endpoints, and clarify quote access plus permission-denial behavior so docs match route and test-backed behavior.
133 lines
4.7 KiB
Markdown
133 lines
4.7 KiB
Markdown
# TimeTracker Development Guide
|
||
|
||
Quick reference for running the project locally, running tests, and contributing. For a single-page contributor overview (workflows, adding routes/services/templates), see [Contributor Guide](docs/development/CONTRIBUTOR_GUIDE.md). For full guidelines, see [Contributing](CONTRIBUTING.md) and the [developer documentation](docs/development/CONTRIBUTING.md).
|
||
|
||
## Running Locally
|
||
|
||
### Option A: Python and virtual environment
|
||
|
||
1. Clone the repo and enter the directory:
|
||
|
||
```bash
|
||
git clone https://github.com/drytrix/TimeTracker.git
|
||
cd TimeTracker
|
||
```
|
||
|
||
2. Create and activate a virtual environment:
|
||
|
||
```bash
|
||
python -m venv venv
|
||
# Windows:
|
||
venv\Scripts\activate
|
||
# Linux/macOS:
|
||
source venv/bin/activate
|
||
```
|
||
|
||
3. Install dependencies:
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
4. Copy the environment template and set required variables:
|
||
|
||
```bash
|
||
cp env.example .env
|
||
```
|
||
|
||
Edit `.env`: set `SECRET_KEY` (e.g. from `python -c "import secrets; print(secrets.token_hex(32))"`). For a local DB, you can use SQLite (see [Local Testing with SQLite](docs/development/LOCAL_TESTING_WITH_SQLITE.md)).
|
||
|
||
5. Initialize the database and run the app:
|
||
|
||
```bash
|
||
flask db upgrade
|
||
flask run
|
||
```
|
||
|
||
By default the app is at http://127.0.0.1:5000.
|
||
|
||
### Option B: Docker (SQLite, no PostgreSQL)
|
||
|
||
For a quick run without installing Python locally:
|
||
|
||
```bash
|
||
docker-compose -f docker/docker-compose.local-test.yml up --build
|
||
```
|
||
|
||
Then open http://localhost:8080. See [Local Testing with SQLite](docs/development/LOCAL_TESTING_WITH_SQLITE.md) for details.
|
||
|
||
## Environment Setup
|
||
|
||
- Copy `env.example` to `.env` and adjust values.
|
||
- Key variables: `SECRET_KEY`, `DATABASE_URL` (or leave default for SQLite), `TZ`, `CURRENCY`.
|
||
- Full list and descriptions: [Docker Compose Setup](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md) and `env.example`.
|
||
|
||
## Dependencies
|
||
|
||
- **Python:** 3.11+
|
||
- **Package list:** `requirements.txt`
|
||
- **Package install for tests:** `setup.py` is used so the app can be installed as a package (e.g. `pip install -e .`) for testing; core dependencies remain in `requirements.txt`.
|
||
|
||
## Folder Structure
|
||
|
||
```
|
||
TimeTracker/
|
||
├── app/ # Flask app: routes, models, services, templates, utils
|
||
├── desktop/ # Electron-style desktop app
|
||
├── mobile/ # Flutter mobile app
|
||
├── docker/ # Docker config and scripts
|
||
├── tests/ # Pytest tests
|
||
├── docs/ # Documentation
|
||
├── app.py # Application entry point
|
||
├── env.example # Environment template
|
||
└── requirements.txt # Python dependencies
|
||
```
|
||
|
||
For more detail, see [ARCHITECTURE.md](ARCHITECTURE.md) and [Project Structure](development/PROJECT_STRUCTURE.md).
|
||
|
||
## Coding Conventions
|
||
|
||
- Follow the [Contributing guidelines](docs/development/CONTRIBUTING.md): PEP 8, Black (line length 88), type hints and docstrings where appropriate.
|
||
- Use blueprints for routes; keep business logic in [services](docs/development/SERVICE_LAYER_AND_BASE_CRUD.md).
|
||
|
||
## Development Workflow
|
||
|
||
1. Create a branch for your change.
|
||
2. Run tests locally: `pytest` (or `pytest --cov=app` for coverage).
|
||
3. Lint/format: follow [Contributing](docs/development/CONTRIBUTING.md) (e.g. Black, flake8).
|
||
4. For user-facing changes, add an entry under **Unreleased** in [CHANGELOG.md](CHANGELOG.md).
|
||
|
||
## Running Tests
|
||
|
||
```bash
|
||
# All tests
|
||
pytest
|
||
|
||
# With coverage
|
||
pytest --cov=app
|
||
|
||
# Single file
|
||
pytest tests/test_timer.py
|
||
|
||
# Single test class or test
|
||
pytest tests/test_routes/test_api_v1_projects_refactored.py -v
|
||
```
|
||
|
||
See [Contributing – Testing](docs/development/CONTRIBUTING.md#testing) for more options and conventions.
|
||
|
||
## Build Steps
|
||
|
||
- **Web app:** No separate frontend build required; Tailwind and static assets are served as-is (or built via your pipeline if you use one). Run the app with `flask run` or `python app.py`.
|
||
- **Docker image:** `docker build -t timetracker .` from repo root. See [Docker Compose Setup](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md).
|
||
- **Mobile/Desktop:** See [Build Guide](../scripts/README-BUILD.md) and [mobile-desktop-apps/README.md](mobile-desktop-apps/README.md) for Flutter and Electron build steps.
|
||
|
||
## Contributing
|
||
|
||
1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
|
||
2. Follow the full [Contributing guidelines](docs/development/CONTRIBUTING.md) (branching, PR process, changelog).
|
||
3. For user-facing changes, add an entry under **Unreleased** in [CHANGELOG.md](CHANGELOG.md).
|
||
|
||
## Releases
|
||
|
||
How versions and releases are managed is documented in [Version Management](docs/admin/deployment/VERSION_MANAGEMENT.md). The application version is defined in `setup.py` as the single source of truth.
|