focus-shift · derTobsch · Mar 24, 2026
diff --git a/.docs/add-new-holiday-calendar.md b/.docs/add-new-holiday-calendar.md
@@ -0,0 +1,216 @@
+# Adding a New Holiday Calendar to Jollyday
+
+This guide explains step-by-step how to add a new holiday calendar to Jollyday, based on the Armenia example from PR #704.
+
+## Overview
+
+To add a new holiday calendar, you need to:
+
+1. [Create a holiday definition XML file](#step-1-create-the-calendar-holiday-configuration-xml-file)
+2. [Add the new holiday calendar enum](#step-2-add-new-holiday-calendar)
+3. [Add translations](#step-3-add-translations-for-the-new-holiday-calendar)
+4. [Write tests](#step-4-write-tests)
+5. [Create a pull request](#step-5-create-pull-request)
+
+---
+
+## Step 1: Create the Calendar Holiday Configuration XML File
+
+Navigate to:
+
+```
+jollyday-core/src/main/resources/holidays
+```
+
+Create a new XML file named after the country code ([ISO 3166-1 alpha-2]).
+
+Example for Armenia:
+
+```
+Holidays_am.xml
+```
+
+### Structure Example
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration hierarchy="am" description="Armenia"
+               xmlns="https://focus_shift.de/jollyday/schema/holiday"
+               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+               xsi:schemaLocation="https://focus_shift.de/jollyday/schema/holiday https://focus_shift.de/jollyday/schema/holiday/holiday.xsd">
+  <Holidays>
+    <Fixed month="JANUARY" day="1" descriptionPropertiesKey="NEW_YEAR"/>
+  </Holidays>
+</Configuration>
+```
+
+### Requirements
+
+Ensure your XML file:
+
+* Is well-formed
+* Matches the schema definition
+* Uses valid elements (e.g., `Fixed`, `RelativeToFixed`, `ChristianHoliday`)
+
+### Notes
+
+* Use ISO 3166-1 alpha-2 country codes (e.g., `am` for Armenia)
+* Follow existing country files as templates
+* Keep the file minimal and consistent with existing implementations
+
+---
+
+## Step 2: Add New Holiday Calendar
+
+Add a new entry to the `HolidayCalendar` enum:
+
+```
+jollyday-core/src/main/java/de/focus_shift/jollyday/core/HolidayCalendar.java
+```
+
+Example:
+
+```java
+ARMENIA("am")
+```
+
+### Notes
+
+* The code must match the XML file name (`am` ↔ `Holidays_am.xml`)
+* Keep alphabetical order if applicable
+
+---
+
+## Step 3: Add Translations for the New Holiday Calendar
+
+Add translations for the country and its subdivisions.
+
+File location:
+
+```
+jollyday-core/src/main/resources/descriptions/country_descriptions.properties
+```
+
+Example:
+
+```properties
+country.description.am        = Armenia
+country.description.am.ag     = Aragatsotn
+country.description.am.ar     = Ararat
+country.description.am.av     = Armavir
+country.description.am.er     = Yerevan
+country.description.am.gr     = Gegharkunik
+country.description.am.kt     = Kotayk
+country.description.am.lo     = Lori
+country.description.am.sh     = Shirak
+country.description.am.su     = Syunik
+country.description.am.tv     = Tavush
+country.description.am.vd     = Vayots Dzor
+```
+
+### Notes
+
+* Use consistent naming with ISO subdivision codes
+* Only add subdivisions if they are supported in the XML
+
+---
+
+## Step 4: Write Tests
+
+Create a test class:
+
+```
+jollyday-tests/src/test/java/de/focus_shift/jollyday/tests/country/HolidayAMTest.java
+```
+
+### Approach (Based on PR #704)
+
+Tests should use the `CalendarCheckerApi` and follow the established fluent style.
+
+### Example Test
+
+```java
+package de.focus_shift.jollyday.tests.country;
+
+import org.junit.jupiter.api.Test;
+
+import static de.focus_shift.jollyday.core.HolidayCalendar.ARMENIA;
+import static de.focus_shift.jollyday.tests.CalendarCheckerApi.assertFor;
+import static java.time.Month.*;
+
+class HolidayAMTest {
+
+  @Test
+  void ensuresHolidays() {
+
+    assertFor(ARMENIA)
+      .hasFixedHoliday("NEW_YEAR", JANUARY, 1).and()
+      .hasFixedHoliday("NEW_YEAR", JANUARY, 2).and()
+      .hasFixedHoliday("CHRISTMAS", JANUARY, 5).and()
+      .hasFixedHoliday("CHRISTMAS", JANUARY, 6).and()
+      .hasFixedHoliday("ARMY_DAY", JANUARY, 28).and()
+      .hasFixedHoliday("INTERNATIONAL_WOMAN", MARCH, 8).and()
+      .hasFixedHoliday("ARMENIAN_GENOCIDE_REMEMBRANCE_DAY", APRIL, 24).and()
+      .hasFixedHoliday("LABOUR_DAY", MAY, 1).and()
+      .hasFixedHoliday("VICTORY_AND_PEACE_DAY", MAY, 9).and()
+      .hasFixedHoliday("REPUBLIC_DAY", MAY, 28).and()
+      .hasFixedHoliday("CONSTITUTION_DAY", JULY, 5).and()
+      .hasFixedHoliday("INDEPENDENCE_DAY", SEPTEMBER, 21).and()
+      .hasFixedHoliday("NEW_YEARS_EVE", DECEMBER, 31).and()
+      .hasChristianHoliday("EASTER")
+      .check();
+  }
+}
+```
+
+### Requirements
+
+Ensure:
+
+* Tests reflect the XML configuration
+* Only representative holidays are tested
+* Fluent API (`assertFor(...)`) is used
+* Tests remain readable and maintainable
+
+Run tests using:
+
+```
+./mvnw verify
+```
+
+---
+
+## Step 5: Create Pull Request
+
+When submitting your PR:
+
+* Include:
+
+  * XML file
+  * Enum update
+  * Translations
+  * Tests
+* Reference official sources for holidays (government websites preferred)
+* Keep the PR focused on a single country
+* Provide a clear description of the changes
+
+---
+
+## Checklist
+
+* [ ] XML file created
+* [ ] HolidayCalendar enum updated
+* [ ] Translations added
+* [ ] Tests implemented
+* [ ] Tests passing (`./mvnw verify`)
+* [ ] PR created with description
+
+---
+
+## Reference
+
+This guide is based on the Armenia implementation from PR #704.
+
+---
+
+[ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,14 +3,28 @@
 Jollyday is released under the Apache 2.0 license. If you would like to contribute
 something, or simply want to hack on the code this document should help you get started.
 
-## Ideal for contribution
+## Reporting Security Vulnerabilities
+
+If you think you have found a security vulnerability in Jollyday please *DO NOT*
+disclose it publicly until we've had a chance to fix it. Please *don't report security
+vulnerabilities using GitHub issues*, instead open a report of a security vulnerability
+via [Report a security vulnerability](https://github.com/focus-shift/jollyday/security/advisories/new)
+
+## Adding a new holiday calendar
+If you want to add a new holiday calendar, please follow the instructions in
+[Adding a New Holiday Calendar to Jollyday](./.docs/add-new-holiday-calendar.md).
+
+
+## Working with us on GitHub
+
+### Ideal for contribution
 
 We would be more than pleased if the community would help us build an awesome piece of software for all.
 To find issues and pull requests that are good for contributions you can use the
 ['ideal for contribution'](https://github.com/focus-shift/jollyday/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+ideal-for-contribution%22)
 label.
 
-## Using GitHub Issues
+### Using GitHub Issues
 
 We use GitHub issues to track bugs and enhancements.
 
@@ -20,14 +34,13 @@ information as possible.
 Please look for other issues or pull requests which already work on this topic.
 Is somebody already on it? Do you need to synchronize?
 
-## Reporting Security Vulnerabilities
+## Working with the Code
 
-If you think you have found a security vulnerability in Jollyday please *DO NOT*
-disclose it publicly until we've had a chance to fix it. Please *don't report security
-vulnerabilities using GitHub issues*, instead open a report of a security vulnerability
-via [Report a security vulnerability](https://github.com/focus-shift/jollyday/security/advisories/new)
+If you don't have an IDE preference we would recommend that you use
+[the IntelliJ Community Edition](https://www.jetbrains.com/idea/download). This will
+automatically use our EditorConfig.
 
-## Code Conventions and Housekeeping
+### Code Conventions and Housekeeping
 
 None of these is essential for a pull request, but they will all help.
 They can also be added after the original pull request but before a merge.
@@ -42,21 +55,13 @@ They can also be added after the original pull request but before a merge.
   if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
   message (where `XXXX` is the issue number).
 
-## Working with the Code
-
-If you don't have an IDE preference we would recommend that you use
-[the IntelliJ Community Edition](https://www.jetbrains.com/idea/download). This will
-automatically use our EditorConfig.
-
 ### Building from Source
 
 The jollyday source can be built from the command line using
 [Apache Maven](http://maven.apache.org/run-maven/index.html) on JDK 17 or above.
 We include '`Maven Wrapper`' scripts (`./mvnw` or `mvnw.cmd`) that you can run rather
 than needing to install Maven locally.
 
-#### Default Build
-
 The project can be built from the root directory using the standard Maven command:
 
 ```shell