Add paragraph about crescent moon visibility to Hijri docs #7330

sffc · 2025-12-18T22:45:58Z

Split from #7325

robertbastian · 2025-12-19T09:23:53Z

components/calendar/src/cal/hijri.rs

 ///
+/// # Crescent moon visibility
+///
+/// According to Islam, months begin when an observer first sees the crescent moon.


when exactly? the same day? there's something about sunset, no?

A new moon can basically only occur after sunrise, you cannot see a new moon after sunset.

this is about crescent moons, not new moons, right?

I'm mainly asking if the day you see the crescent is day 0 or 1. that should be documented

A crescent moon occurs immediately after the moment of the new moon. The moment of the new moon can only occur during the day.

Whether that crescent is distinct enough is a different question.

Islam doesn't have "something about sunset" IIRC, it's Judaism which does that.

But yes, day 1 of the month is when the crescent moon is visible. Fair to want that documented.

My goal in this section is for readers to better understand the nature of the different Hijri Rules using language that is clear and accurate but doesn't add new invariants.

if you're trying to be accurate then say "on the day an observer first sees the crescent moon"

added "on the day"

But yes, day 1 of the month is when the crescent moon is visible

this seems to disagree with what Gemini is arguing in the other thread. I was also under the assumption that it was the next day (i.e. you spot the crescent, and then celebrate Eid the next day). this says something similar

Oh, yes, sorry, you're right, I had my wires crossed. The islamic "day" does traditionally also begin after sunset.

robertbastian · 2025-12-19T09:42:40Z

components/calendar/src/cal/hijri.rs

+/// For centuries, astronomers have been developing criteria for predicting crescent moon
+/// visibility. However, most regions that use the Hijri calendar rely on observations that
+/// are impacted by atmospheric phenomena, meaning such predictions are only an approximation
+/// of ground truth.


this calendar is inherently observer-based. everyone can look at the sky and make their own "ground truth", so it's not really ground truth

The term "ground truth" is used elsewhere in these docs. But, I rewrote this and my rewrite doesn't use the term.

robertbastian · 2025-12-19T15:28:09Z

components/calendar/src/cal/hijri.rs

+/// are impacted by atmospheric phenomena, meaning such predictions are only an approximation
+/// of ground truth.
+///
+/// The primary exception is Saudi Arabia, where the KACST publishes official predictions of


primary exception to what? if it's to "most regions", it should be in that paragraph

Primary exception to the previous paragraph: "observations that are impacted by atmospheric phenomena"

I rewrote this to not frame it as an exception to a rule.

robertbastian

.

robertbastian · 2025-12-30T21:58:31Z

components/calendar/src/cal/hijri.rs

+/// However, some groups use criteria that are not impacted by these phenomena and are
+/// therefore suitable for future prediction.
+///
+/// ICU4X ships two of these:


icu or icu_calendar users might not know what "ICU4X" is. just say "this crate"

robertbastian · 2025-12-30T22:07:57Z

components/calendar/src/cal/hijri.rs

+///
+/// 1. [`UmmAlQura`], used in Saudi Arabia, is based on official predictions of crescent
+///    timings published by the KACST.
+/// 2. [`TabularAlgorithm`], used by certain denominations such as Dawoodi Bohra, is


nit: you consistenly use "groups" earlier, but here you suddenly use "denomination". I haven't seen the term "denomination" associated with Islam much, according to Wikipedia "sects" or "schools" might be better terms. or just continue using "groups"

I wanted a word that covers both regions and sects.

https://en.wikipedia.org/wiki/Dawoodi_Bohra calls it a "denomination".

I don't see the need to cover regions, as this is not official in any region, so it's not a geographic thing.

Wikipedia appears to suggest a different leap year cycle for Dawoodi Bohra. Are we sure that they use this leap year cycle and epoch?

Yeah, they might be using TypeIV.

Let's not claim Dawoodi Bohra using this then. AFAICT, the justification for islamic-tbla is Microsoft legacy and the justification for islamic-civil is IBM legacy. (I think one of them, not sure which one, matches historical official status in the Ottoman Empire, but that's not why either is here.)

Little frustrating that we have BCP47 codes for a bunch of legacy unused calendars but we do not for actually in-use calendars.

I remember when I researched this I confirmed that tbla was using the same epoch as the Bohra/Fatimid calendar, but I probably missed the leap year pattern difference.

sffc · 2025-12-31T07:57:18Z

/gemini review

gemini-code-assist

Code Review

This pull request adds a helpful documentation section on crescent moon visibility to the Hijri calendar module. The explanation is clear and provides good context for the different Hijri calendar algorithms supported by the crate. I have one minor suggestion to improve the precision of the description of how a new month begins in Islam, to avoid potential ambiguity.

gemini-code-assist · 2025-12-31T07:58:15Z

components/calendar/src/cal/hijri.rs

 ///
+/// # Crescent moon visibility
+///
+/// According to Islam, months begin on the day when the crescent moon is visible in the sky.


The phrasing "months begin on the day when the crescent moon is visible" is a bit ambiguous. An Islamic day starts at sunset, and the new month starts on the day after the crescent moon is sighted. To improve clarity and precision, I suggest rephrasing this.

