From 2262883cc54ba1715f2c6528c4b098ae6548f343 Mon Sep 17 00:00:00 2001 From: altaskur <105789412+altaskur@users.noreply.github.com> Date: Wed, 4 Feb 2026 20:37:27 +0100 Subject: [PATCH 1/2] docs(readme): clarify scope and dev instructions --- CONTRIBUTING.md | 44 +++++++-- README.md | 237 ++++++++++++---------------------------------- package-lock.json | 4 +- 3 files changed, 100 insertions(+), 185 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8b638b..8a08261 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Thank you for your interest in contributing to OpenTimeTracker! This guide will help you get started with contributing to the project. -*Versión en español más abajo / Spanish version below* +_Versión en español más abajo / Spanish version below_ --- @@ -21,6 +21,7 @@ Thank you for your interest in contributing to OpenTimeTracker! This guide will ## Getting Started OpenTimeTracker is built with: + - **Angular 21** for the UI - **Electron 37** for the desktop application - **Prisma/SQLite** for data persistence @@ -39,21 +40,23 @@ The main branch is `main`, and active development happens on the `develop` branc ### Installation 1. Fork and clone the repository: + ```bash git clone https://github.com/YOUR_USERNAME/OpenTimeTracker.git cd OpenTimeTracker ``` 2. Install dependencies: + ```bash npm install npm run prisma:generate ``` 3. Run the application: + ```bash - npm start # Angular dev server on port 4200 - npm run dev # Build and run Electron in dev mode + npm run dev # Build and run Angular + Electron in dev mode ``` ## Development Workflow @@ -61,11 +64,13 @@ The main branch is `main`, and active development happens on the `develop` branc ### Creating a Branch Always branch from `develop` with the appropriate prefix: + - `feat/` - New features - `fix/` - Bug fixes - `chore/` - Maintenance tasks Example: + ```bash git checkout develop git pull origin develop @@ -87,6 +92,7 @@ type(scope): description Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` Examples: + - `feat(projects): add project archiving functionality` - `fix(calendar): correct date calculation in week view` - `docs(readme): update installation instructions` @@ -139,11 +145,12 @@ Your pull request should include: We use SonarQube for static code analysis. To run it locally: 1. Start SonarQube: + ```bash docker-compose up -d # First start takes ~2 minutes ``` -2. Access SonarQube at http://localhost:9000 +2. Access SonarQube at - Default credentials: `admin` / `admin` - Change password on first login @@ -152,16 +159,19 @@ We use SonarQube for static code analysis. To run it locally: - Copy the token 4. Create a `.env` file: + ``` SONAR_TOKEN=your_generated_token_here ``` 5. Run the analysis: + ```bash npm run sonar:check ``` 6. Stop SonarQube: + ```bash docker-compose down ``` @@ -171,11 +181,13 @@ We use SonarQube for static code analysis. To run it locally: When modifying the Prisma schema: 1. Create a migration: + ```bash npx prisma migrate dev --name description_of_change ``` 2. Update the production template: + ```bash npm run prisma:template ``` @@ -194,12 +206,14 @@ When modifying the Prisma schema: ### Adding Translations Add new strings to both language files: + - `src/assets/i18n/en.json` - `src/assets/i18n/es.json` ### Accessibility Ensure your UI changes: + - Have proper labels for form controls - Maintain visible focus indicators - Meet color contrast requirements @@ -236,12 +250,13 @@ Gracias por tu interés en contribuir a OpenTimeTracker. Esta guía te ayudará - [Estándares de Calidad](#estándares-de-calidad) - [Cambios en la Base de Datos](#cambios-en-la-base-de-datos) - [UI e Internacionalización](#ui-e-internacionalización) -- [Seguridad](#seguridad-1) +- [Seguridad](#seguridad) - [Obtener Ayuda](#obtener-ayuda) ## Comenzando OpenTimeTracker está construido con: + - **Angular 21** para la interfaz - **Electron 37** para la aplicación de escritorio - **Prisma/SQLite** para persistencia de datos @@ -260,21 +275,23 @@ La rama principal es `main`, y el desarrollo activo ocurre en la rama `develop`. ### Instalación 1. Haz fork y clona el repositorio: + ```bash git clone https://github.com/TU_USUARIO/OpenTimeTracker.git cd OpenTimeTracker ``` 2. Instala las dependencias: + ```bash npm install npm run prisma:generate ``` 3. Ejecuta la aplicación: + ```bash - npm start # Servidor Angular en puerto 4200 - npm run dev # Construye y ejecuta Electron en modo dev + npm run dev # Construye y ejecuta Angular + Electron en modo dev ``` ## Flujo de Trabajo @@ -282,11 +299,13 @@ La rama principal es `main`, y el desarrollo activo ocurre en la rama `develop`. ### Crear una Rama Siempre crea ramas desde `develop` con el prefijo apropiado: + - `feat/` - Nuevas características - `fix/` - Corrección de errores - `chore/` - Tareas de mantenimiento Ejemplo: + ```bash git checkout develop git pull origin develop @@ -308,6 +327,7 @@ tipo(alcance): descripción Tipos: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` Ejemplos: + - `feat(proyectos): añadir funcionalidad de archivo de proyectos` - `fix(calendario): corregir cálculo de fecha en vista semanal` - `docs(readme): actualizar instrucciones de instalación` @@ -360,11 +380,12 @@ Tu pull request debe incluir: Usamos SonarQube para análisis estático de código. Para ejecutarlo localmente: 1. Inicia SonarQube: + ```bash docker-compose up -d # El primer inicio tarda ~2 minutos ``` -2. Accede a SonarQube en http://localhost:9000 +2. Accede a SonarQube en - Credenciales por defecto: `admin` / `admin` - Cambia la contraseña en el primer inicio @@ -373,16 +394,19 @@ Usamos SonarQube para análisis estático de código. Para ejecutarlo localmente - Copia el token 4. Crea un archivo `.env`: + ``` SONAR_TOKEN=tu_token_generado_aqui ``` 5. Ejecuta el análisis: + ```bash npm run sonar:check ``` 6. Detén SonarQube: + ```bash docker-compose down ``` @@ -392,11 +416,13 @@ Usamos SonarQube para análisis estático de código. Para ejecutarlo localmente Al modificar el esquema de Prisma: 1. Crea una migración: + ```bash npx prisma migrate dev --name descripcion_del_cambio ``` 2. Actualiza la plantilla de producción: + ```bash npm run prisma:template ``` @@ -415,12 +441,14 @@ Al modificar el esquema de Prisma: ### Añadir Traducciones Añade nuevas cadenas a ambos archivos de idioma: + - `src/assets/i18n/en.json` - `src/assets/i18n/es.json` ### Accesibilidad Asegúrate de que tus cambios de UI: + - Tengan etiquetas apropiadas para controles de formulario - Mantengan indicadores de foco visibles - Cumplan requisitos de contraste de color diff --git a/README.md b/README.md index 88cb8dd..37c0acc 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,13 @@

