# Contributing

Thank you for helping improve the Restaurant Manager Workbook. It is a free
tool for small restaurants, so please keep it simple, honest and offline.

## How to contribute

1. **Talk first for big changes.** For a new feature or a change to how data
   is stored, open an issue describing the problem and the plan before you
   write code. Small fixes (a wrong label, a broken check, a typo) can go
   straight to a pull request.
2. **Work on a branch** from `main`. Keep changes small and focused — one
   change per pull request.
3. **Test before submitting.** Run the test suites described in
   [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and say which ones you ran and
   what passed. Do not submit untested changes to the workbook file.
4. **Describe the change plainly** in the pull request: what it does, why it
   is needed, what you tested, and any honest limits (what you could not
   test, what still needs a real phone or a real provider).
5. **Update the docs** when behaviour changes: the User Guide for anything a
   restaurant owner will see, the data-format doc for any change to the JSON
   file, the ZATCA doc for anything about e-invoicing, and CHANGELOG.md.

## Rules every contribution must follow

### No brand names

Never add a chain, delivery-app, product, or payment brand name to the app,
the site or the docs. Use category terms only, for example:

- "delivery apps" (not a delivery company's name)
- "national debit card network"
- "international card networks"
- "mobile wallet payments"
- "government e-payment system"

This applies to code, labels, lists, examples, screenshots and docs. Old
brand names stored in a user's data file are renamed to these generic
categories automatically when the file loads — do not reintroduce them.

### No personal data

Never add real personal health, family or financial details, and never add
real business data (real restaurant names, real VAT numbers, real invoices).
Use the demo business for examples, and label demo figures as demo data.
The demo figures in the docs (for example E001 October net 9,096.87 and
INV-00001 84.53) are sample data, not real records.

### Keep it offline-first and single-file

- The workbook is one HTML file (`app.html`). Do not split it into modules
  and do not add a build step.
- No external resources: no web fonts, no scripts or styles from other
  sites, no network calls. Everything the app needs must be inside the file.
- No account, no sign-up, no tracking. Nothing the app does may send user
  data anywhere.
- New fields must be optional with a sensible default, so older data files
  keep loading.
- Risky behaviour must be opt-in and off by default, clearly labelled.

### Keep it plain and honest

- Write in plain, simple English. Short labels. The user is a restaurant
  owner, not a developer.
- Do not claim what is not verified. If something is an estimate, say so
  where it appears. If something is untested on a real phone, say so.
- Never silently discard user data. A file from an older version must load;
  a file from a newer version must load what it can and warn about the rest.

## Code style

- Match the style already in `app.html`.
- Keep the 19 modules and the menu order unchanged. New features live inside
  their existing section, behind a filter, toggle or compact block — do not
  add a new top-level tab.
- Use the app's own plain-word tooltips for jargon (for example, explain
  weighted-average cost in plain words where it appears).
- Arabic strings go through the existing translation dictionary; new strings
  in English only are acceptable, with the English fallback — but do not
  claim the app is fully translated when it is not.

## Licence

By contributing, you agree your work will be released under the MIT licence
(see [LICENSE](LICENSE)).