EverShelf/CONTRIBUTING.md

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:

   git clone https://github.com/YOUR_USERNAME/dispensa.git
   cd dispensa
   

3. Create a branch from develop:

   git checkout develop
   git checkout -b feature/your-feature-name
   

4. Set up your development environment:

   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

{
  "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 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:

# 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.