OpenTimeTracker

- Free and open source time tracking application for developers and teams + Free and open-source, local-first time tracking app for developers and small teams.

- Features • - Installation • - Development • + What is • + Key Features • + Quick start • Contributing • License

@@ -23,222 +23,109 @@ Coverage - - Bugs - - - Vulnerabilities + + DeepWiki -

- -

- Angular 21 - Electron 37 - Prisma - SQLite + License: GPL v3

--- -## ✨ Features +## What is OpenTimeTracker? -- 📊 **Project Management** - Create and organize projects with full CRUD operations -- ✅ **Task Tracking** - Manage tasks with statuses, tags, and time estimates -- ⏱️ **Time Entries** - Log work time with notes and date tracking -- 📅 **Calendar View** - Visual calendar to see your time entries -- 🏷️ **Tags & Categories** - Organize tasks with customizable tags -- 🌙 **Dark Mode** - Beautiful dark theme with Aura Black preset -- 🌐 **Multi-language** - Support for English and Spanish -- 💾 **Local Database** - All data stored locally with SQLite -- 🔄 **Backup System** - Automatic backup on shutdown +OpenTimeTracker is a **desktop time-tracking application** built with **Angular + Electron**, designed for people who want: -## 📥 Installation +- full control over their data +- no SaaS subscriptions +- a fast, offline-first experience -### Download +All data is stored **locally** using SQLite. -Download the latest installer for your platform from the [Releases](https://github.com/altaskur/OpenTimeTracker/releases) page: - -| Platform | Format | Architecture | -| -------- | ----------------------- | -------------------------- | -| Windows | `.exe` (NSIS installer) | x64 | -| macOS | `.dmg` | x64, arm64 (Apple Silicon) | -| Linux | `.AppImage`, `.deb` | x64 | +--- -### Build from Source +## ✨ Key Features -```bash -# Clone the repository -git clone https://github.com/altaskur/OpenTimeTracker.git -cd OpenTimeTracker +- 📊 Project and task management +- ⏱️ Time tracking with notes and dates +- 📅 Calendar view of your activity +- 🏷️ Tags and task categorization +- 🌙 Dark mode by default +- 🌐 English and Spanish support +- 💾 Local SQLite database +- 🔄 Automatic backups on shutdown -# Install dependencies -npm install - -# Generate Prisma client -npm run prisma:generate +--- -# Build and run -npm run dev -``` +## 🚀 Quick start -## 🛠️ Development +### Download (recommended) -### Prerequisites +Download the latest version for your platform from **Releases**: -- Node.js 20+ -- npm 10+ +👉 -### Commands +Supported platforms: -| Command | Description | -| ----------------------- | ------------------------------------ | -| `npm start` | Start Angular dev server (port 4200) | -| `npm run dev` | Build and run Electron app | -| `npm run build` | Production build | -| `npm run dist` | Generate installer for current OS | -| `npm run dist:win` | Generate Windows installer | -| `npm run dist:mac` | Generate macOS installer (DMG) | -| `npm run dist:linux` | Generate Linux installers | -| `npm test` | Run Angular tests | -| `npm run test:electron` | Run Electron tests | -| `npm run lint` | Run ESLint | -| `npm run sonar:check` | Run tests + SonarQube analysis | +- Windows (`.exe`) +- macOS (`.dmg`, Intel & Apple Silicon) +- Linux (`.AppImage`, `.deb`) -### Database +--- -The app uses **SQLite with Prisma ORM**. After modifying the schema: +### Run from source (development) ```bash -# Create migration -npx prisma migrate dev --name your_migration_name - -# Update production template -npm run prisma:template -``` +git clone https://github.com/altaskur/OpenTimeTracker.git +cd OpenTimeTracker -### Project Structure - -```text -OpenTimeTracker/ -├── electron/src/ # Electron main process -│ ├── main/ # Window management -│ ├── preload/ # IPC bridge -│ └── services/ # Database & handlers -├── src/app/ # Angular application -│ ├── components/ # Shared components -│ ├── pages/ # Route pages -│ └── services/ # Angular services -├── prisma/ # Database schema & migrations -└── scripts/ # Build scripts +npm install +npm run prisma:generate +npm run dev ``` -## ⌨️ Keyboard Shortcuts - -| Shortcut | Action | -| -------------- | ----------------- | -| `Ctrl+1` | Go to Home | -| `Ctrl+2` | Go to Calendar | -| `Ctrl+3` | Go to Projects | -| `Ctrl+N` | New time entry | -| `Ctrl+Shift+N` | New project | -| `Ctrl+T` | Toggle dark mode | -| `F11` | Toggle fullscreen | - -## 🔍 Code Quality - -This project uses **SonarQube** for static code analysis. Before contributing to `develop`, you must pass the local SonarQube analysis. - -### Prerequisites for Development - -- Docker & Docker Compose - -### Local SonarQube Setup - -1. **Start SonarQube** (first time takes ~2 minutes): - - ```bash - docker-compose up -d - ``` - -2. **Access SonarQube** at - - Default credentials: `admin` / `admin` - - You'll be prompted to change the password on first login - -3. **Generate a token**: - - Go to: My Account → Security → Generate Tokens - - Create a token and copy it +npm run dev is the recommended and supported development command. +It runs Angular and Electron together as intended. -4. **Create a `.env` file** in the project root: +## 🧪 Project status - ``` - SONAR_TOKEN=your_generated_token_here - ``` +⚠️ Alpha stage -5. **Run the full analysis** (tests + coverage + SonarQube): +OpenTimeTracker is under active development. +Features, UI and internal APIs may change. - ```bash - npm run sonar:check - ``` - -6. **Stop SonarQube** when done: - - ```bash - docker-compose down - ``` - -> ⚠️ **Important**: The pre-push hook automatically runs `sonar:check` for all feature branches (`feat/*`, `fix/*`, `chore/*`, etc.). Your push will be blocked if the analysis fails. +Feedback, bug reports and contributions are welcome. ## 🤝 Contributing -Contributions are welcome! We appreciate your interest in improving OpenTimeTracker. +Interested in contributing? Great ❤️ +All contribution-related documentation lives outside this README to keep things clear and up to date. -### Getting Started +📘 CONTRIBUTING.md — setup, workflow and quality checks -Please read our contributing guidelines to get started: +🧭 COLLABORATION.md — technical and architectural details -- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Comprehensive guide for contributors (includes setup, workflow, and testing) -- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Community standards and expectations -- **[SECURITY.md](SECURITY.md)** - How to report security vulnerabilities -- **[COLLABORATION.md](COLLABORATION.md)** - Additional workflow and technical details +🛡️ SECURITY.md — how to report vulnerabilities -### Quick Start +📜 CODE_OF_CONDUCT.md — community guidelines -1. Fork the repository -2. Create your feature branch from `develop` (`git checkout -b feat/AmazingFeature`) -3. Make your changes following our [coding standards](CONTRIBUTING.md) -4. Run tests and quality checks: `npm run lint && npm test && npm run sonar:check` -5. Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/) -6. Push to your branch (`git push origin feat/AmazingFeature`) -7. Open a Pull Request against the `develop` branch +🌐 DeepWiki — optional, supplementary documentation (secondary): -### Questions or Issues? - -- Check existing [issues](https://github.com/altaskur/OpenTimeTracker/issues) -- Use our [issue templates](.github/ISSUE_TEMPLATE) for bug reports or feature requests -- Follow the [pull request template](.github/pull_request_template.md) when submitting PRs - -Thank you for contributing! 🚀 +Before opening a PR, please read CONTRIBUTING.md. ## 📄 License -This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details. +This project is licensed under the GNU General Public License v3.0. -This means: +You are free to: -- ✅ You can use, modify, and distribute this software -- ✅ You must keep it open source -- ✅ You must include the original copyright and license -- ✅ Any derivative work must use the same license +use, study and modify the software -## 👤 Author +redistribute it under the same license -**altaskur** +See the LICENSE file for details. -- GitHub: [@altaskur](https://github.com/altaskur) - ---- +## 👤 Author -

- Made with ❤️ by altaskur -

+altaskur +GitHub: diff --git a/package-lock.json b/package-lock.json index c0a1b25..0f52a1c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "open-time-tracker", - "version": "1.0.0-alpha.1", + "version": "1.0.0-alpha.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "open-time-tracker", - "version": "1.0.0-alpha.1", + "version": "1.0.0-alpha.3", "hasInstallScript": true, "license": "GPL-3.0", "dependencies": { From d58d00192f64d27ee654e5bc181e0be7df2e8830 Mon Sep 17 00:00:00 2001 From: altaskur <105789412+altaskur@users.noreply.github.com> Date: Wed, 4 Feb 2026 21:39:36 +0100 Subject: [PATCH 2/2] docs(sonarqube): complete setup guide with wizard steps --- CONTRIBUTING.md | 102 +++++++++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 2 +- 2 files changed, 103 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a08261..7642270 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -176,6 +176,57 @@ We use SonarQube for static code analysis. To run it locally: docker-compose down ``` +### SonarQube Local Project Setup + +**Step 1 of 2: Create a local project** + +1. In SonarQube, click "Create a local project" +2. Fill in the project details: + - **Project display name**: `OpenTimeTracker` + - **Project key**: `altaskur_OpenTimeTracker` (must match `sonar-project.properties`) + - **Main branch name**: `develop` +3. Click "Next" + +**Step 2 of 2: Set up project for Clean as You Code** + +1. Choose your baseline for new code: + - Recommended: **Previous version** (default option) + - This defines what SonarQube considers as "new code" for analysis +2. Click "Create project" + +**Analysis Method** + +1. On the "How do you want to analyze your repository?" screen +2. Select **"Locally"** + +**Token Generation** + +1. In the "Analyze your project" screen: + - Generate a **Project Analysis Token** + - Give it a descriptive name (e.g., `local-analysis`) + - Click "Generate" +2. Copy the generated token + +3. Add the token to `.env` (do not commit it): + + ``` + SONAR_TOKEN=your_generated_token_here + ``` + +4. Run the analysis: + + ```bash + npm run sonar:check + ``` + +### SonarQube Troubleshooting + +- Ensure the SonarQube token is set in the `.env` file. +- Confirm the project key matches `sonar-project.properties`. +- If you see a version warning, update the SonarQube image in `docker-compose.yml`. +- For upgrades, follow the 24.12 path or reset Docker volumes. +- The pre-push hook requires `sonar:check` and a running SonarQube instance. + ## Database Changes When modifying the Prisma schema: @@ -411,6 +462,57 @@ Usamos SonarQube para análisis estático de código. Para ejecutarlo localmente docker-compose down ``` +### Configuración del proyecto local en SonarQube + +**Paso 1 de 2: Crear un proyecto local** + +1. En SonarQube, haz clic en "Create a local project" +2. Completa los detalles del proyecto: + - **Project display name**: `OpenTimeTracker` + - **Project key**: `altaskur_OpenTimeTracker` (debe coincidir con `sonar-project.properties`) + - **Main branch name**: `develop` +3. Haz clic en "Next" + +**Paso 2 de 2: Configurar proyecto para Clean as You Code** + +1. Elige tu baseline para código nuevo: + - Recomendado: **Previous version** (opción por defecto) + - Esto define qué considera SonarQube como "código nuevo" para el análisis +2. Haz clic en "Create project" + +**Método de Análisis** + +1. En la pantalla "How do you want to analyze your repository?" +2. Selecciona **"Locally"** + +**Generación de Token** + +1. En la pantalla "Analyze your project": + - Genera un **Project Analysis Token** + - Dale un nombre descriptivo (ej., `local-analysis`) + - Haz clic en "Generate" +2. Copia el token generado + +3. Añade el token a `.env` (no lo subas al repositorio): + + ``` + SONAR_TOKEN=tu_token_generado_aqui + ``` + +4. Ejecuta el análisis: + + ```bash + npm run sonar:check + ``` + +### Solución de problemas de SonarQube + +- Asegúrate de que el token de SonarQube esté en el archivo `.env`. +- Confirma que la clave del proyecto coincida con `sonar-project.properties`. +- Si aparece una advertencia de versión, actualiza la imagen de SonarQube en `docker-compose.yml`. +- Para actualizaciones, sigue la ruta 24.12 o reinicia los volúmenes de Docker. +- El pre-push requiere `sonar:check` y que SonarQube esté en ejecución. + ## Cambios en la Base de Datos Al modificar el esquema de Prisma: diff --git a/docker-compose.yml b/docker-compose.yml index fedf891..59ebc7c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,6 @@ services: sonarqube: - image: sonarqube:lts-community + image: sonarqube:24.12.0.100206-community container_name: sonarqube depends_on: - sonarqube-db