# Contributing

Thanks for taking the time to contribute! The number-one priority of this repository is **accuracy**, so please back up any calendar claim with a reliable source and any code change with tests.

## How you can help

- **Improve the documentation:** Please keep the English (`docs/en`) and Persian (`docs/fa`) pages in sync. If you're only comfortable writing in one of the two languages, just mention it in your pull request and someone else can help translate.
- **Add a new programming language** to [`implementations/`](https://goudarzjafari.com/persian-calendar/implementations/):
  1. Port the algorithm from [`docs/en/03-algorithm.md`](https://goudarzjafari.com/persian-calendar/algorithm/). Follow your language's idiomatic naming and style,
     but keep the same core API: leap year check, days in month, date validation, to/from JDN, to/from Gregorian, day of week (0 = Saturday), and day of year.
  2. Write a test suite that reads `data/years.csv` and `data/test-vectors.csv`, round-trips every single day from 1178 to 3000 AP, and tests input validation
     (you can model it after any of the existing language tests).
  3. Add a CI job to [`.github/workflows/test.yml`](https://github.com/Goudarz/PersianCalendar/blob/main/.github/workflows/test.yml) and add your language to [`implementations/README.md`](https://goudarzjafari.com/persian-calendar/implementations/).
- **Evaluate another library:** Add a test runner to [`tools/library-evaluation`](https://goudarzjafari.com/persian-calendar/tools/library-evaluation/) that outputs `results/<library>_<version>.txt`,
  run `cargo run --release -- score-libraries` inside `tools/calendar-data`, and update [page 6 of the guide](https://goudarzjafari.com/persian-calendar/languages-and-libraries/).
- **Report bugs upstream** to library maintainers and link the issue in the docs.

## A few ground rules

- Any statement about how the calendar works needs a verifiable source (an official University of Tehran Calendar Center publication, a peer-reviewed paper, CLDR, or reproducible code).
- Never edit the files in `data/` by hand. Instead, update [`tools/calendar-data`](https://goudarzjafari.com/persian-calendar/tools/calendar-data/) and regenerate them:
  `cd tools/calendar-data && cargo run --release`. CI runs `cargo run --release -- --check` to make sure they stay in sync.
- Make sure all tests pass locally before opening a pull request.
- For holidays: keep official public holidays, non-holiday observances, and different countries/regions clearly separated, and always cite your source.
- Keep the tone practical, objective, and developer-focused.

---

Page: https://goudarzjafari.com/persian-calendar/contributing/
License: text CC BY 4.0, code MIT, data CC0 1.0. Version 1.0.0 of https://github.com/Goudarz/PersianCalendar
