feat: v1.1.0 - Docker, i18n, setup wizard, rate limiting, OpenAPI

New features: - Docker support (Dockerfile + docker-compose.yml) - GitHub Actions CI pipeline (PHP lint, JS lint, Docker build, i18n validation) - Internationalization system with 3 languages (it, en, de) and 347 translation keys - First-run setup wizard (4-step configuration) - File-based API rate limiting (120/15/5 req/min tiers) - OpenAPI 3.1.0 specification for all 43 API endpoints - CONTRIBUTING.md with translation and development guide - Screenshots directory placeholder Modified: - README.md: Docker badges, install instructions, translations section - api/index.php: rate limiting middleware - assets/js/app.js: i18n system, setup wizard, t() function - assets/css/style.css: setup wizard styles - index.html: data-i18n attributes, setup wizard overlay, language settings - .gitignore: rate_limits exclusion
2026-04-10 06:03:11 +00:00
parent e0956c6043
commit d13f744aea
16 changed files with 2993 additions and 102 deletions
@@ -0,0 +1,141 @@
+# Contributing to Dispensa Manager
+
+Thank you for your interest in contributing! This guide will help you get started.
+
+## 🚀 Getting Started
+
+1. **Fork** the repository
+2. **Clone** your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/dispensa.git
+   cd dispensa
+   ```
+3. **Create a branch** from `develop`:
+   ```bash
+   git checkout develop
+   git checkout -b feature/your-feature-name
+   ```
+4. **Set up** your development environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys
+   php -S localhost:8080
+   ```
+
+## 📐 Project Structure
+
+```
+├── index.html              # Single-page app (all HTML)
+├── api/
+│   ├── index.php           # API router + all endpoint functions
+│   ├── database.php        # SQLite schema + migrations
+│   └── cron_smart_shopping.php
+├── assets/
+│   ├── js/app.js           # All application JavaScript
+│   └── css/style.css       # All styles
+├── translations/           # i18n translation files
+│   ├── it.json             # Italian (base language)
+│   ├── en.json             # English
+│   └── ...
+└── data/                   # Runtime data (gitignored)
+```
+
+## 🌍 Contributing Translations
+
+Translations are one of the easiest ways to contribute! Each language is a single JSON file in the `translations/` directory.
+
+### Adding a new language
+
+1. Copy `translations/it.json` (the base language)
+2. Rename it to your language code (e.g., `fr.json`, `de.json`, `es.json`)
+3. Translate all the values (keep the keys unchanged)
+4. Submit a Pull Request
+
+### Translation file format
+
+```json
+{
+  "app.title": "Dispensa Manager",
+  "nav.dashboard": "Dashboard",
+  "nav.inventory": "Inventario",
+  ...
+}
+```
+
+**Rules:**
+- Keys are in English, dot-separated (`section.key`)
+- Values are the translated strings
+- Keep `{0}`, `{1}` placeholders — they are filled dynamically
+- Don't translate brand names (Bring!, Gemini, etc.)
+- The CI pipeline will check your file for missing keys
+
+### Language codes
+
+Use [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) two-letter codes:
+`it`, `en`, `de`, `fr`, `es`, `pt`, `nl`, `pl`, `ru`, `ja`, `zh`, `ko`, etc.
+
+## 🔧 Development Guidelines
+
+### Code Style
+- **PHP**: PSR-12 compatible, use type hints where practical
+- **JavaScript**: No build tools, vanilla ES6+, single-file architecture
+- **CSS**: Mobile-first, use CSS custom properties from `:root`
+- **Comments**: English only, concise
+
+### Commits
+- Use descriptive commit messages
+- Reference issue numbers when applicable: `Fix #42: barcode scanner timeout`
+- Keep commits focused on a single change
+
+### Branching
+- `main` — stable releases only
+- `develop` — active development (PRs target here)
+- `feature/*` — new features
+- `fix/*` — bug fixes
+- `i18n/*` — translation contributions
+
+## 🧪 Testing
+
+Before submitting a PR:
+
+```bash
+# Check PHP syntax
+php -l api/index.php
+php -l api/database.php
+
+# Check JS syntax
+node -c assets/js/app.js
+
+# Validate translation files
+python3 -c "import json; json.load(open('translations/it.json'))"
+
+# Test Docker build
+docker build -t dispensa-test .
+```
+
+## 📝 Pull Request Process
+
+1. Ensure your code passes all CI checks
+2. Update `CHANGELOG.md` if applicable
+3. Target the `develop` branch
+4. Provide a clear description of your changes
+5. Link any related issues
+
+## 🐛 Reporting Bugs
+
+Open an issue with:
+- Steps to reproduce
+- Expected vs. actual behavior
+- Browser/device information
+- Screenshots if applicable
+
+## 💡 Feature Requests
+
+Open an issue with the `enhancement` label. Describe:
+- The problem you're trying to solve
+- Your proposed solution
+- Any alternatives you've considered
+
+## 📄 License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).