/// According to Islam, the first day of a month is the day after the crescent moon is first sighted at sunset.

/gemini Good point. I tweaked the language. It now reads: "According to Islam, the first day of a month begins when the crescent moon is visible at sunset." Is this better?

Thank you for the update! The new phrasing is clearer, but it still implies the month begins on the same day the crescent moon is visible at sunset. To be fully precise, the new month typically starts the day after the crescent moon is first sighted at sunset.

I recommend reverting to the previous suggestion for accuracy.

Suggested change

/// According to Islam, months begin on the day when the crescent moon is visible in the sky.

/// According to Islam, the first day of a month is the day after the crescent moon is first sighted at sunset.

/gemini I think your phrasing is potentially less clear if you consider days to begin at sunset rather than midnight. How about: "According to Islam, the first day of a month begins after the crescent moon is visible at sunset."

I talked with you Gemini in another window on the following phrasing: "According to Islam, a new month begins the evening when the crescent moon is visible at sunset." And you said: 'That statement is excellent. It is concise, accurate, and avoids the "day/day after" ambiguity by using the word "evening."' So I will go with that version. Thanks.

I understand your concern about potential ambiguity. Let's try to resolve this with a slightly different approach that incorporates the idea of days starting at sunset:

"According to Islam, the first day of a month begins in the evening after the crescent moon is visible at sunset."

This phrasing aims to capture both the sunset aspect and the "day after" concept. What do you think?

sffc · 2026-01-06T21:37:50Z

I consider this mergeable. Since we just had two weeks of holidays, I will wait for a few more days for feedback.

robertbastian · 2026-01-09T18:36:18Z

components/calendar/src/cal/hijri.rs

 /// The most common version of these rules uses [`TabularAlgorithmEpoch::Friday`] and [`TabularAlgorithmLeapYears::TypeII`].
 ///
+/// Tabular Islamic rules are used in denominations such as Dawoodi Bohra and other branches of Ismailism.
+/// Be sure to select the correct leap year and epoch parameters according to your use case. If ICU4X does


Suggested change

/// Be sure to select the correct leap year and epoch parameters according to your use case. If ICU4X does

/// Be sure to select the correct leap year and epoch parameters according to your use case. If this type does

Follow-up to #7330 (comment)

Add paragraph about crescent moon visibility to Hijri docs

126cd21

sffc requested a review from Manishearth as a code owner December 18, 2025 22:45

sffc requested review from hsivonen and robertbastian December 18, 2025 22:56

Delete the sophisticated telescope thing

04c36ed

sffc mentioned this pull request Dec 18, 2025

Improve the docs of Hijri AstronomicalSimulation #7325

Draft

centuries

ab9b886

Manishearth approved these changes Dec 19, 2025

View reviewed changes

robertbastian reviewed Dec 19, 2025

View reviewed changes

robertbastian requested changes Dec 30, 2025

View reviewed changes

Update hijri.rs

200d1f7

sffc requested review from Manishearth and robertbastian December 30, 2025 21:56

robertbastian reviewed Dec 30, 2025

View reviewed changes

Update hijri.rs

7ebf543

sffc requested a review from robertbastian December 30, 2025 22:03

robertbastian approved these changes Dec 30, 2025

View reviewed changes

gemini-code-assist bot reviewed Dec 31, 2025

View reviewed changes

sffc added 2 commits December 30, 2025 22:09

Update hijri.rs

2e10b42

Update hijri.rs

d17d2c7

Manishearth approved these changes Jan 6, 2026

View reviewed changes

Improve language surrounding TabularIslamic

e8cd985

sffc requested a review from Manishearth January 9, 2026 18:07

Manishearth approved these changes Jan 9, 2026

View reviewed changes

sffc merged commit 40c7402 into unicode-org:main Jan 9, 2026
32 checks passed

sffc deleted the hijridoc-01 branch January 9, 2026 18:34

robertbastian reviewed Jan 9, 2026

View reviewed changes

sffc added a commit to sffc/omnicu that referenced this pull request Jan 9, 2026

Address one more feedback comment on unicode-org#7330

2368bb7

sffc mentioned this pull request Jan 9, 2026

Change doc comment language to "this type" #7392

Merged

Manishearth pushed a commit that referenced this pull request Jan 9, 2026

Change doc comment language to "this type" (#7392)

9d626e1

Follow-up to #7330 (comment)

	/// According to Islam, months begin on the day when the crescent moon is visible in the sky.
	/// According to Islam, the first day of a month is the day after the crescent moon is first sighted at sunset.

	/// Be sure to select the correct leap year and epoch parameters according to your use case. If ICU4X does
	/// Be sure to select the correct leap year and epoch parameters according to your use case. If this type does

Add paragraph about crescent moon visibility to Hijri docs #7330

Add paragraph about crescent moon visibility to Hijri docs #7330

Uh oh!

Conversation

sffc commented Dec 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Manishearth Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robertbastian left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Manishearth Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sffc commented Dec 31, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Dec 31, 2025

Choose a reason for hiding this comment

Uh oh!

Manishearth Dec 30, 2025 •

edited

Loading

Manishearth Jan 8, 2026 •

edited

Loading