persian-calendar/persian-calendar: an Android Solar Hijri calendar you can build yourself

What the Android Persian Calendar actually does

The README opens with a single line: "A simple, free and open-source Android calendar." That is the whole scope statement. The project renders the Solar Hijri calendar, the system used in Iran, on Android, and it is written in Kotlin. It is not a date-conversion library with a UI bolted on, and it is not a general scheduling app that happens to support one more calendar system. The repository layout confirms the shape of it: PersianCalendar/ holds the phone app, wear/ holds a Wear OS module, and lintChecks/ holds custom Android lint rules the project applies to itself.

The audience is narrow and clear. Someone who lives with Solar Hijri dates and wants them on a phone without paying for it, and someone who wants to read or modify the source of that app. The README is bilingual, with an English block and a Persian block, and the Persian block is the longer of the two because it explains the licence reasoning. That asymmetry is worth noticing: the project treats the licence question as something its Persian-speaking users will actually ask about.

The app is distributed through five channels listed in the README: Google Play under the package id com.byagowi.persiancalendar, F-Droid, the GitHub releases page, and the Iranian stores Cafe Bazaar and Myket. The package id is the stable identifier across all of them, so a build you make yourself and a build from F-Droid install over each other only if the signing keys match.

How the repository is put together

The build is Gradle with a Kotlin DSL, visible in build.gradle.kts and settings.gradle.kts at the top level. There is a gradle/ directory and a gradlePlugins/ directory, which means the project uses the Gradle version catalog plus its own convention plugins rather than repeating configuration in each module. A submodule is declared in .gitmodules, so a clone that does not fetch submodules will leave something missing; the README's clone instructions do not mention that step, and that is a gap.

Two files in the repository are not code but carry real weight. COMPATIBILITY.md is linked from both README blocks with the line "If your device is running an older version of Android, see this." That file is where the minimum and maximum supported Android versions live, and it is the only place the README points for that information. privacy-policy.md exists at the top level, which is what the Play Store listing requires. FAQ.fa.md is a Persian-language FAQ, and there is no English equivalent in the listing, so a non-Persian reader has to work from the README and the source.

nightly.keystore sits at the top level. A keystore in a public repository is normal for a debug or nightly signing key, and it means nightly builds are signed consistently with each other, not with the release APKs. Anyone building from source should generate their own key rather than reuse it. The fastlane/ directory holds store metadata, which is how the F-Droid and Play listings get their text and screenshots.

Installing it and building a first APK

If you just want the app, the README's Download section is the answer: install from Google Play, F-Droid, the GitHub releases page, Cafe Bazaar or Myket. The most recent release listed is v10.1.7, published on 2026-02-19, and the last push to main was the same day. Nothing in the README describes an in-app upgrade path or a rollback procedure, so if you sideload an APK you are responsible for keeping it current yourself.

If you want to build it, the README gives exactly two steps and they are GUI steps, not shell steps. In Android Studio, choose File > New > Project from Version Control, use https://github.com/persian-calendar/persian-calendar as the URL, and click the clone button.

git clone https://github.com/persian-calendar/persian-calendar

The README does not tell you to fetch submodules, even though the repository declares one in .gitmodules. A clone without them leaves that directory empty, which typically shows up as a Gradle sync failure rather than an obvious message about the submodule.

The README documents no command-line build, no output path and no signing configuration for release builds. The Gradle wrapper is present in the repository, so the conventional debug task is the wrapper script, but treat it as the standard Gradle entry point rather than a project-documented one. For a release build you will need your own keystore, since the nightly.keystore in the repository is not the release key.

Where the project is thin, and where it is the wrong tool

The README is a download page with a licence section attached. It does not document the app's features, its settings, its widgets, its notification behaviour, or how it handles time zones and daylight saving. For a calendar, time zone handling is the part most likely to produce a wrong-looking date, and the README says nothing about it. If you are evaluating the app on correctness rather than on availability, you will be reading Kotlin, not documentation.

The build instructions are the weakest part. Two Android Studio dialog steps, no command line, no CI recipe, no note about the required JDK or Android SDK level. COMPATIBILITY.md is linked but its contents are not reproduced in the README, so you cannot tell from the README alone whether your test device is supported. The project also carries a lintChecks/ module, which suggests the maintainers care about static analysis, yet none of that is surfaced to a new contributor.

It is the wrong tool in three cases. It is Android-only: there is no desktop, web or iOS target in the repository listing. It is an application, not a library, so if you want to convert Solar Hijri dates inside your own app you get no reusable artifact from this repository. And it is GPL-3.0, which the Persian half of the README explains was not a free choice: the project reused code under that licence and is therefore bound to it. If your product cannot ship GPL-3.0 code, this is not a component you can take.

How it compares with a general-purpose calendar app

The obvious alternative for an Android user is the calendar that ships with the phone, or a general app like Etar or the AOSP Calendar. Those take the opposite approach: they are calendar clients built around syncing with CalDAV or Google accounts, and they display whatever calendar system the locale asks for. Their strength is interoperability. Their weakness, for this audience, is that Solar Hijri support depends on the platform locale and is rarely the thing the app was designed around.

The Persian Calendar inverts that. It is built around one calendar system and is not described in the README as a sync client at all. There is no CalDAV mention, no account setup, no event-sharing story in the README. So the trade is real in both directions: you get an app whose primary display is the date system you care about, and you give up the interoperability that a general calendar client provides. If your events live in a Google account and you need them on the same screen, this project's README does not claim to solve that for you.

A second alternative is to use a conversion library inside an app you already control. That gets you the arithmetic without the UI, but this repository does not publish such a library, so you would be writing the conversion yourself or sourcing it elsewhere.

Licence and the cost of keeping a fork

The licence is GPL-3.0, stated in the README and in the COPYING file at the top level. The Persian section of the README is unusually direct about why: the project used source code that was already under this licence, so the maintainers say they are not in a position to offer the code under different terms. The same section summarises the practical obligation as publishing your modified source publicly with each release, linking to it publicly, and giving proper attribution to the original. That is the project's own plain-language summary, not a legal opinion, and it is the part a company evaluating this code should read before anything else.

For a fork, the cost is not the licence fee, it is the release discipline. Every release you publish has to come with your modified source and a public link to it. If you were planning to ship a closed derivative, GPL-3.0 rules that out, and the README is explicit that relicensing is not the maintainers' to grant.

On maintenance, the last push to main was on 2026-02-19, and the newest release, v10.1.7, carries the same date. The repository is not archived. Beyond that the repository does not describe a support policy, a release cadence or a deprecation process, so there is no basis for a claim about how quickly fixes arrive. A fork inherits the Android version treadmill: as Google raises target SDK requirements, someone has to do that work, and the repository does not document who.

Editorial conclusion

Adopt it if you want a GPL-3.0 Android calendar that renders Solar Hijri dates and you are willing to clone the repository and build it in Android Studio, or to install the APK from F-Droid or the GitHub releases page. Do not adopt it if you need a desktop or web calendar, or a permissively licensed library you can relicense; the README states the GPL-3.0 choice was forced by code the project already uses. Before you commit, check COMPATIBILITY.md against your minimum Android version and read the licence section in the Persian half of the README, which is the one that explains the obligation in detail.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes