Skip to content

ADR 0023 week numbering without default

Jump to bottom
Karthik P edited this page Oct 31, 2026 · 1 revision

ADR-0023: Week numbering has no default; 0.1.0 supports contains_start only

week.numbering is required in every definition, and 0.1.0 implements only contains_start, with first_full reserved for 0.2.

Last reviewed: 31 Oct 2026

Status

Accepted on 31 Oct 2026 under the maintainer's delegation; may be revisited. The research proposal left this open ("Week numbering default for calendar-month years: contains_start or first_full, or no default"), and the maintainer asked for the roadmap and 0.1.0 to be decided and built without them. Built in 0.1.0.

Context

Fiscal week numbers are one of the oldest requests in this area: fiscalyear issue #10, "Support for week number of a date in a FiscalYear", has 20 comments and is open as of 31 Oct 2026 (fiscalyear #10). In a week-based year, week 1 starts on the year's first day and every week is whole, so the numbering is fixed. In a fixed-date year the first and last weeks are usually partial, and organisations differ in whether week 1 is the week containing the year's first day (contains_start) or the first full week (first_full).

The proposal's principle 5 says anything that differs between organisations is required, and defaults exist only where every real calendar agrees.

Decision drivers

  • No silent defaults for organisation-specific choices.
  • Ship week numbers in 0.1.0 with a rule that is fully specified and tested.
  • Do not block the release on designing every numbering rule.

Considered options

Option 1: Default to contains_start

Pros:

  • Shorter definitions.

Cons:

  • Silently wrong for organisations that use full weeks.

Option 2: Default to first_full

Pros:

  • Every numbered week has 7 days.

Cons:

  • Silently wrong for organisations that count the partial first week; also leaves days before week 1 that need their own rule.

Option 3: No default; implement contains_start now and reserve first_full (chosen)

Pros:

  • Every definition states its rule.
  • 0.1.0 ships one rule completely, and first_full can be added without changing any existing definition's meaning.

Cons:

  • Users whose organisation uses full weeks cannot use week numbers in fixed-date years until 0.2.
  • Even week-based definitions must write "numbering": "contains_start", although there is only one meaningful rule for them.

Decision

Option 3, as specified in spec/definition-v1.md (week):

  • numbering is required and has no default.
  • "contains_start" is the only accepted value in 0.1.0. "first_full" is reserved and rejected with UNSUPPORTED_FEATURE.
  • In a week_based year, weeks are numbered 1 to 52, or 1 to 53 in a year with an extra week.
  • In a fixed_date year with contains_start, week 1 runs from the year's first day to the day before the next starts_on, so it may have 1 to 7 days; a year has 53 or 54 weeks.

The decision covers every year type, not only calendar-month years as the proposal's question was phrased, so that the rule is the same everywhere.

Consequences

Good:

  • No definition gets week numbers it did not ask for.
  • The differential test covers numbering rules against the slow reference implementation (Testing-Strategy).

Bad:

  • In fixed-date years, week children of a quarter or period are LEVEL_NOT_NESTED, because weeks cross month boundaries there.
  • first_full users wait for 0.2.

Links

fiscalclock is licensed under MIT OR Apache-2.0 (MIT, Apache-2.0). Last reviewed: 31 Oct 2026. Found an error on this page? Report it with the documentation form.

Start

Design

Decisions

Project

Clone this wiki locally