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.
How you can help
Link to section: 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/:- 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. - Write a test suite that reads
data/years.csvanddata/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). - Add a CI job to
.github/workflows/test.ymland add your language toimplementations/README.md.
- Port the algorithm from
- Evaluate another library: Add a test runner to
tools/library-evaluationthat outputsresults/<library>_<version>.txt, runcargo run --release -- score-librariesinsidetools/calendar-data, and update page 6 of the guide. - Report bugs upstream to library maintainers and link the issue in the docs.
A few ground rules
Link to section: 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, updatetools/calendar-dataand regenerate them:cd tools/calendar-data && cargo run --release. CI runscargo run --release -- --checkto 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.