Skip to main content
Contents

Project

Contributing

1 min readUpdated

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.

  • 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/:
    1. Port the algorithm from docs/en/03-algorithm.md. 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 and add your language to implementations/README.md.
  • Evaluate another library: Add a test runner to 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.
  • Report bugs upstream to library maintainers and link the issue in the docs.
  • 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 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.