From 806e309d80701fa519819b0e434e32ad19e06c0d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 16:52:09 +0000 Subject: [PATCH 1/6] Initial plan From 3cb11ddbef273cf7afb870c7a19867e43820d103 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 16:56:24 +0000 Subject: [PATCH 2/6] docs: add wiki pages for Home, Getting Started, Architecture, and Database Schema Co-authored-by: altaskur <105789412+altaskur@users.noreply.github.com> --- wiki/Architecture.md | 698 ++++++++++++++++++++++++++++++++++++++++ wiki/Database-Schema.md | 651 +++++++++++++++++++++++++++++++++++++ wiki/Getting-Started.md | 417 ++++++++++++++++++++++++ wiki/Home.md | 147 +++++++++ 4 files changed, 1913 insertions(+) create mode 100644 wiki/Architecture.md create mode 100644 wiki/Database-Schema.md create mode 100644 wiki/Getting-Started.md create mode 100644 wiki/Home.md diff --git a/wiki/Architecture.md b/wiki/Architecture.md new file mode 100644 index 0000000..2305572 --- /dev/null +++ b/wiki/Architecture.md @@ -0,0 +1,698 @@ +# Architecture & Technical Design + +This document describes the architecture, design patterns, and technical decisions in OpenTimeTracker. + +## System Overview + +OpenTimeTracker is a **desktop application** built with modern web technologies: + +``` +┌─────────────────────────────────────────────┐ +│ Electron Application │ +├─────────────────────────────────────────────┤ +│ ┌────────────────┐ ┌─────────────────┐ │ +│ │ Renderer │◄──►│ Main Process │ │ +│ │ (Angular 21) │IPC │ (Node.js) │ │ +│ └────────────────┘ └─────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌────────────────┐ ┌─────────────────┐ │ +│ │ PrimeNG UI │ │ Prisma Client │ │ +│ └────────────────┘ └─────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────┐ │ +│ │ SQLite Database │ │ +│ └─────────────────┘ │ +└─────────────────────────────────────────────┘ +``` + +## Architecture Layers + +### 1. Presentation Layer (Angular Frontend) + +**Technology**: Angular 21 with standalone components + +**Responsibilities**: +- User interface rendering +- User interaction handling +- State management (services) +- Form validation +- Internationalization (i18n) + +**Key Components**: +- `src/app/pages/*` - Page components (routing targets) +- `src/app/components/*` - Reusable UI components +- `src/app/services/*` - Business logic and state +- `src/app/interfaces/*` - TypeScript interfaces + +**UI Framework**: PrimeNG + PrimeFlex +- Component library: PrimeNG +- Utility classes: PrimeFlex +- Default theme: Aura Black (dark mode) + +### 2. IPC Communication Layer + +**Technology**: Electron IPC (Inter-Process Communication) + +**Pattern**: Request-Response with type safety + +The renderer process communicates with the main process through a secure IPC bridge: + +```typescript +// Renderer side (Angular) +window.electronAPI.database.createProject(projectData) + +// Preload script (Bridge) +contextBridge.exposeInMainWorld('electronAPI', { + database: { + createProject: (data) => ipcRenderer.invoke('db:createProject', data) + } +}) + +// Main process (Electron) +ipcMain.handle('db:createProject', async (event, data) => { + return await prisma.project.create({ data }) +}) +``` + +**Security**: +- Context isolation enabled +- Node integration disabled in renderer +- Preload script as secure bridge + +### 3. Business Logic Layer (Electron Main Process) + +**Technology**: Node.js (Electron Main Process) + +**Responsibilities**: +- Database operations via Prisma +- File system operations +- Application lifecycle management +- Automatic backups +- Window management + +**Key Files**: +- `electron/src/main/main.ts` - Application entry point +- `electron/src/main/database.ts` - Database operations +- `electron/src/preload/preload.ts` - IPC bridge + +### 4. Data Layer (Prisma + SQLite) + +**Technology**: Prisma ORM + SQLite + +**Responsibilities**: +- Data persistence +- Schema management +- Migrations +- Type-safe database access + +**Database Location**: +- Development: `./dist/data/timetracker.db` +- Production: + - Windows: `%APPDATA%/OpenTimeTracker/data/timetracker.db` + - macOS: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` + - Linux: `~/.config/OpenTimeTracker/data/timetracker.db` + +--- + +## Data Model + +### Entity Relationship Diagram + +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Project │──1:N──│ Task │──N:M──│ Tag │ +└──────────────┘ └──────────────┘ └──────────────┘ + │ │ + │ │ + │1:N │1:N + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ AuditLog │ │ TimeEntry │ +└──────────────┘ └──────────────┘ + + ┌──────────────┐ + │ TaskStatus │ + └──────────────┘ + │1:N + ▼ + ┌──────────────┐ + │ Task │ + └──────────────┘ +``` + +### Core Entities + +#### Project +- Container for related tasks +- Can be closed when completed +- Tracks creation/update timestamps +- Related to audit logs + +#### Task +- Belongs to a project +- Has a status (optional) +- Can have multiple tags +- Tracks time entries +- Stores estimated hours + +#### Tag +- Reusable labels for tasks +- Many-to-many relationship with tasks +- Global across all projects + +#### TaskStatus +- Customizable workflow states +- Default status can be set +- Color-coded for UI +- Examples: "To Do", "In Progress", "Done" + +#### TimeEntry +- Records time worked +- Optional task association +- Date-based +- Stores minutes and notes + +#### WorkConfig (Singleton) +- Global work configuration template +- Daily/weekly minute targets +- Work days configuration +- Per-day schedule + +#### MonthConfig +- Overrides WorkConfig for specific months +- Month-specific work days and schedules + +#### DayType +- Types of special days (holidays, vacation, etc.) +- Color-coded +- Default minutes configuration + +#### DayOverride +- Specific day overrides +- Associates with DayType +- Custom minutes and notes + +#### AppSettings (Singleton) +- Application-wide settings +- Dark mode preference +- Language selection + +#### AuditLog +- Tracks entity changes +- Records action type and changes +- Associates with projects/tasks + +#### ActionHistory +- Undo/redo functionality +- Stores previous and new data +- Tracks undone status + +--- + +## Design Patterns + +### 1. Service Layer Pattern + +Angular services encapsulate business logic and state: + +```typescript +@Injectable({ providedIn: 'root' }) +export class ProjectService { + async getProjects(): Promise { + return window.electronAPI.database.getProjects() + } +} +``` + +**Benefits**: +- Separation of concerns +- Reusable business logic +- Easy testing with mocks + +### 2. Repository Pattern + +Database operations abstracted through Prisma: + +```typescript +// Main process +const project = await prisma.project.create({ + data: { name, description }, + include: { tasks: true } +}) +``` + +### 3. Observer Pattern + +Angular's RxJS for reactive state management: + +```typescript +@Injectable({ providedIn: 'root' }) +export class ThemeService { + private isDarkMode$ = new BehaviorSubject(true) + + get isDarkMode() { + return this.isDarkMode$.asObservable() + } +} +``` + +### 4. Strategy Pattern + +Translation strategy for i18n: + +```typescript +@Injectable({ providedIn: 'root' }) +export class TranslationService { + setLanguage(lang: 'en' | 'es') { + this.translate.use(lang) + } +} +``` + +--- + +## Key Technical Decisions + +### Why Electron? + +✅ **Pros**: +- Cross-platform (Windows, macOS, Linux) +- Single codebase +- Native OS integration +- Access to Node.js APIs +- Large ecosystem + +❌ **Cons**: +- Larger bundle size +- Memory footprint +- Requires distributing Chromium + +**Conclusion**: Best choice for local-first desktop app with web technologies. + +### Why SQLite? + +✅ **Pros**: +- File-based (no server needed) +- Fast for local operations +- ACID compliant +- Zero configuration +- Easy backups + +❌ **Cons**: +- No built-in sync +- Single-user by design + +**Conclusion**: Perfect for local-first, privacy-focused application. + +### Why Prisma? + +✅ **Pros**: +- Type-safe database access +- Auto-generated client +- Migration system +- Great DX (Developer Experience) +- Works well with SQLite + +❌ **Cons**: +- Client generation step +- Limited advanced SQL features + +**Conclusion**: Best ORM for TypeScript + SQLite + Electron. + +### Why Angular? + +✅ **Pros**: +- Full framework (batteries included) +- Strong TypeScript support +- Dependency injection +- RxJS integration +- Large ecosystem + +❌ **Cons**: +- Steeper learning curve +- Bundle size +- Opinionated structure + +**Conclusion**: Excellent choice for complex, maintainable applications. + +### Why PrimeNG? + +✅ **Pros**: +- Comprehensive component library +- Angular-native +- Themeable +- Professional appearance +- Good documentation + +**Conclusion**: Accelerates UI development with consistent design. + +--- + +## Build & Packaging Process + +### Development Build + +```bash +npm run dev +``` + +**Steps**: +1. `ng build --configuration=development` - Build Angular app +2. `tsc` (Electron main) - Compile TypeScript +3. `tsc` (Electron preload) - Compile preload script +4. `electron .` - Launch application + +### Production Build + +```bash +npm run dist +``` + +**Steps**: +1. `ng build` - Build Angular for production +2. `tsc` (Electron) - Compile TypeScript +3. `electron-builder` - Package application + +**Output**: +- Windows: NSIS installer (`.exe`) +- macOS: DMG image (`.dmg`) +- Linux: AppImage (`.AppImage`) and Deb package (`.deb`) + +### Build Configuration + +File: `package.json` → `build` section + +**Key settings**: +- `appId`: Application identifier +- `icon`: Application icon +- `files`: Files to include +- `asarUnpack`: Files to exclude from ASAR archive (Prisma, SQLite) + +--- + +## Security Considerations + +### Electron Security + +✅ **Implemented**: +- Context isolation enabled +- Node integration disabled in renderer +- Secure IPC bridge via preload script +- Content Security Policy (CSP) + +### Data Security + +✅ **Implemented**: +- Local-only data storage +- No network requests (except updates) +- User controls backups +- SQLite file encryption possible (user-managed) + +❌ **Not Implemented** (by design): +- Cloud sync (privacy-first approach) +- User authentication (single-user app) +- Encryption at rest (user can encrypt filesystem) + +--- + +## Testing Strategy + +### Unit Tests + +**Angular (Karma + Jasmine)**: +```bash +npm test +``` + +- Service tests +- Component tests +- Utility function tests + +**Electron (Vitest)**: +```bash +npm run test:electron +``` + +- Main process logic +- Database operations (mocked) + +### Code Quality + +**ESLint**: +```bash +npm run lint +``` + +**SonarQube**: +```bash +npm run sonar:check +``` + +- Code coverage +- Code smells +- Security vulnerabilities +- Maintainability rating + +--- + +## Performance Considerations + +### Database Optimization + +- Indexes on frequently queried fields +- Cascade deletes for data integrity +- Efficient queries with Prisma + +### Bundle Optimization + +- Tree shaking in production builds +- Lazy loading of Angular routes (when applicable) +- ASAR packaging for faster startup + +### Memory Management + +- Proper cleanup of subscriptions +- Efficient Angular change detection +- Prisma connection pooling (not needed for SQLite) + +--- + +## Internationalization (i18n) + +**Library**: `@ngx-translate/core` + +**Languages**: English (en), Spanish (es) + +**Translation Files**: +- `src/assets/i18n/en.json` +- `src/assets/i18n/es.json` + +**Usage**: +```html +

{{ 'home.title' | translate }}

