# Contributing Guide

## Purpose
This project is a lightweight PHP template shell. Contributions should preserve simplicity, readability, and security.

## Workflow
1. Create a feature branch from main.
2. Keep changes focused to one concern per pull request.
3. Prefer small, reviewable commits with clear messages.
4. Rebase or merge latest main before opening PR.

## Change Types
1. UI change: update PHP fragment(s) plus CSS/JS as needed.
2. Routing change: update route whitelist and navigation links together.
3. Behavior change: document expected behavior in docs and testing notes.

## Coding Rules
1. Escape dynamic PHP output with `htmlspecialchars(..., ENT_QUOTES)`.
2. Keep route keys alphanumeric with underscore or dash.
3. Do not add inline script unless page-specific and justified.
4. Prefer reusable CSS classes over repeated inline styles.
5. Keep global logic in `assets/app.js` and global styles in `assets/app.css`.

## Pull Request Checklist
1. New/updated route works in full load and AJAX mode.
2. Sidebar active state and breadcrumb label are correct.
3. Browser back/forward still works.
4. Mobile sidebar open/close still works.
5. No obvious console errors in changed flows.
6. Docs updated when behavior changes.

## Definition of Done
1. Change is functionally correct.
2. Security and testing checklist items are completed.
3. Documentation is updated.
4. Reviewer can understand the change from PR description alone.