+``` + +--- + +## Backup Strategy + +### Automatic Backups + +**Trigger**: Application shutdown + +**Location**: `{app-data}/backups/` + +**Format**: `timetracker-backup-YYYY-MM-DD-HH-mm-ss.db` + +**Retention**: User-managed (no automatic cleanup) + +### Manual Backups + +Users can manually copy the SQLite database file. + +--- + +## Future Architecture Considerations + +### Potential Enhancements + +1. **Plugin System**: Allow custom integrations +2. **Export/Import**: JSON, CSV formats +3. **Reporting Engine**: Advanced analytics +4. **Optional Sync**: Self-hosted sync server +5. **API**: REST API for integrations + +### Scalability + +Current architecture handles: +- Thousands of projects +- Tens of thousands of tasks +- Years of time entries + +For larger datasets, consider: +- Database indexing optimization +- Virtual scrolling for large lists +- Pagination for API responses + +--- + +# Arquitectura (Español) + +Este documento describe la arquitectura, patrones de diseño y decisiones técnicas en OpenTimeTracker. + +## Resumen del Sistema + +OpenTimeTracker es una **aplicación de escritorio** construida con tecnologías web modernas: + +``` +┌─────────────────────────────────────────────┐ +│ Aplicación Electron │ +├─────────────────────────────────────────────┤ +│ ┌────────────────┐ ┌─────────────────┐ │ +│ │ Renderer │◄──►│ Main Process │ │ +│ │ (Angular 21) │IPC │ (Node.js) │ │ +│ └────────────────┘ └─────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌────────────────┐ ┌─────────────────┐ │ +│ │ PrimeNG UI │ │ Cliente Prisma │ │ +│ └────────────────┘ └─────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────┐ │ +│ │ Base de Datos │ │ +│ │ SQLite │ │ +│ └─────────────────┘ │ +└─────────────────────────────────────────────┘ +``` + +## Capas de Arquitectura + +### 1. Capa de Presentación (Frontend Angular) + +**Tecnología**: Angular 21 con componentes standalone + +**Responsabilidades**: +- Renderizado de interfaz de usuario +- Manejo de interacciones del usuario +- Gestión de estado (servicios) +- Validación de formularios +- Internacionalización (i18n) + +**Componentes Clave**: +- `src/app/pages/*` - Componentes de página (destinos de enrutamiento) +- `src/app/components/*` - Componentes UI reutilizables +- `src/app/services/*` - Lógica de negocio y estado +- `src/app/interfaces/*` - Interfaces TypeScript + +**Framework UI**: PrimeNG + PrimeFlex +- Biblioteca de componentes: PrimeNG +- Clases de utilidad: PrimeFlex +- Tema por defecto: Aura Black (modo oscuro) + +### 2. Capa de Comunicación IPC + +**Tecnología**: Electron IPC (Comunicación Inter-Proceso) + +**Patrón**: Petición-Respuesta con seguridad de tipos + +El proceso renderer se comunica con el proceso main a través de un puente IPC seguro: + +```typescript +// Lado del Renderer (Angular) +window.electronAPI.database.createProject(projectData) + +// Script Preload (Puente) +contextBridge.exposeInMainWorld('electronAPI', { + database: { + createProject: (data) => ipcRenderer.invoke('db:createProject', data) + } +}) + +// Proceso Main (Electron) +ipcMain.handle('db:createProject', async (event, data) => { + return await prisma.project.create({ data }) +}) +``` + +**Seguridad**: +- Aislamiento de contexto habilitado +- Integración de Node deshabilitada en renderer +- Script preload como puente seguro + +### 3. Capa de Lógica de Negocio (Proceso Main de Electron) + +**Tecnología**: Node.js (Proceso Main de Electron) + +**Responsabilidades**: +- Operaciones de base de datos vía Prisma +- Operaciones del sistema de archivos +- Gestión del ciclo de vida de la aplicación +- Backups automáticos +- Gestión de ventanas + +**Archivos Clave**: +- `electron/src/main/main.ts` - Punto de entrada de la aplicación +- `electron/src/main/database.ts` - Operaciones de base de datos +- `electron/src/preload/preload.ts` - Puente IPC + +### 4. Capa de Datos (Prisma + SQLite) + +**Tecnología**: Prisma ORM + SQLite + +**Responsabilidades**: +- Persistencia de datos +- Gestión de esquema +- Migraciones +- Acceso a base de datos con seguridad de tipos + +**Ubicación de Base de Datos**: +- Desarrollo: `./dist/data/timetracker.db` +- Producción: + - Windows: `%APPDATA%/OpenTimeTracker/data/timetracker.db` + - macOS: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` + - Linux: `~/.config/OpenTimeTracker/data/timetracker.db` + +--- + +## Decisiones Técnicas Clave + +### ¿Por qué Electron? + +✅ **Pros**: +- Multiplataforma (Windows, macOS, Linux) +- Base de código única +- Integración nativa con el SO +- Acceso a APIs de Node.js +- Ecosistema grande + +**Conclusión**: Mejor opción para aplicación de escritorio local-first con tecnologías web. + +### ¿Por qué SQLite? + +✅ **Pros**: +- Basado en archivos (no necesita servidor) +- Rápido para operaciones locales +- Conforme con ACID +- Configuración cero +- Backups fáciles + +**Conclusión**: Perfecto para aplicación local-first enfocada en privacidad. + +### ¿Por qué Prisma? + +✅ **Pros**: +- Acceso a base de datos con seguridad de tipos +- Cliente auto-generado +- Sistema de migraciones +- Excelente DX (Experiencia del Desarrollador) +- Funciona bien con SQLite + +**Conclusión**: Mejor ORM para TypeScript + SQLite + Electron. + +--- + +Para más detalles técnicos, consulta las secciones anteriores en inglés. diff --git a/wiki/Database-Schema.md b/wiki/Database-Schema.md new file mode 100644 index 0000000..39a40f7 --- /dev/null +++ b/wiki/Database-Schema.md @@ -0,0 +1,651 @@ +# Database Schema Documentation + +This document provides detailed information about the OpenTimeTracker database schema, relationships, and data model. + +## Overview + +OpenTimeTracker uses **SQLite** as its database engine, managed through **Prisma ORM**. The schema is defined in `prisma/schema.prisma`. + +## Schema File Location + +- **Schema Definition**: `prisma/schema.prisma` +- **Migrations**: `prisma/migrations/` +- **Template Database**: `prisma/template.db` (used for new installations) + +## Database Location + +### Development +``` +./dist/data/timetracker.db +``` + +### Production +- **Windows**: `%APPDATA%/OpenTimeTracker/data/timetracker.db` +- **macOS**: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` +- **Linux**: `~/.config/OpenTimeTracker/data/timetracker.db` + +--- + +## Entity-Relationship Diagram + +``` +Project (1) ─── (N) Task (N) ─── (M) Tag + │ │ + │ ├── (1) TaskStatus + │ │ + │ └── (N) TimeEntry + │ + └─── (N) AuditLog ─── (N) Task + +WorkConfig (Singleton) ─── (Override) ─── MonthConfig + +DayType (1) ─── (N) DayOverride + +AppSettings (Singleton) + +ActionHistory (Independent) +``` + +--- + +## Core Entities + +### Project + +**Table**: `projects` + +Represents a project that groups related tasks. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `name` | String | Project name | Required | +| `description` | String? | Project description | Optional | +| `isClosed` | Boolean | Whether project is closed | Default: false | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | +| `updatedAt` | DateTime | Last update timestamp | Auto-updated | + +**Relationships**: +- `tasks` → Task[] (One-to-Many) +- `auditLogs` → AuditLog[] (One-to-Many) + +**Example**: +```json +{ + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "Website Redesign", + "description": "Complete redesign of company website", + "isClosed": false, + "createdAt": "2024-01-15T10:00:00Z", + "updatedAt": "2024-01-15T10:00:00Z" +} +``` + +--- + +### Task + +**Table**: `tasks` + +Represents a task within a project. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `projectId` | String | Foreign key to Project | Required, CASCADE | +| `name` | String | Task name | Required | +| `description` | String? | Task description | Optional | +| `estimatedHours` | Float? | Estimated time to complete | Optional | +| `statusId` | String? | Foreign key to TaskStatus | Optional | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | +| `updatedAt` | DateTime | Last update timestamp | Auto-updated | + +**Relationships**: +- `project` → Project (Many-to-One) +- `status` → TaskStatus (Many-to-One, optional) +- `tags` → TaskTag[] (One-to-Many) +- `timeEntries` → TimeEntry[] (One-to-Many) +- `auditLogs` → AuditLog[] (One-to-Many) + +**Delete Behavior**: +- When Project is deleted → CASCADE (task is deleted) +- When TaskStatus is deleted → SET NULL (status becomes null) + +--- + +### Tag + +**Table**: `tags` + +Reusable labels for categorizing tasks. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `name` | String | Tag name | Required, Unique | + +**Relationships**: +- `tasks` → TaskTag[] (One-to-Many) + +**Example**: +```json +{ + "id": "abc123...", + "name": "frontend" +} +``` + +--- + +### TaskTag (Join Table) + +**Table**: `task_tags` + +Many-to-many relationship between Tasks and Tags. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `taskId` | String | Foreign key to Task | Composite Primary Key | +| `tagId` | String | Foreign key to Tag | Composite Primary Key | + +**Relationships**: +- `task` → Task (Many-to-One, CASCADE) +- `tag` → Tag (Many-to-One, CASCADE) + +--- + +### TaskStatus + +**Table**: `task_status` + +Defines workflow states for tasks (e.g., "To Do", "In Progress", "Done"). + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `name` | String | Status name | Required, Unique | +| `color` | String | Hex color code | Default: "#6b7280" | +| `isDefault` | Boolean | Whether this is the default status | Default: false | + +**Relationships**: +- `tasks` → Task[] (One-to-Many) + +**Example**: +```json +{ + "id": "def456...", + "name": "In Progress", + "color": "#3b82f6", + "isDefault": false +} +``` + +--- + +### TimeEntry + +**Table**: `time_entries` + +Records time worked on tasks. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `taskId` | String? | Foreign key to Task | Optional, SET NULL | +| `date` | String | Date in YYYY-MM-DD format | Required | +| `minutes` | Int | Time worked in minutes | Required | +| `notes` | String? | Notes about the work | Optional | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | +| `updatedAt` | DateTime | Last update timestamp | Auto-updated | + +**Relationships**: +- `task` → Task (Many-to-One, optional, SET NULL on delete) + +**Note**: Time entries can exist without a task (unassigned time). + +**Example**: +```json +{ + "id": "ghi789...", + "taskId": "task-uuid", + "date": "2024-01-15", + "minutes": 120, + "notes": "Implemented user authentication", + "createdAt": "2024-01-15T14:30:00Z", + "updatedAt": "2024-01-15T14:30:00Z" +} +``` + +--- + +## Work Configuration + +### WorkConfig (Singleton) + +**Table**: `work_config` + +Global work configuration template. Only one record exists (id: "work_config"). + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | Fixed ID "work_config" | Primary Key | +| `dailyMinutes` | Int | Default daily work minutes | Default: 480 (8 hours) | +| `weeklyMinutes` | Int | Target weekly work minutes | Default: 2400 (40 hours) | +| `workDays` | String | CSV of work days (1=Mon, 7=Sun) | Default: "1,2,3,4,5" | +| `daySchedule` | String | JSON of per-day minutes | Default: Mon-Fri 480 min | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | +| `updatedAt` | DateTime | Last update timestamp | Auto-updated | + +**Example**: +```json +{ + "id": "work_config", + "dailyMinutes": 480, + "weeklyMinutes": 2400, + "workDays": "1,2,3,4,5", + "daySchedule": "{\"1\":480,\"2\":480,\"3\":480,\"4\":480,\"5\":480}", + "createdAt": "2024-01-01T00:00:00Z", + "updatedAt": "2024-01-15T12:00:00Z" +} +``` + +--- + +### MonthConfig + +**Table**: `month_configs` + +Month-specific overrides for work configuration. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `year` | Int | Year (e.g., 2024) | Unique with month | +| `month` | Int | Month (1-12) | Unique with year | +| `weeklyMinutes` | Int | Weekly target for this month | Default: 2400 | +| `workDays` | String | CSV of work days | Default: "1,2,3,4,5" | +| `daySchedule` | String | JSON of per-day minutes | Default: standard schedule | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | +| `updatedAt` | DateTime | Last update timestamp | Auto-updated | + +**Unique Constraint**: `(year, month)` + +**Example**: +```json +{ + "id": "jkl012...", + "year": 2024, + "month": 12, + "weeklyMinutes": 2000, + "workDays": "1,2,3,4", + "daySchedule": "{\"1\":500,\"2\":500,\"3\":500,\"4\":500}", + "createdAt": "2024-11-01T00:00:00Z", + "updatedAt": "2024-11-01T00:00:00Z" +} +``` + +--- + +## Special Days + +### DayType + +**Table**: `day_types` + +Types of special days (holidays, vacation, sick leave, etc.). + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `name` | String | Day type name | Required, Unique | +| `color` | String | Hex color code | Default: "#6b7280" | +| `defaultMinutes` | Int | Default work minutes for this type | Default: 0 | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | + +**Relationships**: +- `dayOverrides` → DayOverride[] (One-to-Many) + +**Example**: +```json +{ + "id": "mno345...", + "name": "Holiday", + "color": "#ef4444", + "defaultMinutes": 0, + "createdAt": "2024-01-01T00:00:00Z" +} +``` + +--- + +### DayOverride + +**Table**: `day_overrides` + +Overrides for specific dates. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `date` | String | Date in YYYY-MM-DD format | Required, Unique | +| `dayTypeId` | String? | Foreign key to DayType | Optional, SET NULL | +| `minutes` | Int? | Custom work minutes for this day | Optional | +| `note` | String? | Note about the day | Optional | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | +| `updatedAt` | DateTime | Last update timestamp | Auto-updated | + +**Relationships**: +- `dayType` → DayType (Many-to-One, optional, SET NULL on delete) + +**Example**: +```json +{ + "id": "pqr678...", + "date": "2024-12-25", + "dayTypeId": "holiday-id", + "minutes": 0, + "note": "Christmas Day", + "createdAt": "2024-01-01T00:00:00Z", + "updatedAt": "2024-01-01T00:00:00Z" +} +``` + +--- + +## Application Data + +### AppSettings (Singleton) + +**Table**: `app_settings` + +Application-wide settings. Only one record exists (id: "app_settings"). + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | Fixed ID "app_settings" | Primary Key | +| `darkMode` | Boolean | Dark mode enabled | Default: true | +| `language` | String | UI language ("en" or "es") | Default: "es" | +| `createdAt` | DateTime | Creation timestamp | Auto-generated | +| `updatedAt` | DateTime | Last update timestamp | Auto-updated | + +**Example**: +```json +{ + "id": "app_settings", + "darkMode": true, + "language": "es", + "createdAt": "2024-01-01T00:00:00Z", + "updatedAt": "2024-01-15T10:00:00Z" +} +``` + +--- + +## Audit & History + +### AuditLog + +**Table**: `audit_logs` + +Tracks changes to entities for audit purposes. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `entityType` | String | Type of entity (e.g., "Project") | Required | +| `entityId` | String | ID of the entity | Required | +| `action` | String | Action performed (e.g., "CREATE") | Required | +| `changes` | String? | JSON of changes made | Optional | +| `userName` | String? | User who made the change | Optional | +| `createdAt` | DateTime | When the action occurred | Auto-generated | +| `projectId` | String? | Related project ID | Optional, CASCADE | +| `taskId` | String? | Related task ID | Optional, CASCADE | + +**Relationships**: +- `project` → Project (Many-to-One, optional, CASCADE) +- `task` → Task (Many-to-One, optional, CASCADE) + +--- + +### ActionHistory + +**Table**: `action_history` + +Records actions for undo/redo functionality. + +| Field | Type | Description | Constraints | +|-------|------|-------------|-------------| +| `id` | String | UUID primary key | Primary Key | +| `entityType` | String | Type of entity | Required | +| `entityId` | String | ID of the entity | Required | +| `actionType` | String | Type of action | Required | +| `description` | String | Human-readable description | Required | +| `previousData` | String? | JSON of previous state | Optional | +| `newData` | String? | JSON of new state | Optional | +| `undone` | Boolean | Whether action has been undone | Default: false | +| `createdAt` | DateTime | When the action occurred | Auto-generated | + +**Example**: +```json +{ + "id": "stu901...", + "entityType": "Task", + "entityId": "task-uuid", + "actionType": "UPDATE", + "description": "Updated task status to 'Done'", + "previousData": "{\"statusId\":\"in-progress-id\"}", + "newData": "{\"statusId\":\"done-id\"}", + "undone": false, + "createdAt": "2024-01-15T15:30:00Z" +} +``` + +--- + +## Indexes + +The following indexes are automatically created by Prisma: + +- **Primary Keys**: All tables have UUID primary keys +- **Unique Constraints**: + - `tags.name` + - `task_status.name` + - `work_periods.{year, month}` + - `month_configs.{year, month}` + - `day_overrides.date` +- **Foreign Keys**: All relationships have FK indexes + +--- + +## Migrations + +### Creating a Migration + +When modifying the schema: + +```bash +npx prisma migrate dev --name description_of_change +``` + +This creates a new migration file in `prisma/migrations/`. + +### Applying Migrations + +Migrations are automatically applied when: +- Running `npm run dev` +- On first application start (production) + +### Migration Files + +Location: `prisma/migrations/TIMESTAMP_migration_name/` + +Each migration contains: +- `migration.sql` - SQL statements to apply + +--- + +## Database Operations + +### Common Queries + +**Create a Project**: +```typescript +await prisma.project.create({ + data: { + name: "New Project", + description: "Project description" + } +}) +``` + +**Get Projects with Tasks**: +```typescript +await prisma.project.findMany({ + include: { + tasks: { + include: { + status: true, + tags: { include: { tag: true } } + } + } + }, + where: { isClosed: false } +}) +``` + +**Create Time Entry**: +```typescript +await prisma.timeEntry.create({ + data: { + taskId: "task-uuid", + date: "2024-01-15", + minutes: 120, + notes: "Worked on feature X" + } +}) +``` + +**Get Time Entries for Date Range**: +```typescript +await prisma.timeEntry.findMany({ + where: { + date: { + gte: "2024-01-01", + lte: "2024-01-31" + } + }, + include: { task: true }, + orderBy: { date: 'desc' } +}) +``` + +--- + +## Backup & Restore + +### Automatic Backups + +- **Trigger**: Application shutdown +- **Location**: `{app-data}/backups/` +- **Format**: `timetracker-backup-YYYY-MM-DD-HH-mm-ss.db` +- **Method**: SQLite file copy + +### Manual Backup + +Simply copy the database file: + +```bash +# Linux/macOS +cp ~/.config/OpenTimeTracker/data/timetracker.db ~/my-backup.db + +# Windows +copy %APPDATA%\OpenTimeTracker\data\timetracker.db C:\my-backup.db +``` + +### Restore + +Replace the database file with a backup: + +1. Close OpenTimeTracker +2. Copy backup file to database location +3. Rename to `timetracker.db` +4. Restart OpenTimeTracker + +--- + +## Schema Evolution + +### Best Practices + +1. **Always create migrations** for schema changes +2. **Test migrations** on a copy of production data +3. **Update `prisma/template.db`** after migrations: + ```bash + npm run prisma:template + ``` +4. **Never commit real user data** to the repository + +### Breaking Changes + +When making breaking changes: + +1. Create a migration +2. Add data transformation logic if needed +3. Update Prisma client generation +4. Test thoroughly +5. Document in release notes + +--- + +## Performance Considerations + +### Query Optimization + +- Use `include` judiciously (only load needed relations) +- Use `select` to limit fields returned +- Add indexes for frequently queried fields + +### Data Volume + +SQLite performs well for: +- Thousands of projects +- Tens of thousands of tasks +- Hundreds of thousands of time entries + +For larger datasets, consider: +- Archiving old data +- Database vacuuming: `VACUUM;` +- Analyzing query performance + +--- + +## Troubleshooting + +### Database Locked + +**Cause**: Multiple processes accessing the database + +**Solution**: Ensure only one OpenTimeTracker instance is running + +### Corrupted Database + +**Cause**: Application crash, disk issues + +**Solution**: Restore from backup + +### Migration Failures + +**Cause**: Schema conflicts, data inconsistencies + +**Solution**: +1. Backup database +2. Reset migrations: `npx prisma migrate reset` +3. Restore data manually if needed + +--- + +## Related Documentation + +- [Prisma Schema Reference](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference) +- [SQLite Documentation](https://www.sqlite.org/docs.html) +- [Architecture Guide](Architecture.md) diff --git a/wiki/Getting-Started.md b/wiki/Getting-Started.md new file mode 100644 index 0000000..5ecce90 --- /dev/null +++ b/wiki/Getting-Started.md @@ -0,0 +1,417 @@ +# Getting Started with OpenTimeTracker + +This guide will help you install and start using OpenTimeTracker. + +## Installation + +### Download Pre-built Releases (Recommended) + +The easiest way to get started is to download a pre-built release for your platform: + +👉 **[Download from Releases](https://github.com/altaskur/OpenTimeTracker/releases)** + +#### Supported Platforms + +| Platform | File Type | Notes | +|----------|-----------|-------| +| **Windows** | `.exe` | NSIS installer for x64 | +| **macOS** | `.dmg` | Universal binary (Intel & Apple Silicon) | +| **Linux** | `.AppImage` | Portable, no installation required | +| **Linux** | `.deb` | Debian/Ubuntu package | + +#### Installation Steps + +**Windows:** +1. Download `OpenTimeTracker-{version}-win-x64.exe` +2. Run the installer +3. Follow the installation wizard +4. Launch OpenTimeTracker from Start Menu or Desktop + +**macOS:** +1. Download `OpenTimeTracker-{version}-mac-{arch}.dmg` +2. Open the DMG file +3. Drag OpenTimeTracker to Applications folder +4. Launch from Applications +5. If you see a security warning, go to System Preferences → Security & Privacy → Allow + +**Linux (AppImage):** +1. Download `OpenTimeTracker-{version}-linux-x64.AppImage` +2. Make it executable: `chmod +x OpenTimeTracker-*.AppImage` +3. Run: `./OpenTimeTracker-*.AppImage` + +**Linux (Debian/Ubuntu):** +1. Download `OpenTimeTracker-{version}-linux-x64.deb` +2. Install: `sudo dpkg -i OpenTimeTracker-*.deb` +3. Launch: `opentimetracker` or find it in your application menu + +--- + +### Run from Source (Advanced) + +If you want to run the latest development version or contribute to the project: + +#### Prerequisites + +- Node.js 20 or higher +- npm 10 or higher +- Git + +#### Steps + +```bash +# Clone the repository +git clone https://github.com/altaskur/OpenTimeTracker.git +cd OpenTimeTracker + +# Install dependencies +npm install + +# Generate Prisma client +npm run prisma:generate + +# Run in development mode +npm run dev +``` + +The application will build and launch in Electron. + +--- + +## First Launch + +### Initial Setup + +When you first launch OpenTimeTracker: + +1. **Language Selection**: Choose your preferred language (English or Spanish) +2. **Dark Mode**: The app uses dark theme by default (can be changed in settings) +3. **Database**: A local SQLite database is automatically created at: + - Windows: `%APPDATA%\OpenTimeTracker\data\timetracker.db` + - macOS: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` + - Linux: `~/.config/OpenTimeTracker/data/timetracker.db` + +### Creating Your First Project + +1. Click **"Projects"** in the sidebar +2. Click **"New Project"** button +3. Fill in the project details: + - **Name**: Enter a project name + - **Description**: Optional project description +4. Click **"Save"** + +### Creating Your First Task + +1. From the project view, click **"Add Task"** +2. Or navigate to **"Tasks"** and click **"New Task"** +3. Fill in task details: + - **Project**: Select the project + - **Task Name**: Enter a descriptive name + - **Description**: Optional details + - **Estimated Hours**: Optional time estimate + - **Status**: Choose from available statuses + - **Tags**: Add tags for categorization +4. Click **"Save"** + +### Tracking Time + +1. Navigate to **"Calendar"** view +2. Click on a date to add a time entry +3. Fill in: + - **Task**: Select the task (optional) + - **Time**: Enter hours and minutes + - **Notes**: Optional notes about what you worked on +4. Click **"Save"** + +--- + +## Quick Tour + +### Main Navigation + +The sidebar provides access to all main features: + +- **🏠 Home** - Dashboard with statistics and recent activity +- **📋 Projects** - Manage your projects +- **✅ Tasks** - View and manage all tasks +- **📅 Calendar** - Time tracking calendar view +- **📊 History** - View action history and audit logs +- **⚙️ Settings** - Configure app settings, statuses, tags, and day types + +### Key Features Overview + +#### Projects & Tasks +- Organize work into projects +- Create tasks within projects +- Track task status (To Do, In Progress, Done, etc.) +- Add tags for better organization +- Close projects when completed + +#### Time Tracking +- Calendar-based time entry +- Add time with notes +- View daily, weekly, and monthly summaries +- Track time with or without tasks + +#### Work Configuration +- Set daily/weekly work hours +- Configure work days +- Set different schedules per day +- Override specific months +- Define day types (holidays, vacation, etc.) + +#### Backup & Data +- Automatic backups on shutdown +- All data stored locally in SQLite +- Full control over your data +- No cloud sync or external dependencies + +--- + +## Basic Workflow + +Here's a typical workflow: + +1. **Create Projects** for your different work areas +2. **Add Tasks** to each project +3. **Track Time** in the calendar view +4. **Review Progress** in the Home dashboard +5. **Adjust Statuses** as tasks progress +6. **Close Projects** when completed + +--- + +## Tips for New Users + +- ⭐ Use **tags** to categorize tasks across projects +- 📊 Check the **Home** dashboard for quick stats +- 🎨 Customize **statuses** to match your workflow +- 📅 Use **day types** to mark holidays and special days +- 💾 Your data is backed up automatically on exit +- 🌙 Dark mode is enabled by default for comfort + +--- + +## Next Steps + +- Read the **[User Guide](User-Guide.md)** for detailed feature documentation +- Learn about **[Work Configuration](User-Guide.md#work-configuration)** to set up your schedule +- Explore **[Calendar Features](User-Guide.md#calendar-time-tracking)** for time tracking +- Check **[Settings](User-Guide.md#settings)** for customization options + +--- + +## Need Help? + +- Check the **[FAQ](FAQ.md)** for common questions +- Visit **[Troubleshooting](Troubleshooting.md)** if you encounter issues +- Open an issue on [GitHub](https://github.com/altaskur/OpenTimeTracker/issues) + +--- + +# Guía de Inicio (Español) + +Esta guía te ayudará a instalar y comenzar a usar OpenTimeTracker. + +## Instalación + +### Descargar Versiones Pre-compiladas (Recomendado) + +La forma más fácil de comenzar es descargar una versión pre-compilada para tu plataforma: + +👉 **[Descargar desde Releases](https://github.com/altaskur/OpenTimeTracker/releases)** + +#### Plataformas Soportadas + +| Plataforma | Tipo de Archivo | Notas | +|------------|-----------------|-------| +| **Windows** | `.exe` | Instalador NSIS para x64 | +| **macOS** | `.dmg` | Binario universal (Intel y Apple Silicon) | +| **Linux** | `.AppImage` | Portable, no requiere instalación | +| **Linux** | `.deb` | Paquete Debian/Ubuntu | + +#### Pasos de Instalación + +**Windows:** +1. Descarga `OpenTimeTracker-{version}-win-x64.exe` +2. Ejecuta el instalador +3. Sigue el asistente de instalación +4. Inicia OpenTimeTracker desde el Menú Inicio o Escritorio + +**macOS:** +1. Descarga `OpenTimeTracker-{version}-mac-{arch}.dmg` +2. Abre el archivo DMG +3. Arrastra OpenTimeTracker a la carpeta Aplicaciones +4. Inicia desde Aplicaciones +5. Si ves una advertencia de seguridad, ve a Preferencias del Sistema → Seguridad y Privacidad → Permitir + +**Linux (AppImage):** +1. Descarga `OpenTimeTracker-{version}-linux-x64.AppImage` +2. Hazlo ejecutable: `chmod +x OpenTimeTracker-*.AppImage` +3. Ejecuta: `./OpenTimeTracker-*.AppImage` + +**Linux (Debian/Ubuntu):** +1. Descarga `OpenTimeTracker-{version}-linux-x64.deb` +2. Instala: `sudo dpkg -i OpenTimeTracker-*.deb` +3. Inicia: `opentimetracker` o búscalo en tu menú de aplicaciones + +--- + +### Ejecutar desde Código Fuente (Avanzado) + +Si deseas ejecutar la última versión de desarrollo o contribuir al proyecto: + +#### Requisitos Previos + +- Node.js 20 o superior +- npm 10 o superior +- Git + +#### Pasos + +```bash +# Clonar el repositorio +git clone https://github.com/altaskur/OpenTimeTracker.git +cd OpenTimeTracker + +# Instalar dependencias +npm install + +# Generar cliente Prisma +npm run prisma:generate + +# Ejecutar en modo desarrollo +npm run dev +``` + +La aplicación se compilará e iniciará en Electron. + +--- + +## Primer Inicio + +### Configuración Inicial + +Cuando inicies OpenTimeTracker por primera vez: + +1. **Selección de Idioma**: Elige tu idioma preferido (Inglés o Español) +2. **Modo Oscuro**: La aplicación usa tema oscuro por defecto (se puede cambiar en configuración) +3. **Base de Datos**: Se crea automáticamente una base de datos SQLite local en: + - Windows: `%APPDATA%\OpenTimeTracker\data\timetracker.db` + - macOS: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` + - Linux: `~/.config/OpenTimeTracker/data/timetracker.db` + +### Crear tu Primer Proyecto + +1. Haz clic en **"Proyectos"** en la barra lateral +2. Haz clic en el botón **"Nuevo Proyecto"** +3. Completa los detalles del proyecto: + - **Nombre**: Ingresa un nombre para el proyecto + - **Descripción**: Descripción opcional del proyecto +4. Haz clic en **"Guardar"** + +### Crear tu Primera Tarea + +1. Desde la vista de proyecto, haz clic en **"Agregar Tarea"** +2. O navega a **"Tareas"** y haz clic en **"Nueva Tarea"** +3. Completa los detalles de la tarea: + - **Proyecto**: Selecciona el proyecto + - **Nombre de Tarea**: Ingresa un nombre descriptivo + - **Descripción**: Detalles opcionales + - **Horas Estimadas**: Estimación de tiempo opcional + - **Estado**: Elige entre los estados disponibles + - **Etiquetas**: Agrega etiquetas para categorización +4. Haz clic en **"Guardar"** + +### Rastrear Tiempo + +1. Navega a la vista de **"Calendario"** +2. Haz clic en una fecha para agregar una entrada de tiempo +3. Completa: + - **Tarea**: Selecciona la tarea (opcional) + - **Tiempo**: Ingresa horas y minutos + - **Notas**: Notas opcionales sobre en qué trabajaste +4. Haz clic en **"Guardar"** + +--- + +## Recorrido Rápido + +### Navegación Principal + +La barra lateral proporciona acceso a todas las funciones principales: + +- **🏠 Inicio** - Panel con estadísticas y actividad reciente +- **📋 Proyectos** - Gestiona tus proyectos +- **✅ Tareas** - Ver y gestionar todas las tareas +- **📅 Calendario** - Vista de calendario para rastreo de tiempo +- **📊 Historial** - Ver historial de acciones y registros de auditoría +- **⚙️ Configuración** - Configurar ajustes de la app, estados, etiquetas y tipos de día + +### Resumen de Funciones Clave + +#### Proyectos y Tareas +- Organiza el trabajo en proyectos +- Crea tareas dentro de proyectos +- Rastrea el estado de tareas (Por Hacer, En Progreso, Hecho, etc.) +- Agrega etiquetas para mejor organización +- Cierra proyectos cuando se completen + +#### Rastreo de Tiempo +- Entrada de tiempo basada en calendario +- Agrega tiempo con notas +- Ver resúmenes diarios, semanales y mensuales +- Rastrea tiempo con o sin tareas + +#### Configuración de Trabajo +- Establece horas de trabajo diarias/semanales +- Configura días laborables +- Establece diferentes horarios por día +- Anula meses específicos +- Define tipos de día (vacaciones, días festivos, etc.) + +#### Backup y Datos +- Backups automáticos al cerrar +- Todos los datos almacenados localmente en SQLite +- Control total sobre tus datos +- Sin sincronización en la nube o dependencias externas + +--- + +## Flujo de Trabajo Básico + +Aquí hay un flujo de trabajo típico: + +1. **Crear Proyectos** para tus diferentes áreas de trabajo +2. **Agregar Tareas** a cada proyecto +3. **Rastrear Tiempo** en la vista de calendario +4. **Revisar Progreso** en el panel de Inicio +5. **Ajustar Estados** a medida que las tareas progresan +6. **Cerrar Proyectos** cuando se completen + +--- + +## Consejos para Nuevos Usuarios + +- ⭐ Usa **etiquetas** para categorizar tareas entre proyectos +- 📊 Revisa el panel de **Inicio** para estadísticas rápidas +- 🎨 Personaliza **estados** para que coincidan con tu flujo de trabajo +- 📅 Usa **tipos de día** para marcar vacaciones y días especiales +- 💾 Tus datos se respaldan automáticamente al salir +- 🌙 El modo oscuro está habilitado por defecto para comodidad + +--- + +## Próximos Pasos + +- Lee la **[Guía de Usuario](User-Guide.md#guía-de-usuario-español)** para documentación detallada de características +- Aprende sobre **[Configuración de Trabajo](User-Guide.md#configuración-de-trabajo-español)** para configurar tu horario +- Explora **[Funciones de Calendario](User-Guide.md#calendario-español)** para rastreo de tiempo +- Revisa **[Configuración](User-Guide.md#configuración-español)** para opciones de personalización + +--- + +## ¿Necesitas Ayuda? + +- Revisa las **[Preguntas Frecuentes](FAQ.md#preguntas-frecuentes-español)** para preguntas comunes +- Visita **[Solución de Problemas](Troubleshooting.md#solución-de-problemas-español)** si encuentras problemas +- Abre un issue en [GitHub](https://github.com/altaskur/OpenTimeTracker/issues) diff --git a/wiki/Home.md b/wiki/Home.md new file mode 100644 index 0000000..9cf29e4 --- /dev/null +++ b/wiki/Home.md @@ -0,0 +1,147 @@ +# OpenTimeTracker Wiki + +

+ OpenTimeTracker Logo +

+ +Welcome to the official OpenTimeTracker wiki! This documentation provides comprehensive information about the project, from getting started to advanced development topics. + +## 🌐 Language / Idioma + +- **English**: Continue reading below +- **Español**: [Ver en español](#bienvenido-a-opentimetracker-español) + +--- + +## About OpenTimeTracker + +OpenTimeTracker is a **free, open-source, local-first time tracking application** designed for developers and small teams who want: + +- ✅ Full control over their data +- ✅ No SaaS subscriptions or cloud dependencies +- ✅ Fast, offline-first experience +- ✅ Privacy-focused with local SQLite storage + +### Key Technologies + +- **Frontend**: Angular 21 +- **Desktop**: Electron 37 +- **Database**: Prisma + SQLite +- **UI Framework**: PrimeNG + PrimeFlex +- **License**: GPL-3.0 + +--- + +## 📚 Documentation Structure + +### For Users + +- **[Getting Started](Getting-Started.md)** - Installation and first steps +- **[User Guide](User-Guide.md)** - Complete feature guide and usage +- **[Troubleshooting](Troubleshooting.md)** - Common issues and solutions +- **[FAQ](FAQ.md)** - Frequently asked questions + +### For Developers + +- **[Development Setup](Development-Setup.md)** - Setting up your development environment +- **[Architecture](Architecture.md)** - Technical design and system architecture +- **[Database Schema](Database-Schema.md)** - Data model and relationships +- **[API Documentation](API-Documentation.md)** - IPC API and service interfaces +- **[Contributing Guide](Contributing.md)** - How to contribute to the project +- **[Build & Deployment](Build-and-Deployment.md)** - Building and packaging + +### Project Information + +- **[Roadmap](Roadmap.md)** - Future plans and feature requests +- **[Release Notes](Release-Notes.md)** - Version history and changes +- **[Security](Security.md)** - Security policy and best practices + +--- + +## 🚀 Quick Links + +- 📦 [Latest Release](https://github.com/altaskur/OpenTimeTracker/releases) +- 🐛 [Report Bug](https://github.com/altaskur/OpenTimeTracker/issues/new) +- 💡 [Request Feature](https://github.com/altaskur/OpenTimeTracker/issues/new) +- 💬 [Discussions](https://github.com/altaskur/OpenTimeTracker/discussions) + +--- + +## Project Status + +⚠️ **Alpha Stage** - OpenTimeTracker is under active development. Features, UI, and internal APIs may change. + +We welcome feedback, bug reports, and contributions! + +--- + +## 🤝 Community + +- **Repository**: [github.com/altaskur/OpenTimeTracker](https://github.com/altaskur/OpenTimeTracker) +- **Author**: [@altaskur](https://github.com/altaskur) +- **License**: GNU General Public License v3.0 + +--- + +# Bienvenido a OpenTimeTracker (Español) + +Bienvenido a la wiki oficial de OpenTimeTracker. Esta documentación proporciona información completa sobre el proyecto, desde cómo empezar hasta temas avanzados de desarrollo. + +## Sobre OpenTimeTracker + +OpenTimeTracker es una **aplicación de seguimiento de tiempo gratuita, de código abierto y local-first** diseñada para desarrolladores y equipos pequeños que desean: + +- ✅ Control total sobre sus datos +- ✅ Sin suscripciones SaaS ni dependencias de la nube +- ✅ Experiencia rápida y offline-first +- ✅ Enfocado en privacidad con almacenamiento SQLite local + +### Tecnologías Clave + +- **Frontend**: Angular 21 +- **Escritorio**: Electron 37 +- **Base de datos**: Prisma + SQLite +- **Framework UI**: PrimeNG + PrimeFlex +- **Licencia**: GPL-3.0 + +--- + +## 📚 Estructura de Documentación + +### Para Usuarios + +- **[Comenzar](Getting-Started.md#guía-de-inicio-español)** - Instalación y primeros pasos +- **[Guía de Usuario](User-Guide.md#guía-de-usuario-español)** - Guía completa de características +- **[Solución de Problemas](Troubleshooting.md#solución-de-problemas-español)** - Problemas comunes y soluciones +- **[Preguntas Frecuentes](FAQ.md#preguntas-frecuentes-español)** - FAQ en español + +### Para Desarrolladores + +- **[Configuración de Desarrollo](Development-Setup.md#configuración-de-desarrollo-español)** - Configurar entorno de desarrollo +- **[Arquitectura](Architecture.md#arquitectura-español)** - Diseño técnico y arquitectura del sistema +- **[Esquema de Base de Datos](Database-Schema.md)** - Modelo de datos y relaciones +- **[Documentación de API](API-Documentation.md)** - API IPC e interfaces de servicio +- **[Guía de Contribución](Contributing.md)** - Cómo contribuir al proyecto +- **[Compilación y Despliegue](Build-and-Deployment.md#compilación-y-despliegue-español)** - Compilar y empaquetar + +### Información del Proyecto + +- **[Hoja de Ruta](Roadmap.md)** - Planes futuros y solicitudes de características +- **[Notas de Versión](Release-Notes.md)** - Historial de versiones y cambios +- **[Seguridad](Security.md)** - Política de seguridad y mejores prácticas + +--- + +## Estado del Proyecto + +⚠️ **Fase Alfa** - OpenTimeTracker está en desarrollo activo. Las características, la UI y las APIs internas pueden cambiar. + +¡Agradecemos comentarios, reportes de errores y contribuciones! + +--- + +## 🤝 Comunidad + +- **Repositorio**: [github.com/altaskur/OpenTimeTracker](https://github.com/altaskur/OpenTimeTracker) +- **Autor**: [@altaskur](https://github.com/altaskur) +- **Licencia**: GNU General Public License v3.0 From 7dc36b782ca6b20892dfaacad5f94d49ba4e4a05 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 16:59:23 +0000 Subject: [PATCH 3/6] docs: add Development Setup, Build and Deployment, and Troubleshooting wiki pages Co-authored-by: altaskur <105789412+altaskur@users.noreply.github.com> --- wiki/Build-and-Deployment.md | 630 ++++++++++++++++++++++++++++ wiki/Development-Setup.md | 766 +++++++++++++++++++++++++++++++++++ wiki/Troubleshooting.md | 693 +++++++++++++++++++++++++++++++ 3 files changed, 2089 insertions(+) create mode 100644 wiki/Build-and-Deployment.md create mode 100644 wiki/Development-Setup.md create mode 100644 wiki/Troubleshooting.md diff --git a/wiki/Build-and-Deployment.md b/wiki/Build-and-Deployment.md new file mode 100644 index 0000000..9fd5436 --- /dev/null +++ b/wiki/Build-and-Deployment.md @@ -0,0 +1,630 @@ +# Build and Deployment Guide + +This guide covers building, packaging, and deploying OpenTimeTracker for production. + +## Build Process Overview + +OpenTimeTracker uses a multi-stage build process: + +1. **Angular Build**: Compiles Angular app to optimized JavaScript +2. **Electron TypeScript Compilation**: Compiles main and preload processes +3. **Electron Builder**: Packages application with Electron for each platform + +--- + +## Production Build + +### Full Production Build + +```bash +npm run build +``` + +**What it does**: +1. Runs `ng build` (production configuration) + - Optimized bundles + - Tree shaking + - Minification + - AOT compilation +2. Compiles Electron main process: `tsc --project electron/build/tsconfig.json` +3. Compiles Electron preload: `tsc --project electron/build/tsconfig.preload.json` + +**Output**: +- Angular app: `dist/browser/` +- Electron main: `dist/electron/main/` +- Electron preload: `dist/electron/preload/` + +--- + +## Packaging + +### Package for All Platforms + +```bash +npm run dist +``` + +Builds and packages for: +- Windows (x64) +- macOS (Intel & Apple Silicon) +- Linux (x64) + +**Output directory**: `release/` + +### Platform-Specific Packaging + +**Windows**: +```bash +npm run dist:win +``` + +**macOS**: +```bash +npm run dist:mac +``` + +**Linux**: +```bash +npm run dist:linux +``` + +### Unpacked Distribution + +```bash +npm run pack +``` + +Creates an unpacked distribution (useful for testing without installing). + +--- + +## Build Configuration + +### Electron Builder Config + +Located in `package.json` → `build` section: + +```json +{ + "build": { + "appId": "com.altaskur.opentimetracker", + "productName": "OpenTimeTracker", + "icon": "public/icon.png", + "directories": { + "output": "release" + }, + "files": [ + "dist/**/*", + "node_modules/@prisma/client/**/*", + "node_modules/@prisma/adapter-better-sqlite3/**/*", + "node_modules/better-sqlite3/**/*", + "prisma/template.db", + "prisma/schema.prisma" + ], + "asarUnpack": [ + "node_modules/.prisma/**/*", + "node_modules/@prisma/client/**/*", + "node_modules/@prisma/adapter-better-sqlite3/**/*", + "node_modules/better-sqlite3/**/*", + "dist/electron/generated/**/*", + "prisma/template.db" + ] + } +} +``` + +**Key settings**: +- `appId`: Unique application identifier +- `productName`: Display name +- `files`: Files to include in the package +- `asarUnpack`: Files excluded from ASAR archive (needed for native modules) + +--- + +## Platform-Specific Builds + +### Windows + +**Configuration**: +```json +{ + "win": { + "target": [{ + "target": "nsis", + "arch": ["x64"] + }] + }, + "nsis": { + "oneClick": false, + "allowToChangeInstallationDirectory": true, + "perMachine": true, + "createDesktopShortcut": true, + "createStartMenuShortcut": true, + "shortcutName": "OpenTimeTracker", + "license": "LICENSE" + } +} +``` + +**Output**: +- `OpenTimeTracker-{version}-win-x64.exe` - NSIS installer + +**Build on**: +- Windows (native) +- Linux/macOS with Wine (not recommended) + +**Installer features**: +- Custom installation directory +- Desktop shortcut +- Start menu entry +- Uninstaller + +--- + +### macOS + +**Configuration**: +```json +{ + "mac": { + "target": [{ + "target": "dmg", + "arch": ["x64", "arm64"] + }], + "icon": "public/icon-512.png", + "category": "public.app-category.productivity" + }, + "dmg": { + "title": "${productName} ${version}", + "contents": [ + { "x": 130, "y": 220 }, + { "x": 410, "y": 220, "type": "link", "path": "/Applications" } + ] + } +} +``` + +**Output**: +- `OpenTimeTracker-{version}-mac-x64.dmg` - Intel +- `OpenTimeTracker-{version}-mac-arm64.dmg` - Apple Silicon + +**Build on**: +- macOS (native) - **Required for signing** +- Linux with [electron-builder Docker image](https://www.electron.build/multi-platform-build#docker) + +**DMG features**: +- Drag-to-Applications folder +- Custom background (can be added) +- Retina-ready + +--- + +### Linux + +**Configuration**: +```json +{ + "linux": { + "target": [ + { "target": "AppImage", "arch": ["x64"] }, + { "target": "deb", "arch": ["x64"] } + ], + "icon": "public/icon.png", + "category": "Office", + "maintainer": "altaskur", + "synopsis": "Time tracking application", + "description": "Free and open source time tracking application" + } +} +``` + +**Output**: +- `OpenTimeTracker-{version}-linux-x64.AppImage` - Portable +- `OpenTimeTracker-{version}-linux-x64.deb` - Debian/Ubuntu package + +**Build on**: +- Linux (native) +- macOS/Windows with Docker + +**AppImage features**: +- No installation required +- Portable +- Desktop integration + +**Deb package features**: +- System integration +- apt package manager support +- Menu entries + +--- + +## Code Signing + +### Why Sign Your Code? + +- **Windows**: Avoids SmartScreen warnings +- **macOS**: Required for Gatekeeper +- **Linux**: Not required + +### Windows Code Signing + +**Requirements**: +- Code signing certificate (.pfx or .p12) +- Certificate password + +**Configuration**: + +1. **Store certificate** securely +2. **Set environment variables**: + ```bash + # Windows + set CSC_LINK=C:\path\to\certificate.pfx + set CSC_KEY_PASSWORD=your_password + + # Linux/macOS + export CSC_LINK=/path/to/certificate.pfx + export CSC_KEY_PASSWORD=your_password + ``` + +3. **Build**: + ```bash + npm run dist:win + ``` + +Electron Builder will automatically sign the executable. + +--- + +### macOS Code Signing & Notarization + +**Requirements**: +- Apple Developer Account ($99/year) +- Developer ID Application certificate +- App-specific password + +**Steps**: + +1. **Install certificate** in Keychain + +2. **Set environment variables**: + ```bash + export APPLE_ID=your@email.com + export APPLE_ID_PASSWORD=app-specific-password + export APPLE_TEAM_ID=your-team-id + ``` + +3. **Add to electron-builder config**: + ```json + { + "mac": { + "hardenedRuntime": true, + "gatekeeperAssess": false, + "entitlements": "build/entitlements.mac.plist", + "entitlementsInherit": "build/entitlements.mac.plist" + }, + "afterSign": "scripts/notarize.js" + } + ``` + +4. **Build**: + ```bash + npm run dist:mac + ``` + +--- + +## CI/CD Integration + +### GitHub Actions + +Create `.github/workflows/build.yml`: + +```yaml +name: Build + +on: + push: + branches: [main] + tags: ['v*'] + pull_request: + +jobs: + build: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [windows-latest, macos-latest, ubuntu-latest] + + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: 20 + + - name: Install dependencies + run: npm ci + + - name: Generate Prisma client + run: npm run prisma:generate + + - name: Build + run: npm run build + + - name: Package + run: npm run dist + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Upload artifacts + uses: actions/upload-artifact@v3 + with: + name: ${{ matrix.os }}-build + path: release/* +``` + +### Release Workflow + +```yaml +name: Release + +on: + push: + tags: ['v*'] + +jobs: + release: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [windows-latest, macos-latest, ubuntu-latest] + + steps: + # ... (same as build workflow) ... + + - name: Release + uses: softprops/action-gh-release@v1 + with: + files: release/* + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +--- + +## Release Process + +### 1. Prepare Release + +1. **Update version** in `package.json`: + ```json + { + "version": "1.0.0" + } + ``` + +2. **Update CHANGELOG** (if exists) + +3. **Run tests**: + ```bash + npm test + npm run test:electron + npm run lint + ``` + +4. **Build locally**: + ```bash + npm run dist + ``` + +5. **Test the build** on target platforms + +### 2. Create Git Tag + +```bash +git tag -a v1.0.0 -m "Release version 1.0.0" +git push origin v1.0.0 +``` + +### 3. Create GitHub Release + +1. Go to GitHub Releases +2. Click "Create a new release" +3. Select the tag +4. Add release notes +5. Upload build artifacts from `release/` +6. Publish release + +--- + +## Build Optimization + +### Reduce Bundle Size + +1. **Enable tree shaking** (enabled by default in production) +2. **Analyze bundle**: + ```bash + ng build --stats-json + npx webpack-bundle-analyzer dist/browser/stats.json + ``` +3. **Lazy load modules** where possible +4. **Remove unused dependencies** + +### Improve Build Speed + +1. **Use incremental builds** in development +2. **Enable caching** in CI/CD +3. **Use multi-stage Docker builds** for CI +4. **Parallelize builds** across platforms + +--- + +## Troubleshooting + +### Build Failures + +**Issue**: Native module compilation fails + +**Solution**: +```bash +npx electron-rebuild +``` + +--- + +**Issue**: Prisma client not found in production build + +**Solution**: Ensure `asarUnpack` includes Prisma files + +--- + +**Issue**: Application won't start after packaging + +**Solutions**: +1. Check DevTools console for errors +2. Verify all dependencies are included +3. Test with unpacked build: `npm run pack` + +--- + +### Platform-Specific Issues + +**Windows**: SmartScreen warning + +**Solution**: Code sign your application + +--- + +**macOS**: "App is damaged" error + +**Solution**: Sign and notarize your application + +--- + +**Linux**: AppImage won't run + +**Solution**: Make it executable: `chmod +x *.AppImage` + +--- + +## Distribution + +### GitHub Releases + +**Pros**: +- Free +- Integrated with repository +- Version management + +**Usage**: +1. Create release with tag +2. Upload build artifacts +3. Users download from releases page + +### Auto-Update + +To implement auto-updates with `electron-updater`: + +1. **Install dependency**: + ```bash + npm install electron-updater + ``` + +2. **Configure** in `main.ts`: + ```typescript + import { autoUpdater } from 'electron-updater'; + + autoUpdater.checkForUpdatesAndNotify(); + ``` + +3. **Publish updates** to GitHub Releases + +4. **Users get notified** of new versions + +--- + +## Best Practices + +1. **Version consistently**: Use semantic versioning (SemVer) +2. **Test before release**: Test on all target platforms +3. **Sign your code**: Prevents security warnings +4. **Provide changelogs**: Help users understand updates +5. **Use CI/CD**: Automate builds and releases +6. **Monitor bundle size**: Keep downloads manageable +7. **Back up signing certificates**: Critical for updates + +--- + +## Related Documentation + +- [Electron Builder Documentation](https://www.electron.build/) +- [Semantic Versioning](https://semver.org/) +- [Development Setup](Development-Setup.md) +- [Architecture](Architecture.md) + +--- + +# Compilación y Despliegue (Español) + +Esta guía cubre la compilación, empaquetado y despliegue de OpenTimeTracker para producción. + +## Compilación de Producción + +### Compilación Completa + +```bash +npm run build +``` + +**Qué hace**: +1. Ejecuta `ng build` (configuración de producción) +2. Compila proceso main de Electron +3. Compila preload de Electron + +**Salida**: `dist/` + +--- + +## Empaquetado + +### Empaquetar para Todas las Plataformas + +```bash +npm run dist +``` + +**Salida**: `release/` + +### Empaquetado Específico por Plataforma + +**Windows**: +```bash +npm run dist:win +``` + +**macOS**: +```bash +npm run dist:mac +``` + +**Linux**: +```bash +npm run dist:linux +``` + +--- + +## Proceso de Liberación + +1. **Actualizar versión** en `package.json` +2. **Ejecutar pruebas**: `npm test` +3. **Compilar**: `npm run dist` +4. **Probar** en plataformas objetivo +5. **Crear tag de Git**: `git tag -a v1.0.0 -m "Release 1.0.0"` +6. **Push tag**: `git push origin v1.0.0` +7. **Crear release en GitHub** y subir archivos + +--- + +Para más detalles, consulta las secciones anteriores en inglés. diff --git a/wiki/Development-Setup.md b/wiki/Development-Setup.md new file mode 100644 index 0000000..842dd0c --- /dev/null +++ b/wiki/Development-Setup.md @@ -0,0 +1,766 @@ +# Development Setup + +This guide will help you set up your development environment for contributing to OpenTimeTracker. + +## Prerequisites + +Before you begin, ensure you have the following installed: + +### Required + +- **Node.js**: Version 20 or higher + - Download from [nodejs.org](https://nodejs.org/) + - Verify: `node --version` +- **npm**: Version 10 or higher (comes with Node.js) + - Verify: `npm --version` +- **Git**: For version control + - Download from [git-scm.com](https://git-scm.com/) + - Verify: `git --version` + +### Recommended + +- **Docker & Docker Compose**: For SonarQube analysis + - Download from [docker.com](https://www.docker.com/) + - Verify: `docker --version` and `docker-compose --version` +- **VS Code**: Recommended IDE with extensions: + - Angular Language Service + - Prettier - Code formatter + - ESLint + - Prisma + +--- + +## Initial Setup + +### 1. Fork and Clone + +1. **Fork the repository** on GitHub + - Go to https://github.com/altaskur/OpenTimeTracker + - Click "Fork" button + +2. **Clone your fork**: + ```bash + git clone https://github.com/YOUR_USERNAME/OpenTimeTracker.git + cd OpenTimeTracker + ``` + +3. **Add upstream remote**: + ```bash + git remote add upstream https://github.com/altaskur/OpenTimeTracker.git + git remote -v + ``` + +### 2. Install Dependencies + +```bash +npm install +``` + +This will: +- Install all npm dependencies +- Set up Git hooks via Husky +- Run `electron-rebuild` for native modules + +### 3. Generate Prisma Client + +```bash +npm run prisma:generate +``` + +This generates the Prisma client in `electron/src/generated/prisma/`. + +### 4. Verify Setup + +Test that everything works: + +```bash +npm run dev +``` + +This should: +1. Build the Angular application +2. Compile Electron TypeScript files +3. Launch the application in Electron + +--- + +## Development Workflow + +### Branch Strategy + +The project uses the following branches: + +- **`main`**: Production-ready code +- **`develop`**: Integration branch for features +- **Feature branches**: `feat/your-feature-name` +- **Bug fix branches**: `fix/bug-description` +- **Chore branches**: `chore/task-description` + +### Creating a Feature Branch + +Always branch from `develop`: + +```bash +# Make sure develop is up to date +git checkout develop +git pull upstream develop + +# Create your feature branch +git checkout -b feat/your-feature-name +``` + +### Making Changes + +1. **Make your changes** in your feature branch +2. **Test locally** (see Testing section) +3. **Commit with conventional commits** (see below) +4. **Push to your fork** +5. **Create a Pull Request** to `develop` + +--- + +## Running the Application + +### Development Mode (Recommended) + +```bash +npm run dev +``` + +**What it does**: +1. Builds Angular in development mode (`ng build --configuration=development`) +2. Compiles Electron main process TypeScript +3. Compiles Electron preload TypeScript +4. Launches Electron with the built application + +**Features**: +- Fast builds +- Source maps enabled +- Development-optimized bundles + +### Angular Dev Server Only + +```bash +npm start +# or +ng serve +``` + +Runs Angular on `http://localhost:4200` (without Electron). + +**When to use**: +- Quick UI development and testing +- Component development +- Style adjustments + +**Note**: Database operations won't work without Electron. + +### Production Build + +```bash +npm run build +``` + +Builds for production (optimized bundles, no source maps). + +### Electron Only (After Build) + +```bash +npm run electron +``` + +Launches Electron with previously built files. + +--- + +## Project Structure + +``` +OpenTimeTracker/ +├── .github/ # GitHub workflows and config +├── .husky/ # Git hooks +├── .vscode/ # VS Code settings +├── electron/ # Electron main process +│ ├── build/ # TypeScript configs for Electron +│ └── src/ +│ ├── main/ # Main process code +│ │ ├── main.ts # Entry point +│ │ └── database.ts +│ └── preload/ # Preload scripts +│ └── preload.ts # IPC bridge +├── prisma/ # Database schema and migrations +│ ├── migrations/ # Database migrations +│ ├── schema.prisma # Prisma schema definition +│ └── template.db # Template database for new installs +├── public/ # Static assets +├── scripts/ # Build and utility scripts +├── src/ # Angular application +│ ├── app/ +│ │ ├── components/ # Shared components +│ │ ├── interfaces/ # TypeScript interfaces +│ │ ├── pages/ # Page components (routes) +│ │ ├── services/ # Angular services +│ │ └── utils/ # Utility functions +│ ├── assets/ +│ │ └── i18n/ # Translation files +│ │ ├── en.json +│ │ └── es.json +│ ├── index.html # HTML entry point +│ ├── main.ts # Angular bootstrap +│ └── styles.scss # Global styles +├── wiki/ # Project wiki (documentation) +├── angular.json # Angular configuration +├── package.json # Dependencies and scripts +├── tsconfig.json # TypeScript configuration +└── vitest.config.ts # Vitest test configuration +``` + +--- + +## Development Commands + +### Building + +| Command | Description | +|---------|-------------| +| `npm run dev` | Build and run in development mode | +| `npm run build` | Production build (Angular + Electron) | +| `npm start` | Start Angular dev server only | + +### Testing + +| Command | Description | +|---------|-------------| +| `npm test` | Run Angular tests (Karma + Jasmine) | +| `npm run test:coverage` | Run tests with coverage report | +| `npm run test:electron` | Run Electron tests (Vitest) | +| `npm run test:electron:watch` | Run Electron tests in watch mode | +| `npm run test:electron:coverage` | Electron tests with coverage | + +### Linting & Formatting + +| Command | Description | +|---------|-------------| +| `npm run lint` | Run ESLint | +| `npm run lint:fix` | Run ESLint with auto-fix | +| `prettier --write .` | Format all files with Prettier | + +### Database + +| Command | Description | +|---------|-------------| +| `npm run prisma:generate` | Generate Prisma client | +| `npm run prisma:push` | Push schema changes to database | +| `npm run prisma:studio` | Open Prisma Studio (database GUI) | +| `npm run prisma:migrate` | Create and apply migration | +| `npm run prisma:template` | Update template.db | + +### Packaging + +| Command | Description | +|---------|-------------| +| `npm run dist` | Build and package for all platforms | +| `npm run dist:win` | Package for Windows | +| `npm run dist:mac` | Package for macOS | +| `npm run dist:linux` | Package for Linux | +| `npm run pack` | Create unpacked distribution | + +### Quality Analysis + +| Command | Description | +|---------|-------------| +| `npm run sonar` | Run SonarQube analysis | +| `npm run sonar:check` | Full quality check (tests + Sonar) | + +--- + +## Testing + +### Unit Tests (Angular) + +**Framework**: Karma + Jasmine + +**Run tests**: +```bash +npm test +``` + +**Run with coverage**: +```bash +npm run test:coverage +``` + +**Writing tests**: + +```typescript +// Example: src/app/services/project.service.spec.ts +describe('ProjectService', () => { + let service: ProjectService; + + beforeEach(() => { + TestBed.configureTestingModule({}); + service = TestBed.inject(ProjectService); + }); + + it('should be created', () => { + expect(service).toBeTruthy(); + }); + + it('should get projects', async () => { + const projects = await service.getProjects(); + expect(projects).toBeDefined(); + }); +}); +``` + +### Unit Tests (Electron) + +**Framework**: Vitest + +**Run tests**: +```bash +npm run test:electron +``` + +**Run in watch mode**: +```bash +npm run test:electron:watch +``` + +**Writing tests**: + +```typescript +// Example: electron/src/main/database.spec.ts +import { describe, it, expect } from 'vitest'; + +describe('Database Operations', () => { + it('should create a project', async () => { + // Test implementation + }); +}); +``` + +### Manual Testing + +1. **Run the app**: `npm run dev` +2. **Test your changes**: + - Create projects and tasks + - Add time entries + - Test UI interactions + - Verify data persistence +3. **Check console** for errors (DevTools: `Ctrl/Cmd + Shift + I`) + +--- + +## Code Quality + +### ESLint + +**Configuration**: `eslint.config.mjs` + +**Rules**: +- Angular ESLint rules +- TypeScript best practices +- Code style enforcement + +**Run linter**: +```bash +npm run lint +``` + +**Auto-fix issues**: +```bash +npm run lint:fix +``` + +### Prettier + +**Configuration**: `.prettierrc.json` + +**Format code**: +```bash +npx prettier --write . +``` + +**Pre-commit hook**: Automatically formats staged files + +### SonarQube + +**Setup** (first time): + +1. **Start SonarQube**: + ```bash + docker-compose up -d + ``` + +2. **Access SonarQube**: http://localhost:9000 + - Default credentials: `admin` / `admin` + - Change password on first login + +3. **Create project**: + - Click "Create a local project" + - Project name: `OpenTimeTracker` + - Project key: `altaskur_OpenTimeTracker` + - Main branch: `develop` + +4. **Generate token**: + - Go to My Account → Security → Generate Tokens + - Create token with name `local-analysis` + - Copy the token + +5. **Create `.env` file**: + ``` + SONAR_TOKEN=your_token_here + ``` + +6. **Run analysis**: + ```bash + npm run sonar:check + ``` + +7. **Stop SonarQube**: + ```bash + docker-compose down + ``` + +**Quality Gates**: +- Code coverage > 80% +- No critical issues +- No security hotspots +- Maintainability rating A + +--- + +## Database Development + +### Prisma Studio + +**Start Prisma Studio**: +```bash +npm run prisma:studio +``` + +Opens a GUI at http://localhost:5555 to: +- View data +- Edit records +- Test queries + +### Creating Migrations + +When you modify `prisma/schema.prisma`: + +```bash +npx prisma migrate dev --name description_of_change +``` + +**Example**: +```bash +npx prisma migrate dev --name add_task_priority +``` + +This: +1. Creates a migration file in `prisma/migrations/` +2. Applies the migration to your local database +3. Regenerates Prisma client + +### Updating Template Database + +After creating migrations: + +```bash +npm run prisma:template +``` + +This updates `prisma/template.db` used for new installations. + +--- + +## Git Workflow + +### Commit Messages + +We use **Conventional Commits**: + +``` +(): + +[optional body] + +[optional footer] +``` + +**Types**: +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `style`: Code style changes (formatting) +- `refactor`: Code refactoring +- `test`: Test changes +- `chore`: Build process or tooling changes + +**Examples**: +```bash +git commit -m "feat(projects): add project archiving functionality" +git commit -m "fix(calendar): correct date calculation in week view" +git commit -m "docs(readme): update installation instructions" +git commit -m "chore(deps): update dependencies" +``` + +**Commitlint**: Pre-commit hook enforces this format. + +### Pre-commit Hooks + +Automatically run on `git commit`: + +1. **Lint-staged**: Formats and lints staged files +2. **Commitlint**: Validates commit message format + +### Pre-push Hooks + +Automatically run on `git push` for feature branches: + +1. **SonarQube check**: Runs full quality analysis + +**Note**: Push will be blocked if SonarQube analysis fails. + +--- + +## Debugging + +### Angular DevTools + +**Open DevTools**: `Ctrl/Cmd + Shift + I` + +**Useful tabs**: +- **Console**: View logs and errors +- **Sources**: Set breakpoints +- **Network**: Monitor API calls (if any) +- **Application**: View localStorage, etc. + +### Electron Main Process + +**Enable DevTools**: + +In `electron/src/main/main.ts`: + +```typescript +mainWindow.webContents.openDevTools(); +``` + +**Logging**: + +```typescript +console.log('Debug info:', data); +``` + +Logs appear in the terminal where you ran `npm run dev`. + +### VS Code Debugging + +**Launch configuration** (`.vscode/launch.json`): + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Electron Main", + "type": "node", + "request": "launch", + "cwd": "${workspaceFolder}", + "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron", + "windows": { + "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd" + }, + "args": ["."], + "outputCapture": "std" + } + ] +} +``` + +--- + +## Troubleshooting + +### Common Issues + +**Issue**: `npm install` fails with native module errors + +**Solution**: +```bash +npm run postinstall +# or +npx electron-rebuild +``` + +--- + +**Issue**: Prisma client not found + +**Solution**: +```bash +npm run prisma:generate +``` + +--- + +**Issue**: Database locked error + +**Solution**: Close all OpenTimeTracker instances + +--- + +**Issue**: Port 4200 already in use + +**Solution**: +```bash +# Linux/macOS +killall -9 node +# Or use a different port +ng serve --port 4300 +``` + +--- + +**Issue**: SonarQube analysis fails + +**Solutions**: +1. Ensure SonarQube is running: `docker ps` +2. Check `.env` has valid `SONAR_TOKEN` +3. Verify project key matches `sonar-project.properties` + +--- + +## Best Practices + +### Code Style + +- Follow existing code patterns +- Use TypeScript types (avoid `any`) +- Write self-documenting code +- Add comments for complex logic +- Keep functions small and focused + +### Component Design + +- Use standalone components +- Keep components focused (single responsibility) +- Use services for business logic +- Use interfaces for type safety + +### State Management + +- Use Angular services for state +- Use RxJS observables for reactive state +- Avoid global state when possible + +### Performance + +- Lazy load modules when possible +- Use `OnPush` change detection for performance-critical components +- Avoid unnecessary subscriptions +- Unsubscribe from observables in `ngOnDestroy` + +--- + +## Resources + +### Documentation + +- [Angular Documentation](https://angular.io/docs) +- [Electron Documentation](https://www.electronjs.org/docs/latest) +- [Prisma Documentation](https://www.prisma.io/docs) +- [PrimeNG Components](https://primeng.org/) + +### Project Documentation + +- [Architecture](Architecture.md) +- [Database Schema](Database-Schema.md) +- [Contributing Guide](../CONTRIBUTING.md) +- [Code of Conduct](../CODE_OF_CONDUCT.md) + +--- + +## Getting Help + +- **GitHub Issues**: For bugs and feature requests +- **GitHub Discussions**: For questions and ideas +- **Code Review**: Ask maintainers for feedback + +--- + +# Configuración de Desarrollo (Español) + +Esta guía te ayudará a configurar tu entorno de desarrollo para contribuir a OpenTimeTracker. + +## Requisitos Previos + +### Requeridos + +- **Node.js**: Versión 20 o superior +- **npm**: Versión 10 o superior +- **Git**: Para control de versiones + +### Recomendados + +- **Docker & Docker Compose**: Para análisis SonarQube +- **VS Code**: IDE recomendado + +--- + +## Configuración Inicial + +### 1. Fork y Clonar + +```bash +# Haz fork en GitHub, luego clona +git clone https://github.com/TU_USUARIO/OpenTimeTracker.git +cd OpenTimeTracker + +# Agrega remote upstream +git remote add upstream https://github.com/altaskur/OpenTimeTracker.git +``` + +### 2. Instalar Dependencias + +```bash +npm install +``` + +### 3. Generar Cliente Prisma + +```bash +npm run prisma:generate +``` + +### 4. Verificar Configuración + +```bash +npm run dev +``` + +--- + +## Comandos de Desarrollo + +| Comando | Descripción | +|---------|-------------| +| `npm run dev` | Compilar y ejecutar en modo desarrollo | +| `npm test` | Ejecutar pruebas | +| `npm run lint` | Ejecutar linter | +| `npm run build` | Compilación de producción | + +--- + +## Flujo de Trabajo + +1. **Crear rama** desde `develop`: `git checkout -b feat/tu-caracteristica` +2. **Hacer cambios** y probar localmente +3. **Commit** con formato convencional +4. **Push** a tu fork +5. **Crear Pull Request** a `develop` + +--- + +Para más detalles, consulta las secciones anteriores en inglés. diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md new file mode 100644 index 0000000..e626de8 --- /dev/null +++ b/wiki/Troubleshooting.md @@ -0,0 +1,693 @@ +# Troubleshooting Guide + +This guide helps you resolve common issues with OpenTimeTracker. + +## Quick Diagnostics + +### Check Application Version + +**Windows**: Help → About OpenTimeTracker +**macOS**: OpenTimeTracker → About OpenTimeTracker +**Linux**: Help → About OpenTimeTracker + +### Check Database Location + +Default locations: +- **Windows**: `%APPDATA%\OpenTimeTracker\data\timetracker.db` +- **macOS**: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` +- **Linux**: `~/.config/OpenTimeTracker/data/timetracker.db` + +### Check Logs + +Logs are written to: +- **Windows**: `%APPDATA%\OpenTimeTracker\logs\` +- **macOS**: `~/Library/Logs/OpenTimeTracker/` +- **Linux**: `~/.config/OpenTimeTracker/logs/` + +--- + +## Installation Issues + +### Windows + +#### Issue: "Windows protected your PC" warning + +**Cause**: Application is not code-signed + +**Solutions**: +1. Click "More info" +2. Click "Run anyway" +3. Or: Download from official releases only + +--- + +#### Issue: Installation fails with error + +**Solutions**: +1. Run installer as Administrator +2. Disable antivirus temporarily +3. Check available disk space +4. Close all OpenTimeTracker instances + +--- + +### macOS + +#### Issue: "App is damaged and can't be opened" + +**Cause**: macOS Gatekeeper security + +**Solutions**: + +**Option 1**: Remove quarantine attribute +```bash +xattr -cr /Applications/OpenTimeTracker.app +``` + +**Option 2**: Allow in Security & Privacy +1. Open System Preferences → Security & Privacy +2. Click "Open Anyway" + +--- + +#### Issue: Application won't launch + +**Solutions**: +1. Check Console.app for errors +2. Verify macOS version compatibility (10.13+) +3. Reinstall application +4. Try running from terminal: + ```bash + open -a OpenTimeTracker + ``` + +--- + +### Linux + +#### Issue: AppImage won't run + +**Cause**: Missing execute permission or FUSE + +**Solutions**: + +**Option 1**: Make executable +```bash +chmod +x OpenTimeTracker-*.AppImage +./OpenTimeTracker-*.AppImage +``` + +**Option 2**: Install FUSE (if missing) +```bash +# Ubuntu/Debian +sudo apt install fuse libfuse2 + +# Fedora +sudo dnf install fuse fuse-libs + +# Arch +sudo pacman -S fuse2 +``` + +--- + +#### Issue: Icon not showing in menu + +**Solution**: Create desktop entry manually: + +```bash +cat > ~/.local/share/applications/opentimetracker.desktop << EOF +[Desktop Entry] +Name=OpenTimeTracker +Exec=/path/to/OpenTimeTracker.AppImage +Icon=opentimetracker +Type=Application +Categories=Office; +EOF +``` + +--- + +## Application Issues + +### Startup Problems + +#### Issue: Application doesn't start + +**Diagnosis**: +1. Check if process is running: + - Windows: Task Manager + - macOS: Activity Monitor + - Linux: `ps aux | grep OpenTimeTracker` + +**Solutions**: +1. Kill existing processes +2. Delete lock file (if exists): `{app-data}/SingletonLock` +3. Check system resources (RAM, disk space) +4. Reinstall application + +--- + +#### Issue: Application crashes on startup + +**Diagnosis**: +- Check logs for error messages +- Look for stack traces + +**Common causes**: +1. **Corrupted database**: Restore from backup +2. **Missing dependencies**: Reinstall +3. **Permission issues**: Check file permissions + +**Solutions**: +```bash +# Backup and reset data directory (CAUTION: Will lose data) +# Windows +move "%APPDATA%\OpenTimeTracker" "%APPDATA%\OpenTimeTracker.backup" + +# macOS +mv "~/Library/Application Support/OpenTimeTracker" "~/Library/Application Support/OpenTimeTracker.backup" + +# Linux +mv ~/.config/OpenTimeTracker ~/.config/OpenTimeTracker.backup +``` + +--- + +### Database Issues + +#### Issue: "Database is locked" error + +**Cause**: Multiple instances accessing database simultaneously + +**Solutions**: +1. Close all OpenTimeTracker instances +2. Check for zombie processes and kill them +3. Restart application + +--- + +#### Issue: Data not saving + +**Diagnosis**: +1. Check disk space +2. Verify write permissions on data directory +3. Check database file size + +**Solutions**: +1. Free up disk space +2. Fix permissions: + ```bash + # Linux/macOS + chmod 755 ~/.config/OpenTimeTracker/data + chmod 644 ~/.config/OpenTimeTracker/data/timetracker.db + ``` +3. Check if database is corrupted (see below) + +--- + +#### Issue: Database corruption + +**Symptoms**: +- Application crashes when opening certain views +- "Database disk image is malformed" error +- Missing or incorrect data + +**Solutions**: + +**Option 1**: Restore from backup +```bash +# Navigate to backup directory +cd {app-data}/backups/ + +# Copy backup to main location +# Replace timetracker.db with your backup file +``` + +**Option 2**: Attempt SQLite repair (advanced) +```bash +# Make a backup first! +sqlite3 timetracker.db ".dump" | sqlite3 timetracker-repaired.db +``` + +**Option 3**: Start fresh (LAST RESORT - Will lose data) +```bash +# Backup first! +mv timetracker.db timetracker.db.corrupt +# Application will create new database on next start +``` + +--- + +### UI Issues + +#### Issue: Blank/white screen + +**Causes**: +- GPU acceleration issues +- Corrupted cache + +**Solutions**: + +1. **Disable hardware acceleration**: + - Add `--disable-gpu` flag to launch command + - Or edit shortcut properties + +2. **Clear cache**: + ```bash + # Close app first, then delete cache + # Windows + rmdir /s "%APPDATA%\OpenTimeTracker\Cache" + + # macOS + rm -rf ~/Library/Application\ Support/OpenTimeTracker/Cache + + # Linux + rm -rf ~/.config/OpenTimeTracker/Cache + ``` + +3. **Reset window state**: + ```bash + # Delete window state file + # Windows + del "%APPDATA%\OpenTimeTracker\window-state.json" + ``` + +--- + +#### Issue: UI elements not responsive + +**Solutions**: +1. Restart application +2. Check for JavaScript errors (DevTools: Ctrl/Cmd+Shift+I) +3. Update to latest version +4. Clear cache and restart + +--- + +#### Issue: Dark mode not working / UI theme issues + +**Solutions**: +1. Go to Settings +2. Toggle Dark Mode off and on +3. Restart application +4. Check Settings database entry: + ```sql + SELECT * FROM app_settings; + ``` + +--- + +### Performance Issues + +#### Issue: Slow application performance + +**Causes**: +- Large database +- Memory leaks +- Insufficient resources + +**Solutions**: + +1. **Check database size**: + ```bash + # Should be < 100MB typically + ls -lh {app-data}/data/timetracker.db + ``` + +2. **Vacuum database** (reduces file size): + ```bash + sqlite3 timetracker.db "VACUUM;" + ``` + +3. **Archive old data**: + - Export old time entries + - Delete from database + - Keep backups + +4. **Increase available RAM**: + - Close other applications + - Restart computer + +--- + +#### Issue: High CPU usage + +**Diagnosis**: +1. Open Activity Monitor/Task Manager +2. Check CPU usage + +**Common causes**: +- Infinite render loop +- Background processes + +**Solutions**: +1. Restart application +2. Check for updates +3. Report issue with logs + +--- + +## Data Issues + +### Missing Data + +#### Issue: Projects/tasks disappeared + +**Possible causes**: +1. Data not saved before crash +2. Database corruption +3. Accidental deletion + +**Solutions**: +1. Check if project is "closed" (filter in Projects view) +2. Restore from automatic backup +3. Check action history for deletions + +--- + +#### Issue: Time entries missing + +**Solutions**: +1. Check date filters in Calendar view +2. Verify correct month/year selected +3. Check if associated task was deleted +4. Restore from backup if needed + +--- + +### Data Integrity + +#### Issue: Incorrect totals/calculations + +**Causes**: +- Orphaned time entries +- Incorrect work configuration + +**Solutions**: +1. Verify work configuration settings +2. Check for orphaned time entries: + ```sql + SELECT * FROM time_entries WHERE taskId NOT IN (SELECT id FROM tasks); + ``` +3. Recalculate totals (restart app) + +--- + +## Import/Export Issues + +### Backup Issues + +#### Issue: Automatic backups not created + +**Check**: +1. Verify backup directory exists +2. Check disk space +3. Check write permissions + +**Solutions**: +1. Create backup directory manually: + ```bash + mkdir -p {app-data}/backups + ``` +2. Fix permissions +3. Manual backup: Copy `timetracker.db` file + +--- + +#### Issue: Cannot restore backup + +**Solutions**: +1. Verify backup file is valid SQLite database: + ```bash + sqlite3 backup-file.db ".schema" + ``` +2. Check file integrity +3. Try opening in SQLite browser/viewer + +--- + +## Network/Update Issues + +#### Issue: Cannot check for updates + +**Cause**: Network connectivity or firewall + +**Solutions**: +1. Check internet connection +2. Check firewall settings +3. Manually check GitHub releases + +--- + +## Development Issues + +### Build Issues + +#### Issue: `npm install` fails + +**Solutions**: +1. Clear npm cache: `npm cache clean --force` +2. Delete `node_modules` and `package-lock.json` +3. Run `npm install` again +4. Check Node.js version (requires 20+) + +--- + +#### Issue: Prisma client not found + +**Solution**: +```bash +npm run prisma:generate +``` + +--- + +#### Issue: `electron-rebuild` fails + +**Solutions**: +1. Install build tools: + ```bash + # Windows + npm install --global windows-build-tools + + # macOS + xcode-select --install + + # Linux (Debian/Ubuntu) + sudo apt install build-essential + ``` + +2. Rebuild: + ```bash + npx electron-rebuild + ``` + +--- + +### Runtime Issues + +#### Issue: IPC errors (renderer ↔ main process) + +**Symptoms**: +- "Cannot read property of undefined" +- Database operations fail + +**Solutions**: +1. Rebuild application: `npm run dev` +2. Check preload script is loaded +3. Verify IPC handler names match + +--- + +## Getting More Help + +### Before Reporting Issues + +Please collect: +1. **Application version** +2. **Operating system** and version +3. **Steps to reproduce** the issue +4. **Expected vs actual behavior** +5. **Error messages** from logs +6. **Screenshots** (if UI issue) + +### Report Issues + +**GitHub Issues**: https://github.com/altaskur/OpenTimeTracker/issues + +**Include**: +- Clear description +- Reproduction steps +- System information +- Relevant logs/screenshots + +### Community Support + +**GitHub Discussions**: https://github.com/altaskur/OpenTimeTracker/discussions + +--- + +## Emergency Recovery + +### Complete Data Recovery + +If application is unusable: + +1. **Locate database**: See "Check Database Location" above +2. **Make backup copy**: `cp timetracker.db timetracker-backup.db` +3. **Extract data**: + ```bash + # Export all data to CSV + sqlite3 timetracker.db + .mode csv + .output projects.csv + SELECT * FROM projects; + .output tasks.csv + SELECT * FROM tasks; + .output time_entries.csv + SELECT * FROM time_entries; + .quit + ``` +4. **Reinstall application** +5. **Import data** (if import feature available) or restore database file + +--- + +## Prevention Best Practices + +1. **Regular backups**: Copy database file weekly +2. **Keep updated**: Install latest versions +3. **Monitor disk space**: Keep at least 1GB free +4. **Proper shutdown**: Always close app normally (not force quit) +5. **Test backups**: Verify backups can be restored + +--- + +# Solución de Problemas (Español) + +Esta guía te ayuda a resolver problemas comunes con OpenTimeTracker. + +## Diagnóstico Rápido + +### Verificar Ubicación de Base de Datos + +Ubicaciones predeterminadas: +- **Windows**: `%APPDATA%\OpenTimeTracker\data\timetracker.db` +- **macOS**: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` +- **Linux**: `~/.config/OpenTimeTracker/data/timetracker.db` + +--- + +## Problemas de Instalación + +### Windows + +#### Problema: Advertencia "Windows protegió tu PC" + +**Soluciones**: +1. Haz clic en "Más información" +2. Haz clic en "Ejecutar de todas formas" + +--- + +### macOS + +#### Problema: "La app está dañada" + +**Solución**: Eliminar atributo de cuarentena +```bash +xattr -cr /Applications/OpenTimeTracker.app +``` + +--- + +### Linux + +#### Problema: AppImage no se ejecuta + +**Solución**: Hacer ejecutable +```bash +chmod +x OpenTimeTracker-*.AppImage +./OpenTimeTracker-*.AppImage +``` + +--- + +## Problemas de la Aplicación + +### Problemas de Inicio + +#### Problema: La aplicación no inicia + +**Soluciones**: +1. Matar procesos existentes +2. Verificar espacio en disco +3. Reinstalar aplicación + +--- + +### Problemas de Base de Datos + +#### Problema: Error "Base de datos bloqueada" + +**Soluciones**: +1. Cerrar todas las instancias +2. Matar procesos zombie +3. Reiniciar aplicación + +--- + +#### Problema: Corrupción de base de datos + +**Opción 1**: Restaurar desde backup +```bash +# Navegar al directorio de backups +cd {app-data}/backups/ +# Copiar backup a ubicación principal +``` + +--- + +### Problemas de Rendimiento + +#### Problema: Rendimiento lento + +**Soluciones**: +1. Verificar tamaño de base de datos +2. Ejecutar VACUUM: + ```bash + sqlite3 timetracker.db "VACUUM;" + ``` +3. Archivar datos antiguos + +--- + +## Recuperación de Emergencia + +### Recuperación Completa de Datos + +1. **Ubicar base de datos** +2. **Hacer copia de seguridad** +3. **Exportar datos**: + ```bash + sqlite3 timetracker.db + .mode csv + .output projects.csv + SELECT * FROM projects; + ``` +4. **Reinstalar aplicación** +5. **Restaurar base de datos** + +--- + +## Prevención + +1. **Backups regulares**: Copiar archivo de base de datos semanalmente +2. **Mantener actualizado**: Instalar últimas versiones +3. **Cierre adecuado**: Siempre cerrar normalmente +4. **Probar backups**: Verificar que se pueden restaurar + +--- + +Para más detalles, consulta las secciones anteriores en inglés. From 540153bc179379659f7401b7af24a848ae4f0e43 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:02:38 +0000 Subject: [PATCH 4/6] docs: add FAQ, Contributing, Security, Roadmap and wiki README pages Co-authored-by: altaskur <105789412+altaskur@users.noreply.github.com> --- wiki/Contributing.md | 369 +++++++++++++++++++++++++++++ wiki/FAQ.md | 541 +++++++++++++++++++++++++++++++++++++++++++ wiki/README.md | 155 +++++++++++++ wiki/Roadmap.md | 452 ++++++++++++++++++++++++++++++++++++ wiki/Security.md | 422 +++++++++++++++++++++++++++++++++ 5 files changed, 1939 insertions(+) create mode 100644 wiki/Contributing.md create mode 100644 wiki/FAQ.md create mode 100644 wiki/README.md create mode 100644 wiki/Roadmap.md create mode 100644 wiki/Security.md diff --git a/wiki/Contributing.md b/wiki/Contributing.md new file mode 100644 index 0000000..616ee80 --- /dev/null +++ b/wiki/Contributing.md @@ -0,0 +1,369 @@ +# Contributing to OpenTimeTracker + +This wiki page provides quick reference for contributors. For complete details, see the main [CONTRIBUTING.md](../CONTRIBUTING.md) file in the repository. + +## Quick Start for Contributors + +### 1. Fork & Clone + +```bash +git clone https://github.com/YOUR_USERNAME/OpenTimeTracker.git +cd OpenTimeTracker +git remote add upstream https://github.com/altaskur/OpenTimeTracker.git +``` + +### 2. Install & Setup + +```bash +npm install +npm run prisma:generate +npm run dev +``` + +### 3. Create Branch + +```bash +git checkout develop +git checkout -b feat/your-feature-name +``` + +### 4. Make Changes + +- Write code +- Add tests +- Update documentation +- Follow code style + +### 5. Test & Lint + +```bash +npm run lint +npm test +npm run test:electron +npm run sonar:check +``` + +### 6. Commit + +Use Conventional Commits: + +```bash +git commit -m "feat(projects): add project archiving" +git commit -m "fix(calendar): correct date calculation" +git commit -m "docs(readme): update installation steps" +``` + +### 7. Push & PR + +```bash +git push origin feat/your-feature-name +``` + +Create Pull Request on GitHub to `develop` branch. + +--- + +## Contribution Types + +### 🐛 Bug Reports + +Found a bug? [Open an issue](https://github.com/altaskur/OpenTimeTracker/issues/new). + +Include: +- Steps to reproduce +- Expected behavior +- Actual behavior +- System information +- Screenshots (if applicable) + +### 💡 Feature Requests + +Have an idea? [Open an issue](https://github.com/altaskur/OpenTimeTracker/issues/new) or [discussion](https://github.com/altaskur/OpenTimeTracker/discussions). + +Describe: +- The problem you're solving +- Proposed solution +- Alternatives considered +- Additional context + +### 🔧 Code Contributions + +1. Check [existing issues](https://github.com/altaskur/OpenTimeTracker/issues) for "good first issue" labels +2. Comment on the issue to claim it +3. Follow the workflow above +4. Submit PR + +### 📖 Documentation + +Improve: +- README +- Wiki pages +- Code comments +- API documentation +- Examples + +### 🌍 Translations + +Add or improve translations: + +1. Edit translation files: + - `src/assets/i18n/en.json` + - `src/assets/i18n/es.json` +2. Add new language files if needed +3. Test translations in the app +4. Submit PR + +--- + +## Code Style + +### TypeScript + +- Use strict typing (avoid `any`) +- Prefer `const` over `let` +- Use descriptive variable names +- Add JSDoc for public APIs + +### Angular + +- Follow Angular style guide +- Use standalone components +- Inject services via constructor +- Use OnPush change detection when appropriate + +### Formatting + +- Prettier handles formatting automatically +- Pre-commit hooks enforce style +- Run `npm run lint:fix` to auto-fix issues + +--- + +## Testing + +### Unit Tests (Angular) + +```typescript +// project.service.spec.ts +describe('ProjectService', () => { + it('should get projects', async () => { + const projects = await service.getProjects(); + expect(projects).toBeDefined(); + }); +}); +``` + +Run: `npm test` + +### Unit Tests (Electron) + +```typescript +// database.spec.ts +import { describe, it, expect } from 'vitest'; + +describe('Database', () => { + it('should create project', async () => { + // test + }); +}); +``` + +Run: `npm run test:electron` + +### Manual Testing + +Always test your changes manually: +1. Build: `npm run dev` +2. Test functionality +3. Check for console errors +4. Test edge cases + +--- + +## Pull Request Checklist + +Before submitting PR: + +- [ ] Code follows project style +- [ ] Tests added/updated +- [ ] All tests pass +- [ ] Linting passes +- [ ] Documentation updated +- [ ] Commit messages follow convention +- [ ] PR description is clear +- [ ] Linked to related issue (if any) + +--- + +## Pull Request Template + +```markdown +## Description +[Describe what this PR does] + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Breaking change +- [ ] Documentation update + +## Changes Made +- [List key changes] + +## Testing +- [Describe testing performed] + +## Screenshots +[If applicable] + +## Checklist +- [ ] Tests pass +- [ ] Linting passes +- [ ] Documentation updated +``` + +--- + +## Development Resources + +- [Development Setup](Development-Setup.md) - Complete setup guide +- [Architecture](Architecture.md) - System architecture +- [Database Schema](Database-Schema.md) - Data model +- [Main CONTRIBUTING.md](../CONTRIBUTING.md) - Full contribution guide + +--- + +## Code of Conduct + +All contributors must follow the [Code of Conduct](../CODE_OF_CONDUCT.md). + +In summary: +- Be respectful +- Be collaborative +- Be constructive +- Be patient + +--- + +## Questions? + +- Check [FAQ](FAQ.md) +- Ask in [Discussions](https://github.com/altaskur/OpenTimeTracker/discussions) +- Open an issue + +--- + +## Recognition + +Contributors are listed in: +- GitHub contributors page +- Release notes (for significant contributions) +- Special thanks in major releases + +Thank you for contributing! 🎉 + +--- + +# Contribuyendo (Español) + +Esta página wiki proporciona referencia rápida para contribuyentes. Para detalles completos, consulta el archivo principal [CONTRIBUTING.md](../CONTRIBUTING.md) en el repositorio. + +## Inicio Rápido + +### 1. Fork y Clonar + +```bash +git clone https://github.com/TU_USUARIO/OpenTimeTracker.git +cd OpenTimeTracker +git remote add upstream https://github.com/altaskur/OpenTimeTracker.git +``` + +### 2. Instalar + +```bash +npm install +npm run prisma:generate +npm run dev +``` + +### 3. Crear Rama + +```bash +git checkout develop +git checkout -b feat/tu-caracteristica +``` + +### 4. Hacer Cambios + +- Escribir código +- Agregar pruebas +- Actualizar documentación + +### 5. Probar + +```bash +npm run lint +npm test +npm run test:electron +``` + +### 6. Commit + +Usar Conventional Commits: + +```bash +git commit -m "feat(proyectos): agregar archivo de proyectos" +git commit -m "fix(calendario): corregir cálculo de fecha" +``` + +### 7. Push y PR + +```bash +git push origin feat/tu-caracteristica +``` + +Crear Pull Request en GitHub a la rama `develop`. + +--- + +## Tipos de Contribución + +### 🐛 Reportes de Errores + +¿Encontraste un bug? [Abre un issue](https://github.com/altaskur/OpenTimeTracker/issues/new). + +### 💡 Solicitudes de Características + +¿Tienes una idea? [Abre un issue](https://github.com/altaskur/OpenTimeTracker/issues/new) o [discusión](https://github.com/altaskur/OpenTimeTracker/discussions). + +### 🔧 Contribuciones de Código + +1. Revisa [issues existentes](https://github.com/altaskur/OpenTimeTracker/issues) +2. Comenta en el issue para reclamarlo +3. Sigue el flujo de trabajo anterior +4. Envía PR + +### 📖 Documentación + +Mejora: +- README +- Páginas wiki +- Comentarios de código + +### 🌍 Traducciones + +Agrega o mejora traducciones en: +- `src/assets/i18n/en.json` +- `src/assets/i18n/es.json` + +--- + +## Recursos + +- [Configuración de Desarrollo](Development-Setup.md#configuración-de-desarrollo-español) +- [Arquitectura](Architecture.md#arquitectura-español) +- [CONTRIBUTING.md principal](../CONTRIBUTING.md) + +--- + +¡Gracias por contribuir! 🎉 diff --git a/wiki/FAQ.md b/wiki/FAQ.md new file mode 100644 index 0000000..4bd06b3 --- /dev/null +++ b/wiki/FAQ.md @@ -0,0 +1,541 @@ +# Frequently Asked Questions (FAQ) + +Common questions about OpenTimeTracker. + +## General Questions + +### What is OpenTimeTracker? + +OpenTimeTracker is a free, open-source desktop application for tracking time spent on projects and tasks. It's designed for developers and small teams who want full control over their data without relying on cloud services. + +### Is OpenTimeTracker really free? + +Yes! OpenTimeTracker is licensed under GPL-3.0, which means: +- ✅ Free to use +- ✅ Free to modify +- ✅ Free to distribute +- ✅ No subscriptions or hidden costs + +### What platforms are supported? + +- **Windows**: 10 and later (x64) +- **macOS**: 10.13 (High Sierra) and later (Intel & Apple Silicon) +- **Linux**: Most distributions (x64) + +### Does it work offline? + +Yes! OpenTimeTracker is fully offline. All data is stored locally on your computer. You don't need an internet connection to use the app. + +### Is my data private? + +Absolutely. Your data never leaves your computer unless you explicitly copy or export it. There is no telemetry, analytics, or cloud sync. + +--- + +## Features + +### Can I track time without assigning it to a task? + +Yes! Time entries can be created without associating them with a task. This is useful for general time tracking. + +### Can I organize tasks across multiple projects? + +Tasks belong to a single project, but you can use **tags** to categorize tasks across different projects. + +### Does it support multiple users? + +OpenTimeTracker is designed as a single-user application. Each instance has its own local database. + +### Can I customize task statuses? + +Yes! Go to Settings → Statuses to: +- Create custom statuses +- Choose colors +- Set a default status + +### Can I set different work schedules? + +Yes! In Settings → Work Configuration: +- Set daily/weekly work hours +- Configure work days +- Set different schedules per day +- Override specific months + +### Can I mark holidays and vacation days? + +Yes! Use Settings → Day Types to: +- Create day types (Holiday, Vacation, Sick Leave, etc.) +- Assign colors +- Set default work minutes +- Override specific dates in the Calendar view + +--- + +## Data & Backups + +### Where is my data stored? + +- **Windows**: `%APPDATA%\OpenTimeTracker\data\timetracker.db` +- **macOS**: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` +- **Linux**: `~/.config/OpenTimeTracker/data/timetracker.db` + +### Are backups automatic? + +Yes! OpenTimeTracker automatically creates a backup of your database when you close the application. Backups are saved in: +- `{app-data}/backups/timetracker-backup-YYYY-MM-DD-HH-mm-ss.db` + +### How do I manually backup my data? + +Simply copy the database file to a safe location: +```bash +# Example (macOS/Linux) +cp ~/Library/Application\ Support/OpenTimeTracker/data/timetracker.db ~/my-backup.db +``` + +### How do I restore from a backup? + +1. Close OpenTimeTracker +2. Replace `timetracker.db` with your backup file +3. Restart the application + +### Can I export my data? + +Currently, manual export is available by: +- Copying the SQLite database file +- Using SQLite tools to export to CSV/JSON +- Feature request: Built-in export is planned + +### Can I sync data across devices? + +Not currently. OpenTimeTracker is local-first by design. However: +- You can manually copy the database file between devices +- Cloud sync via third-party tools (Dropbox, etc.) is possible but not officially supported +- Self-hosted sync may be added in the future + +--- + +## Usage + +### How do I close a project? + +1. Go to Projects view +2. Click on the project +3. Click "Close Project" or edit and check "Is Closed" +4. Closed projects are hidden by default (use filter to show them) + +### Can I reopen a closed project? + +Yes! +1. Show closed projects (filter) +2. Edit the project +3. Uncheck "Is Closed" + +### Can I delete a project? + +Yes, but **be careful**: +- Deleting a project also deletes all its tasks +- Time entries are kept but lose their task association +- This action cannot be undone (unless you restore from backup) + +### How do I undo an action? + +OpenTimeTracker tracks actions in the History view: +1. Go to History +2. Find the action +3. Click "Undo" (if available) + +Note: Not all actions are undoable yet. This feature is being improved. + +### Can I import time entries? + +Not built-in yet, but you can: +- Manually insert via SQLite (advanced) +- Feature request: Import functionality is planned + +--- + +## Technical + +### What database does it use? + +SQLite - a lightweight, file-based database. No server required. + +### Can I view/edit the database directly? + +Yes, using SQLite tools: +- **DB Browser for SQLite**: https://sqlitebrowser.org/ +- **Prisma Studio**: `npm run prisma:studio` (for developers) + +**Warning**: Direct database editing can corrupt data. Always backup first! + +### How large can my database get? + +SQLite can handle very large databases (terabytes), but for best performance: +- Typical usage: < 50MB +- Heavy usage: < 500MB +- Consider archiving old data if it grows beyond 1GB + +### What's the tech stack? + +- **Frontend**: Angular 21 +- **Desktop**: Electron 37 +- **Database**: Prisma + SQLite +- **UI**: PrimeNG + PrimeFlex +- **License**: GPL-3.0 + +See [Architecture](Architecture.md) for details. + +--- + +## Internationalization + +### What languages are supported? + +Currently: +- English (en) +- Spanish (es) + +### How do I change the language? + +Settings → Language → Select language → Restart app + +### Can I contribute translations? + +Yes! See [Contributing Guide](../CONTRIBUTING.md). Translation files are in: +- `src/assets/i18n/en.json` +- `src/assets/i18n/es.json` + +--- + +## Troubleshooting + +### The app won't start. What should I do? + +See [Troubleshooting Guide](Troubleshooting.md) for detailed solutions. + +Quick checks: +1. Check if another instance is running +2. Check disk space +3. Try restarting your computer +4. Reinstall the application + +### I lost my data. Can I recover it? + +If you have backups: +1. Check `{app-data}/backups/` folder +2. Restore most recent backup + +If no backups: +- Data may be unrecoverable +- **Prevention**: Always keep regular backups + +### The database is corrupted. What now? + +1. Restore from backup (recommended) +2. Try SQLite repair: `sqlite3 db.db ".recover" | sqlite3 new.db` +3. Last resort: Start fresh (data loss) + +See [Troubleshooting Guide](Troubleshooting.md) for details. + +### How do I report a bug? + +1. Check [existing issues](https://github.com/altaskur/OpenTimeTracker/issues) +2. If not found, create a new issue with: + - Description + - Steps to reproduce + - Expected vs actual behavior + - System information + - Screenshots (if applicable) + +--- + +## Development + +### How do I build from source? + +See [Development Setup](Development-Setup.md). + +Quick start: +```bash +git clone https://github.com/altaskur/OpenTimeTracker.git +cd OpenTimeTracker +npm install +npm run prisma:generate +npm run dev +``` + +### How can I contribute? + +See [Contributing Guide](../CONTRIBUTING.md). + +Ways to contribute: +- Report bugs +- Request features +- Submit pull requests +- Improve documentation +- Add translations + +### What's the development workflow? + +1. Fork the repository +2. Create a feature branch from `develop` +3. Make changes +4. Run tests and linting +5. Submit pull request + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for details. + +--- + +## Roadmap & Future + +### What features are planned? + +See [Roadmap](Roadmap.md) (if available) or check: +- [GitHub Issues](https://github.com/altaskur/OpenTimeTracker/issues) +- [GitHub Discussions](https://github.com/altaskur/OpenTimeTracker/discussions) + +Commonly requested: +- CSV/JSON export +- Reports and analytics +- Pomodoro timer +- Integrations (Git, Jira, etc.) +- Optional self-hosted sync + +### Is there a mobile app? + +Not currently. OpenTimeTracker is a desktop application. A mobile app may be considered in the future. + +### Will there be a cloud/SaaS version? + +No. OpenTimeTracker is local-first by design. However: +- You can self-host a sync server (future feature) +- Third-party cloud sync (at your own risk) + +### Is this actively maintained? + +Yes! OpenTimeTracker is under active development. Check [commit history](https://github.com/altaskur/OpenTimeTracker/commits) and [releases](https://github.com/altaskur/OpenTimeTracker/releases) for activity. + +--- + +## Security & Privacy + +### Is my data secure? + +Your data is as secure as your computer: +- Data is stored locally +- No cloud transmission +- No analytics or telemetry +- You control backups + +**Best practices**: +- Use full-disk encryption (OS feature) +- Regular backups to secure location +- Keep OS and app updated + +### Does it collect any data? + +No. OpenTimeTracker: +- ❌ No telemetry +- ❌ No analytics +- ❌ No cloud sync +- ❌ No external network requests (except update checks) + +### How do I report security vulnerabilities? + +See [SECURITY.md](../SECURITY.md). + +**Do NOT** report security issues publicly. Use: +- GitHub Security Advisories +- Direct contact with maintainer + +--- + +## Licensing + +### What does GPL-3.0 mean? + +GPL-3.0 (GNU General Public License v3.0) means: +- ✅ Free to use for any purpose +- ✅ Free to study and modify the source code +- ✅ Free to share (redistribute) +- ✅ Any modifications must also be GPL-3.0 +- ✅ Source code must be made available + +### Can I use this commercially? + +Yes! You can use OpenTimeTracker for commercial purposes. + +### Can I sell this software? + +You can sell OpenTimeTracker, but you must: +- Provide source code +- Keep GPL-3.0 license +- Clearly indicate it's free software + +In practice, it's easier to just give it away (since source is freely available). + +### Can I fork this project? + +Yes! You can create a fork, but: +- Must maintain GPL-3.0 license +- Must provide source code +- Must credit original project + +--- + +## Support + +### Where can I get help? + +- **Documentation**: Start with [Getting Started](Getting-Started.md) +- **Troubleshooting**: Check [Troubleshooting Guide](Troubleshooting.md) +- **FAQ**: You're here! +- **Issues**: [GitHub Issues](https://github.com/altaskur/OpenTimeTracker/issues) +- **Discussions**: [GitHub Discussions](https://github.com/altaskur/OpenTimeTracker/discussions) + +### Is there community support? + +Yes! +- GitHub Discussions for questions +- GitHub Issues for bugs +- Community contributions welcome + +### Is there paid support? + +Currently no. OpenTimeTracker is a community-driven project. Support is provided by maintainers and community on a best-effort basis. + +--- + +## Credits + +### Who created OpenTimeTracker? + +Created and maintained by [@altaskur](https://github.com/altaskur). + +### How can I support the project? + +- ⭐ Star the repository +- 🐛 Report bugs +- 💡 Suggest features +- 🤝 Contribute code +- 📖 Improve documentation +- 🌍 Add translations +- 💬 Help others in discussions + +--- + +# Preguntas Frecuentes (Español) + +Preguntas comunes sobre OpenTimeTracker. + +## Preguntas Generales + +### ¿Qué es OpenTimeTracker? + +OpenTimeTracker es una aplicación de escritorio gratuita y de código abierto para rastrear tiempo dedicado a proyectos y tareas. Está diseñada para desarrolladores y equipos pequeños que desean control total sobre sus datos sin depender de servicios en la nube. + +### ¿Es realmente gratis? + +¡Sí! OpenTimeTracker está licenciado bajo GPL-3.0, lo que significa: +- ✅ Gratis para usar +- ✅ Gratis para modificar +- ✅ Gratis para distribuir +- ✅ Sin suscripciones ni costos ocultos + +### ¿Qué plataformas son compatibles? + +- **Windows**: 10 y posterior (x64) +- **macOS**: 10.13 (High Sierra) y posterior (Intel y Apple Silicon) +- **Linux**: La mayoría de distribuciones (x64) + +### ¿Funciona sin conexión? + +¡Sí! OpenTimeTracker funciona completamente offline. Todos los datos se almacenan localmente en tu computadora. + +### ¿Son privados mis datos? + +Absolutamente. Tus datos nunca salen de tu computadora a menos que los copies o exportes explícitamente. No hay telemetría, analytics ni sincronización en la nube. + +--- + +## Características + +### ¿Puedo rastrear tiempo sin asignarlo a una tarea? + +¡Sí! Las entradas de tiempo se pueden crear sin asociarlas con una tarea. + +### ¿Puedo personalizar los estados de tareas? + +¡Sí! Ve a Configuración → Estados para: +- Crear estados personalizados +- Elegir colores +- Establecer un estado predeterminado + +### ¿Puedo establecer diferentes horarios de trabajo? + +¡Sí! En Configuración → Configuración de Trabajo: +- Establecer horas de trabajo diarias/semanales +- Configurar días laborables +- Establecer diferentes horarios por día +- Anular meses específicos + +--- + +## Datos y Backups + +### ¿Dónde se almacenan mis datos? + +- **Windows**: `%APPDATA%\OpenTimeTracker\data\timetracker.db` +- **macOS**: `~/Library/Application Support/OpenTimeTracker/data/timetracker.db` +- **Linux**: `~/.config/OpenTimeTracker/data/timetracker.db` + +### ¿Los backups son automáticos? + +¡Sí! OpenTimeTracker crea automáticamente un backup de tu base de datos cuando cierras la aplicación. + +### ¿Cómo hago un backup manual? + +Simplemente copia el archivo de base de datos a una ubicación segura. + +### ¿Cómo restauro desde un backup? + +1. Cierra OpenTimeTracker +2. Reemplaza `timetracker.db` con tu archivo de backup +3. Reinicia la aplicación + +--- + +## Solución de Problemas + +### La aplicación no inicia. ¿Qué hago? + +Ver [Guía de Solución de Problemas](Troubleshooting.md#solución-de-problemas-español). + +Verificaciones rápidas: +1. Verificar si hay otra instancia ejecutándose +2. Verificar espacio en disco +3. Reiniciar computadora +4. Reinstalar aplicación + +--- + +## Desarrollo + +### ¿Cómo compilo desde el código fuente? + +Ver [Configuración de Desarrollo](Development-Setup.md#configuración-de-desarrollo-español). + +--- + +## Soporte + +### ¿Dónde puedo obtener ayuda? + +- **Documentación**: Comienza con [Comenzar](Getting-Started.md#guía-de-inicio-español) +- **Solución de Problemas**: [Guía](Troubleshooting.md#solución-de-problemas-español) +- **Problemas**: [GitHub Issues](https://github.com/altaskur/OpenTimeTracker/issues) + +--- + +Para más preguntas, consulta las secciones anteriores en inglés. diff --git a/wiki/README.md b/wiki/README.md new file mode 100644 index 0000000..c329601 --- /dev/null +++ b/wiki/README.md @@ -0,0 +1,155 @@ +# OpenTimeTracker Wiki + +This directory contains comprehensive documentation for the OpenTimeTracker project. + +## 📖 Wiki Structure + +### Getting Started +- **[Home](Home.md)** - Wiki home page and navigation +- **[Getting Started](Getting-Started.md)** - Installation and first steps +- **[FAQ](FAQ.md)** - Frequently asked questions + +### User Documentation +- **[Getting Started](Getting-Started.md)** - Complete installation and setup guide +- **[Troubleshooting](Troubleshooting.md)** - Common issues and solutions +- **[FAQ](FAQ.md)** - Answers to common questions + +### Developer Documentation +- **[Development Setup](Development-Setup.md)** - Setting up development environment +- **[Architecture](Architecture.md)** - Technical design and system architecture +- **[Database Schema](Database-Schema.md)** - Data model and relationships +- **[Build and Deployment](Build-and-Deployment.md)** - Building and packaging guide +- **[Contributing](Contributing.md)** - How to contribute (wiki quick reference) + +### Project Information +- **[Roadmap](Roadmap.md)** - Future plans and feature roadmap +- **[Security](Security.md)** - Security policy and best practices + +--- + +## 🌐 Bilingual Documentation + +All wiki pages include content in both English and Spanish: +- English content appears first +- Spanish content follows (marked with "Español" headers) + +--- + +## 📝 How to Use This Wiki + +### For New Users +1. Start with **[Getting Started](Getting-Started.md)** +2. Explore features through the guides +3. Check **[FAQ](FAQ.md)** for common questions +4. Use **[Troubleshooting](Troubleshooting.md)** if you encounter issues + +### For Developers +1. Read **[Development Setup](Development-Setup.md)** to get started +2. Study **[Architecture](Architecture.md)** to understand the system +3. Review **[Database Schema](Database-Schema.md)** for data model +4. Follow **[Contributing](Contributing.md)** guidelines + +### For Contributors +1. Check **[Contributing](Contributing.md)** for quick reference +2. See main **[CONTRIBUTING.md](../CONTRIBUTING.md)** for complete guidelines +3. Review **[Code of Conduct](../CODE_OF_CONDUCT.md)** +4. Explore **[Roadmap](Roadmap.md)** for planned features + +--- + +## 🔗 External Resources + +### Repository Files +- **[README.md](../README.md)** - Project overview +- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Complete contribution guide +- **[SECURITY.md](../SECURITY.md)** - Full security policy +- **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** - Community guidelines +- **[LICENSE](../LICENSE)** - GPL-3.0 license + +### Online Resources +- **GitHub Repository**: https://github.com/altaskur/OpenTimeTracker +- **Releases**: https://github.com/altaskur/OpenTimeTracker/releases +- **Issues**: https://github.com/altaskur/OpenTimeTracker/issues +- **Discussions**: https://github.com/altaskur/OpenTimeTracker/discussions + +--- + +## ✏️ Contributing to Wiki + +The wiki is part of the repository and follows the same contribution process: + +1. **Fork the repository** +2. **Create a branch**: `git checkout -b docs/wiki-update` +3. **Edit wiki files** in the `wiki/` directory +4. **Follow Markdown best practices** +5. **Update in both languages** (English and Spanish) +6. **Submit pull request** to `develop` branch + +### Wiki Style Guide + +- Use clear, concise language +- Include code examples where appropriate +- Add screenshots for UI features +- Keep formatting consistent +- Update cross-references when adding new pages +- Maintain bilingual content + +--- + +## 🗂️ Wiki Maintenance + +### Keeping Wiki Updated + +When making changes to the project: +- Update relevant wiki pages +- Check for broken links +- Verify code examples still work +- Update version numbers +- Reflect new features in documentation + +### Wiki Version + +Wiki documentation reflects the **latest stable version** unless otherwise noted. + +For development/unreleased features, check: +- GitHub `develop` branch +- Pull requests +- Issue discussions + +--- + +## 📋 Wiki Index + +### Complete Page List + +1. [Home](Home.md) - Wiki welcome and navigation +2. [Getting Started](Getting-Started.md) - Installation and setup +3. [Architecture](Architecture.md) - Technical architecture +4. [Database Schema](Database-Schema.md) - Data model +5. [Development Setup](Development-Setup.md) - Dev environment setup +6. [Build and Deployment](Build-and-Deployment.md) - Building and packaging +7. [Troubleshooting](Troubleshooting.md) - Common issues +8. [FAQ](FAQ.md) - Frequently asked questions +9. [Contributing](Contributing.md) - Contribution quick reference +10. [Security](Security.md) - Security policy +11. [Roadmap](Roadmap.md) - Future plans + +--- + +## 🆘 Need Help? + +- **Issues**: [GitHub Issues](https://github.com/altaskur/OpenTimeTracker/issues) +- **Discussions**: [GitHub Discussions](https://github.com/altaskur/OpenTimeTracker/discussions) +- **Email**: Contact [@altaskur](https://github.com/altaskur) + +--- + +## 📜 License + +Documentation is part of OpenTimeTracker and is licensed under [GPL-3.0](../LICENSE). + +--- + +**Last Updated**: 2026-02-05 + +**Maintained By**: [@altaskur](https://github.com/altaskur) and contributors diff --git a/wiki/Roadmap.md b/wiki/Roadmap.md new file mode 100644 index 0000000..f55ac0a --- /dev/null +++ b/wiki/Roadmap.md @@ -0,0 +1,452 @@ +# Roadmap + +OpenTimeTracker is in **active development**. This page outlines planned features and improvements. + +## Current Status + +**Version**: 1.0.0-alpha.3 +**Stage**: Alpha - Active Development + +⚠️ Features, UI, and internal APIs may change. + +--- + +## Release Milestones + +### Alpha (Current) + +**Focus**: Core functionality and stability + +**Status**: ✅ Released + +**Features**: +- ✅ Project management +- ✅ Task management with statuses +- ✅ Time tracking (calendar view) +- ✅ Tags for categorization +- ✅ Work configuration +- ✅ Day types and overrides +- ✅ Automatic backups +- ✅ Dark mode +- ✅ Bilingual (English/Spanish) +- ✅ Action history (undo/redo) + +--- + +### Beta (Planned) + +**Focus**: Refinement, reports, and export + +**Target**: Q2-Q3 2026 + +**Planned Features**: +- [ ] Reports and analytics +- [ ] Data export (CSV, JSON) +- [ ] Data import +- [ ] Advanced filtering +- [ ] Search functionality +- [ ] Custom reports +- [ ] Charts and visualizations +- [ ] Print support +- [ ] Keyboard shortcuts +- [ ] Performance optimizations +- [ ] UI/UX improvements +- [ ] Additional themes + +--- + +### 1.0 Stable (Planned) + +**Focus**: Production-ready release + +**Target**: Q4 2026 + +**Goals**: +- [ ] API stability +- [ ] Comprehensive testing +- [ ] Complete documentation +- [ ] Performance benchmarks +- [ ] Security audit +- [ ] Code signing for all platforms +- [ ] Auto-update mechanism +- [ ] Migration tools + +--- + +## Feature Requests + +Popular feature requests from the community: + +### High Priority + +1. **Export/Import** + - Status: 📝 Planned for Beta + - CSV and JSON export + - Import from other time tracking tools + +2. **Reports** + - Status: 📝 Planned for Beta + - Time summaries by project/task/period + - Custom report builder + - PDF export + +3. **Advanced Search** + - Status: 📝 Planned for Beta + - Global search across projects/tasks + - Filter by date range, tags, status + - Saved searches + +4. **Keyboard Shortcuts** + - Status: 📝 Planned for Beta + - Quick time entry + - Navigation shortcuts + - Customizable hotkeys + +### Medium Priority + +5. **Pomodoro Timer** + - Status: 💡 Under consideration + - Built-in timer + - Notifications + - Automatic time entry creation + +6. **Integrations** + - Status: 💡 Under consideration + - Git commit time tracking + - Jira/GitHub issues + - Calendar apps (Google Calendar, Outlook) + - IDE plugins (VS Code) + +7. **Mobile App** + - Status: 💡 Future consideration + - Companion mobile app + - Read-only view + - Quick time entries + +8. **Team Features** + - Status: 💡 Future consideration + - Multi-user support + - Shared projects + - Time approval workflows + +### Low Priority / Future + +9. **Self-Hosted Sync** + - Status: 💡 Long-term consideration + - Optional sync server + - Self-hosted solution + - End-to-end encryption + +10. **Invoice Generation** + - Status: 💡 Long-term consideration + - Generate invoices from time entries + - Customizable templates + - PDF export + +11. **Budget Tracking** + - Status: 💡 Long-term consideration + - Project budgets + - Cost tracking + - Budget alerts + +12. **Additional Languages** + - Status: 🌍 Community-driven + - French, German, Portuguese, etc. + - Community translations welcome + +--- + +## Technical Improvements + +### Short Term + +- [ ] Improve test coverage (target: 90%+) +- [ ] Performance profiling and optimization +- [ ] Memory leak detection and fixes +- [ ] Database query optimization +- [ ] Bundle size reduction + +### Medium Term + +- [ ] Plugin/extension system +- [ ] REST API for integrations +- [ ] Improved error handling +- [ ] Better logging system +- [ ] Crash reporting (opt-in) + +### Long Term + +- [ ] Migrate to newer frameworks (as needed) +- [ ] Consider Rust for performance-critical parts +- [ ] Advanced caching strategies +- [ ] Offline-first sync protocol + +--- + +## Known Limitations + +Current limitations to be addressed: + +1. **Single User** + - Current: Single-user only + - Future: Multi-user support considered + +2. **No Cloud Sync** + - Current: Local-only + - Future: Optional self-hosted sync + +3. **Limited Export** + - Current: Manual SQLite export + - Future: Built-in CSV/JSON export + +4. **No Mobile App** + - Current: Desktop only + - Future: Companion mobile app considered + +5. **Basic Reporting** + - Current: Basic stats in UI + - Future: Advanced reports and analytics + +--- + +## Contributing to Roadmap + +Have ideas? We'd love to hear them! + +### How to Contribute + +1. **Check existing issues**: [GitHub Issues](https://github.com/altaskur/OpenTimeTracker/issues) +2. **Search discussions**: [GitHub Discussions](https://github.com/altaskur/OpenTimeTracker/discussions) +3. **Create new request**: If not found, open an issue with: + - Clear description + - Use case/problem it solves + - Proposed solution (if any) + - Why it's important + +### Prioritization + +Features are prioritized based on: +- 👥 **Community interest**: Number of upvotes/comments +- 🎯 **Alignment**: Fits project goals and philosophy +- ⚡ **Impact**: Benefits many users +- 💪 **Effort**: Development time and complexity +- 🔒 **Stability**: Doesn't compromise security/privacy + +--- + +## Development Progress + +### Track Progress + +- **GitHub Issues**: Track individual features +- **GitHub Projects**: Overall project status +- **Releases**: Version history and changelogs +- **Commits**: Day-to-day development + +### Get Involved + +Ways to help move the roadmap forward: + +1. **Code contributions**: Implement features +2. **Testing**: Test alpha/beta releases +3. **Documentation**: Improve docs +4. **Feedback**: Report bugs and suggestions +5. **Translations**: Add language support +6. **Spread the word**: Share with others + +--- + +## Version History + +### v1.0.0-alpha.3 (Current) + +**Released**: [Check releases](https://github.com/altaskur/OpenTimeTracker/releases) + +**Highlights**: +- Complete time tracking system +- Project and task management +- Work configuration +- Automatic backups +- Dark mode by default + +### Previous Versions + +See [Release Notes](https://github.com/altaskur/OpenTimeTracker/releases) for complete history. + +--- + +## Long-Term Vision + +OpenTimeTracker aims to be: + +1. **Privacy-First**: Your data, your control +2. **Open Source**: Transparent and community-driven +3. **Local-First**: Works offline, always +4. **Developer-Friendly**: Built by developers, for developers +5. **Extensible**: Plugin system for custom functionality +6. **Cross-Platform**: Windows, macOS, Linux support +7. **Zero Dependencies**: No required cloud services or subscriptions + +--- + +## Questions? + +- **When will feature X be released?**: Check this roadmap or GitHub issues +- **Can I help implement feature Y?**: Yes! See [Contributing](Contributing.md) +- **Will feature Z be added?**: Open a discussion to propose it + +--- + +## Disclaimer + +This roadmap is **subject to change** based on: +- Community feedback +- Technical constraints +- Maintainer availability +- Project priorities + +There are **no guarantees** on timeline or feature inclusion. + +--- + +# Hoja de Ruta (Español) + +OpenTimeTracker está en **desarrollo activo**. Esta página describe características y mejoras planificadas. + +## Estado Actual + +**Versión**: 1.0.0-alpha.3 +**Etapa**: Alfa - Desarrollo Activo + +⚠️ Las características, UI y APIs internas pueden cambiar. + +--- + +## Hitos de Lanzamiento + +### Alfa (Actual) + +**Enfoque**: Funcionalidad principal y estabilidad + +**Estado**: ✅ Lanzado + +**Características**: +- ✅ Gestión de proyectos +- ✅ Gestión de tareas con estados +- ✅ Rastreo de tiempo (vista de calendario) +- ✅ Etiquetas para categorización +- ✅ Configuración de trabajo +- ✅ Tipos de día y anulaciones +- ✅ Backups automáticos +- ✅ Modo oscuro +- ✅ Bilingüe (Inglés/Español) +- ✅ Historial de acciones (deshacer/rehacer) + +--- + +### Beta (Planificado) + +**Enfoque**: Refinamiento, reportes y exportación + +**Objetivo**: Q2-Q3 2026 + +**Características Planificadas**: +- [ ] Reportes y analytics +- [ ] Exportación de datos (CSV, JSON) +- [ ] Importación de datos +- [ ] Filtrado avanzado +- [ ] Funcionalidad de búsqueda +- [ ] Reportes personalizados +- [ ] Gráficos y visualizaciones +- [ ] Soporte de impresión +- [ ] Atajos de teclado +- [ ] Optimizaciones de rendimiento +- [ ] Mejoras de UI/UX +- [ ] Temas adicionales + +--- + +### 1.0 Estable (Planificado) + +**Enfoque**: Lanzamiento listo para producción + +**Objetivo**: Q4 2026 + +**Objetivos**: +- [ ] Estabilidad de API +- [ ] Pruebas exhaustivas +- [ ] Documentación completa +- [ ] Benchmarks de rendimiento +- [ ] Auditoría de seguridad +- [ ] Firma de código para todas las plataformas +- [ ] Mecanismo de actualización automática +- [ ] Herramientas de migración + +--- + +## Solicitudes de Características + +Solicitudes populares de la comunidad: + +### Alta Prioridad + +1. **Exportar/Importar** + - Estado: 📝 Planificado para Beta + - Exportación CSV y JSON + - Importación desde otras herramientas + +2. **Reportes** + - Estado: 📝 Planificado para Beta + - Resúmenes de tiempo por proyecto/tarea/período + - Constructor de reportes personalizados + - Exportación PDF + +3. **Búsqueda Avanzada** + - Estado: 📝 Planificado para Beta + - Búsqueda global + - Filtrar por rango de fechas, etiquetas, estado + - Búsquedas guardadas + +### Prioridad Media + +4. **Temporizador Pomodoro** + - Estado: 💡 En consideración + - Temporizador integrado + - Notificaciones + +5. **Integraciones** + - Estado: 💡 En consideración + - Git, Jira/GitHub, apps de calendario + +6. **App Móvil** + - Estado: 💡 Consideración futura + - App móvil complementaria + +--- + +## Contribuir a la Hoja de Ruta + +¿Tienes ideas? ¡Nos encantaría escucharlas! + +### Cómo Contribuir + +1. **Revisar issues existentes**: [GitHub Issues](https://github.com/altaskur/OpenTimeTracker/issues) +2. **Crear nueva solicitud**: Si no se encuentra, abre un issue + +--- + +## Visión a Largo Plazo + +OpenTimeTracker busca ser: + +1. **Privacidad-Primero**: Tus datos, tu control +2. **Código Abierto**: Transparente y dirigido por la comunidad +3. **Local-Primero**: Funciona offline, siempre +4. **Amigable para Desarrolladores**: Hecho por desarrolladores, para desarrolladores +5. **Extensible**: Sistema de plugins +6. **Multiplataforma**: Soporte para Windows, macOS, Linux +7. **Cero Dependencias**: Sin servicios en la nube requeridos + +--- + +Para más detalles, consulta las secciones anteriores en inglés. diff --git a/wiki/Security.md b/wiki/Security.md new file mode 100644 index 0000000..f7b987a --- /dev/null +++ b/wiki/Security.md @@ -0,0 +1,422 @@ +# Security + +OpenTimeTracker Security Policy and Best Practices. + +For the complete security policy, see [SECURITY.md](../SECURITY.md) in the repository. + +## Quick Security Overview + +### Data Security + +✅ **What OpenTimeTracker Does**: +- Stores all data locally on your computer +- No cloud transmission +- No telemetry or analytics +- No external network requests (except update checks) +- Uses SQLite with ACID compliance + +❌ **What OpenTimeTracker Doesn't Do**: +- No data collection +- No user tracking +- No cloud sync (by design) +- No remote access + +--- + +## Your Responsibility + +As a local-first application, **you** are responsible for: + +### 1. Physical Security +- Secure your computer with password/PIN +- Lock your screen when away +- Control physical access to your device + +### 2. File System Security +- Use full-disk encryption (BitLocker, FileVault, LUKS) +- Set appropriate file permissions +- Secure database backups + +### 3. Backup Security +- Store backups in secure location +- Encrypt backups if needed +- Protect backup files like passwords + +--- + +## Best Practices + +### For Users + +1. **Enable full-disk encryption** on your OS +2. **Use strong passwords/PINs** for your computer +3. **Regular backups** to secure, encrypted location +4. **Keep app updated** for security patches +5. **Don't share database files** over insecure channels + +### For Developers + +1. **Never commit** `.env` files or secrets +2. **Use environment variables** for sensitive config +3. **Follow secure coding practices** +4. **Review dependencies** for vulnerabilities +5. **Run security scans** (SonarQube, npm audit) + +--- + +## Electron Security + +OpenTimeTracker follows Electron security best practices: + +✅ **Implemented**: +- Context isolation enabled +- Node integration disabled in renderer +- Secure IPC bridge via preload script +- Content Security Policy (CSP) +- No remote content loading + +### Security Configuration + +```javascript +// electron/src/main/main.ts +webPreferences: { + contextIsolation: true, // ✅ Enabled + nodeIntegration: false, // ✅ Disabled + sandbox: true, // ✅ Enabled + preload: path.join(__dirname, 'preload.js') +} +``` + +--- + +## Database Security + +### SQLite Security + +**File-based security**: +- Database file permissions +- Operating system access controls +- Full-disk encryption + +**What SQLite provides**: +- ACID compliance +- Transaction safety +- Data integrity checks + +**What SQLite doesn't provide**: +- Encryption at rest (use OS-level encryption) +- User authentication (single-user app) +- Network security (local-only) + +### Securing Your Database + +**Set proper permissions** (Linux/macOS): +```bash +chmod 600 ~/.config/OpenTimeTracker/data/timetracker.db +``` + +**Use OS-level encryption**: +- Windows: BitLocker +- macOS: FileVault +- Linux: LUKS + +--- + +## Reporting Security Vulnerabilities + +### ⚠️ Important: DO NOT Report Publicly + +**Do NOT** open public GitHub issues for security vulnerabilities. + +### How to Report + +**Option 1: GitHub Security Advisory** (Preferred) +1. Go to [Security tab](https://github.com/altaskur/OpenTimeTracker/security/advisories) +2. Click "Report a vulnerability" +3. Fill in details + +**Option 2: Direct Contact** +- Contact: [@altaskur](https://github.com/altaskur) on GitHub +- Subject: "SECURITY: [Brief description]" + +### What to Include + +1. **Type of vulnerability** (e.g., SQL injection, XSS, etc.) +2. **Affected files/components** +3. **Steps to reproduce** +4. **Proof of concept** (if possible) +5. **Impact assessment** +6. **Suggested fix** (if any) + +--- + +## Response Timeline + +- **Acknowledgment**: Within 3 business days +- **Assessment**: Within 7 days +- **Fix Development**: Depends on severity + - Critical: 7-14 days + - High: 14-30 days + - Medium: 30-60 days + - Low: Best effort + +--- + +## Supported Versions + +| Version | Supported | +|---------|-----------| +| Latest release (main) | ✅ Yes | +| Develop branch | ✅ Yes | +| Older releases | ❌ No | + +**Recommendation**: Always use the latest stable release. + +--- + +## Known Security Considerations + +### Data at Rest + +**Current State**: +- Data stored in plaintext SQLite file +- Protected by OS-level permissions +- No application-level encryption + +**Recommendations**: +- Use full-disk encryption (mandatory) +- Set restrictive file permissions +- Secure backup storage + +### Backups + +**Automatic Backups**: +- Stored in `{app-data}/backups/` +- Same security as main database +- User-managed (no auto-cleanup) + +**Best Practices**: +- Limit backup retention +- Secure backup location +- Encrypt external backups +- Don't store in cloud without encryption + +### Update Mechanism + +**Update Checks**: +- Checks GitHub releases API +- HTTPS connection +- No personal data transmitted + +**Security**: +- Code signing (recommended for production) +- Verify download checksums +- Update via official channels only + +--- + +## Security Updates + +When a vulnerability is confirmed: + +1. **Develop fix** privately +2. **Prepare security advisory** +3. **Release patched version** +4. **Publish advisory** with: + - Description + - Affected versions + - Fixed version + - Credit to reporter +5. **Notify users** via GitHub + +--- + +## Dependency Security + +### Regular Checks + +```bash +# Check for vulnerable dependencies +npm audit + +# Fix automatically +npm audit fix + +# Force fix (may have breaking changes) +npm audit fix --force +``` + +### In CI/CD + +Security scans run automatically: +- npm audit in workflows +- SonarQube security analysis +- Dependabot alerts + +--- + +## Privacy + +### No Data Collection + +OpenTimeTracker **NEVER** collects: +- ❌ Personal information +- ❌ Usage statistics +- ❌ Error reports (unless you share them) +- ❌ IP addresses +- ❌ Device information + +### What Data Stays Local + +Everything: +- ✅ Projects and tasks +- ✅ Time entries +- ✅ Configuration +- ✅ Preferences +- ✅ Database + +--- + +## Additional Resources + +- [OWASP Top Ten](https://owasp.org/www-project-top-ten/) +- [Electron Security](https://www.electronjs.org/docs/latest/tutorial/security) +- [SQLite Security](https://www.sqlite.org/security.html) +- [Complete SECURITY.md](../SECURITY.md) + +--- + +## Security Checklist + +### For Users + +- [ ] Enable full-disk encryption +- [ ] Use strong computer password +- [ ] Keep application updated +- [ ] Secure database backups +- [ ] Lock screen when away +- [ ] Don't share database files insecurely + +### For Developers + +- [ ] No secrets in code +- [ ] Context isolation enabled +- [ ] Node integration disabled +- [ ] Secure IPC communication +- [ ] Regular dependency updates +- [ ] Run security scans +- [ ] Review pull requests for security + +--- + +## Questions? + +For security-related questions (non-vulnerability): +- Open a regular GitHub issue +- Ask in GitHub Discussions +- Check [FAQ](FAQ.md) + +For vulnerabilities: +- Follow reporting process above +- **DO NOT** discuss publicly + +--- + +Thank you for helping keep OpenTimeTracker and its users safe! 🔒 + +--- + +# Seguridad (Español) + +Política y mejores prácticas de seguridad de OpenTimeTracker. + +Para la política de seguridad completa, consulta [SECURITY.md](../SECURITY.md) en el repositorio. + +## Resumen Rápido de Seguridad + +### Seguridad de Datos + +✅ **Lo que hace OpenTimeTracker**: +- Almacena todos los datos localmente +- Sin transmisión a la nube +- Sin telemetría ni analytics +- Sin solicitudes de red externas (excepto verificación de actualizaciones) + +❌ **Lo que NO hace OpenTimeTracker**: +- Sin recopilación de datos +- Sin seguimiento de usuario +- Sin sincronización en la nube +- Sin acceso remoto + +--- + +## Tu Responsabilidad + +Como aplicación local-first, **tú** eres responsable de: + +### 1. Seguridad Física +- Asegurar tu computadora con contraseña/PIN +- Bloquear pantalla cuando no estés +- Controlar acceso físico a tu dispositivo + +### 2. Seguridad del Sistema de Archivos +- Usar cifrado de disco completo (BitLocker, FileVault, LUKS) +- Establecer permisos de archivo apropiados +- Asegurar backups de base de datos + +### 3. Seguridad de Backups +- Almacenar backups en ubicación segura +- Cifrar backups si es necesario +- Proteger archivos de backup como contraseñas + +--- + +## Mejores Prácticas + +### Para Usuarios + +1. **Habilitar cifrado de disco completo** en tu SO +2. **Usar contraseñas fuertes** para tu computadora +3. **Backups regulares** a ubicación segura y cifrada +4. **Mantener app actualizada** para parches de seguridad +5. **No compartir archivos de base de datos** por canales inseguros + +--- + +## Reportar Vulnerabilidades de Seguridad + +### ⚠️ Importante: NO Reportar Públicamente + +**NO** abras issues públicos en GitHub para vulnerabilidades de seguridad. + +### Cómo Reportar + +**Opción 1: GitHub Security Advisory** (Preferido) +1. Ve a [Security tab](https://github.com/altaskur/OpenTimeTracker/security/advisories) +2. Haz clic en "Report a vulnerability" +3. Completa detalles + +**Opción 2: Contacto Directo** +- Contacto: [@altaskur](https://github.com/altaskur) en GitHub +- Asunto: "SECURITY: [Descripción breve]" + +--- + +## Privacidad + +### Sin Recopilación de Datos + +OpenTimeTracker **NUNCA** recopila: +- ❌ Información personal +- ❌ Estadísticas de uso +- ❌ Reportes de errores +- ❌ Direcciones IP +- ❌ Información del dispositivo + +--- + +Para más detalles, consulta las secciones anteriores en inglés o [SECURITY.md](../SECURITY.md). + +--- + +¡Gracias por ayudar a mantener OpenTimeTracker y sus usuarios seguros! 🔒 From 4aab50442e7535b0a84e043e0156cc6dc81da240 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:03:18 +0000 Subject: [PATCH 5/6] docs: update README with prominent wiki links and documentation section Co-authored-by: altaskur <105789412+altaskur@users.noreply.github.com> --- README.md | 42 +++++++++++++++++++++++++++++++++--------- 1 file changed, 33 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 37c0acc..a07ddcd 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ What is • Key Features • Quick start • + Documentation • Contributing • License

@@ -87,6 +88,29 @@ npm run dev npm run dev is the recommended and supported development command. It runs Angular and Electron together as intended. +--- + +## 📚 Documentation + +**Comprehensive documentation is available in the project wiki:** + +### 👉 **[Visit the Wiki](wiki/Home.md)** 📖 + +Quick access to key documentation: + +- 🚀 **[Getting Started](wiki/Getting-Started.md)** - Installation and first steps +- 📖 **[User Guide](wiki/Getting-Started.md)** - Complete feature guide +- 🏗️ **[Architecture](wiki/Architecture.md)** - Technical design +- 💾 **[Database Schema](wiki/Database-Schema.md)** - Data model +- 🛠️ **[Development Setup](wiki/Development-Setup.md)** - Dev environment setup +- 🔧 **[Troubleshooting](wiki/Troubleshooting.md)** - Common issues and solutions +- ❓ **[FAQ](wiki/FAQ.md)** - Frequently asked questions +- 🗺️ **[Roadmap](wiki/Roadmap.md)** - Future plans + +All documentation is available in **English** and **Spanish**. + +--- + ## 🧪 Project status ⚠️ Alpha stage @@ -99,19 +123,19 @@ Feedback, bug reports and contributions are welcome. ## 🤝 Contributing Interested in contributing? Great ❤️ -All contribution-related documentation lives outside this README to keep things clear and up to date. - -📘 CONTRIBUTING.md — setup, workflow and quality checks - -🧭 COLLABORATION.md — technical and architectural details -🛡️ SECURITY.md — how to report vulnerabilities +**📖 [Visit the Wiki](wiki/Home.md)** for comprehensive documentation. -📜 CODE_OF_CONDUCT.md — community guidelines +All contribution-related documentation lives outside this README to keep things clear and up to date: -🌐 DeepWiki — optional, supplementary documentation (secondary): +- 📘 **[CONTRIBUTING.md](CONTRIBUTING.md)** — setup, workflow and quality checks +- 🧭 **[COLLABORATION.md](COLLABORATION.md)** — technical and architectural details +- 🛡️ **[SECURITY.md](SECURITY.md)** — how to report vulnerabilities +- 📜 **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — community guidelines +- 📚 **[Project Wiki](wiki/Home.md)** — comprehensive documentation +- 🌐 **[DeepWiki](https://deepwiki.com/altaskur/OpenTimeTracker)** — optional, supplementary documentation (secondary) -Before opening a PR, please read CONTRIBUTING.md. +Before opening a PR, please read **[CONTRIBUTING.md](CONTRIBUTING.md)**. ## 📄 License From b65b52273d0a559324e176d7231f9bcda4b212e9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:29:51 +0000 Subject: [PATCH 6/6] docs: prepare wiki for GitHub Wiki migration with instructions Co-authored-by: altaskur <105789412+altaskur@users.noreply.github.com> --- README.md | 20 ++++--- WIKI_MIGRATION.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++ wiki/Home.md | 6 -- 3 files changed, 153 insertions(+), 15 deletions(-) create mode 100644 WIKI_MIGRATION.md diff --git a/README.md b/README.md index a07ddcd..34d4b31 100644 --- a/README.md +++ b/README.md @@ -94,21 +94,23 @@ It runs Angular and Electron together as intended. **Comprehensive documentation is available in the project wiki:** -### 👉 **[Visit the Wiki](wiki/Home.md)** 📖 +### 👉 **[Visit the Wiki](https://github.com/altaskur/OpenTimeTracker/wiki)** 📖 Quick access to key documentation: -- 🚀 **[Getting Started](wiki/Getting-Started.md)** - Installation and first steps -- 📖 **[User Guide](wiki/Getting-Started.md)** - Complete feature guide -- 🏗️ **[Architecture](wiki/Architecture.md)** - Technical design -- 💾 **[Database Schema](wiki/Database-Schema.md)** - Data model -- 🛠️ **[Development Setup](wiki/Development-Setup.md)** - Dev environment setup -- 🔧 **[Troubleshooting](wiki/Troubleshooting.md)** - Common issues and solutions -- ❓ **[FAQ](wiki/FAQ.md)** - Frequently asked questions -- 🗺️ **[Roadmap](wiki/Roadmap.md)** - Future plans +- 🚀 **[Getting Started](https://github.com/altaskur/OpenTimeTracker/wiki/Getting-Started)** - Installation and first steps +- 📖 **[User Guide](https://github.com/altaskur/OpenTimeTracker/wiki/Getting-Started)** - Complete feature guide +- 🏗️ **[Architecture](https://github.com/altaskur/OpenTimeTracker/wiki/Architecture)** - Technical design +- 💾 **[Database Schema](https://github.com/altaskur/OpenTimeTracker/wiki/Database-Schema)** - Data model +- 🛠️ **[Development Setup](https://github.com/altaskur/OpenTimeTracker/wiki/Development-Setup)** - Dev environment setup +- 🔧 **[Troubleshooting](https://github.com/altaskur/OpenTimeTracker/wiki/Troubleshooting)** - Common issues and solutions +- ❓ **[FAQ](https://github.com/altaskur/OpenTimeTracker/wiki/FAQ)** - Frequently asked questions +- 🗺️ **[Roadmap](https://github.com/altaskur/OpenTimeTracker/wiki/Roadmap)** - Future plans All documentation is available in **English** and **Spanish**. +> **Note**: Documentation source files are in the [`wiki/`](wiki/) folder. See [WIKI_MIGRATION.md](WIKI_MIGRATION.md) for instructions on publishing to GitHub Wiki. + --- ## 🧪 Project status diff --git a/WIKI_MIGRATION.md b/WIKI_MIGRATION.md new file mode 100644 index 0000000..0247479 --- /dev/null +++ b/WIKI_MIGRATION.md @@ -0,0 +1,142 @@ +# Migrating Documentation to GitHub Wiki + +This guide explains how to migrate the documentation from the `wiki/` folder to GitHub's native Wiki feature. + +## Prerequisites + +1. **Enable Wiki** in repository settings: + - Go to: https://github.com/altaskur/OpenTimeTracker/settings + - Scroll to "Features" section + - Check ✅ "Wikis" + +2. **Create initial page**: + - Go to: https://github.com/altaskur/OpenTimeTracker/wiki + - Click "Create the first page" + - Title: "Home" + - Content: "Documentation wiki for OpenTimeTracker" + - Click "Save Page" + +## Migration Steps + +### Step 1: Clone the Wiki Repository + +```bash +# Clone the main repository (if not already) +git clone https://github.com/altaskur/OpenTimeTracker.git +cd OpenTimeTracker + +# Clone the wiki repository (separate Git repo) +cd /tmp +git clone https://github.com/altaskur/OpenTimeTracker.wiki.git +cd OpenTimeTracker.wiki +``` + +### Step 2: Copy Wiki Files + +```bash +# Copy all markdown files from main repo to wiki repo +cp /path/to/OpenTimeTracker/wiki/*.md . + +# Verify files are copied +ls -la +``` + +### Step 3: Adjust Internal Links + +Wiki files need to have links adjusted (remove `wiki/` prefix): + +```bash +# Find and replace wiki/ prefix in links +# macOS/Linux: +sed -i 's|](wiki/|](|g' *.md +sed -i 's|](../wiki/|](|g' *.md + +# Or manually edit each file to change: +# [Link](wiki/Page.md) → [Link](Page.md) +# [Link](../wiki/Page.md) → [Link](Page.md) +``` + +### Step 4: Commit and Push + +```bash +git add . +git commit -m "docs: migrate documentation to GitHub Wiki" +git push origin master +``` + +### Step 5: Verify + +Visit https://github.com/altaskur/OpenTimeTracker/wiki to verify: +- All pages are visible +- Navigation works +- Links between pages work correctly + +### Step 6: Clean Up Main Repository (Optional) + +If you want to remove wiki/ from main repo after migration: + +```bash +cd /path/to/OpenTimeTracker +git rm -r wiki/ +git commit -m "docs: remove wiki folder (migrated to GitHub Wiki)" +git push +``` + +--- + +## Alternative: Keep Both + +You can keep documentation in both places: + +**Main Repo (`wiki/` folder)**: +- ✅ Versioned with code +- ✅ PR review process +- ✅ Works offline +- ✅ Clone with repo + +**GitHub Wiki** (separate repo): +- ✅ Native wiki UI +- ✅ Easy web editing +- ✅ Built-in search + +**Sync strategy**: Manually copy from `wiki/` to GitHub Wiki when making documentation updates. + +--- + +## Files to Migrate + +The following files are ready to migrate: + +- `Home.md` - Main wiki entry point +- `Getting-Started.md` - Installation and setup +- `Architecture.md` - Technical architecture +- `Database-Schema.md` - Database documentation +- `Development-Setup.md` - Developer guide +- `Build-and-Deployment.md` - Build process +- `Troubleshooting.md` - Common issues +- `FAQ.md` - Frequently asked questions +- `Contributing.md` - Contribution guide +- `Security.md` - Security policy +- `Roadmap.md` - Future plans +- `README.md` - Wiki index + +--- + +## Troubleshooting + +### Wiki not enabled +- Check repository settings → Features → Wikis must be checked + +### Permission denied on push +- Ensure you have write access to the repository +- Check GitHub credentials are configured + +### Links broken after migration +- Verify all internal links use format `[Text](Page.md)` without `wiki/` prefix +- GitHub Wiki uses page names, not file paths + +--- + +## Questions? + +For issues with migration, contact the repository maintainer or open an issue. diff --git a/wiki/Home.md b/wiki/Home.md index 9cf29e4..d0d644f 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -37,7 +37,6 @@ OpenTimeTracker is a **free, open-source, local-first time tracking application* ### For Users - **[Getting Started](Getting-Started.md)** - Installation and first steps -- **[User Guide](User-Guide.md)** - Complete feature guide and usage - **[Troubleshooting](Troubleshooting.md)** - Common issues and solutions - **[FAQ](FAQ.md)** - Frequently asked questions @@ -46,14 +45,12 @@ OpenTimeTracker is a **free, open-source, local-first time tracking application* - **[Development Setup](Development-Setup.md)** - Setting up your development environment - **[Architecture](Architecture.md)** - Technical design and system architecture - **[Database Schema](Database-Schema.md)** - Data model and relationships -- **[API Documentation](API-Documentation.md)** - IPC API and service interfaces - **[Contributing Guide](Contributing.md)** - How to contribute to the project - **[Build & Deployment](Build-and-Deployment.md)** - Building and packaging ### Project Information - **[Roadmap](Roadmap.md)** - Future plans and feature requests -- **[Release Notes](Release-Notes.md)** - Version history and changes - **[Security](Security.md)** - Security policy and best practices --- @@ -111,7 +108,6 @@ OpenTimeTracker es una **aplicación de seguimiento de tiempo gratuita, de códi ### Para Usuarios - **[Comenzar](Getting-Started.md#guía-de-inicio-español)** - Instalación y primeros pasos -- **[Guía de Usuario](User-Guide.md#guía-de-usuario-español)** - Guía completa de características - **[Solución de Problemas](Troubleshooting.md#solución-de-problemas-español)** - Problemas comunes y soluciones - **[Preguntas Frecuentes](FAQ.md#preguntas-frecuentes-español)** - FAQ en español @@ -120,14 +116,12 @@ OpenTimeTracker es una **aplicación de seguimiento de tiempo gratuita, de códi - **[Configuración de Desarrollo](Development-Setup.md#configuración-de-desarrollo-español)** - Configurar entorno de desarrollo - **[Arquitectura](Architecture.md#arquitectura-español)** - Diseño técnico y arquitectura del sistema - **[Esquema de Base de Datos](Database-Schema.md)** - Modelo de datos y relaciones -- **[Documentación de API](API-Documentation.md)** - API IPC e interfaces de servicio - **[Guía de Contribución](Contributing.md)** - Cómo contribuir al proyecto - **[Compilación y Despliegue](Build-and-Deployment.md#compilación-y-despliegue-español)** - Compilar y empaquetar ### Información del Proyecto - **[Hoja de Ruta](Roadmap.md)** - Planes futuros y solicitudes de características -- **[Notas de Versión](Release-Notes.md)** - Historial de versiones y cambios - **[Seguridad](Security.md)** - Política de seguridad y mejores prácticas ---