feat: add Venezuela holiday provider

.github/workflows/stale.yml

@@ -15,7 +15,7 @@ jobs:
 
     steps:
       - name: "Prune stale issues and pull requests"
-        uses: "actions/stale@v10.1.1"
+        uses: "actions/stale@v10.2.0"
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"
           days-before-close: "${{ env.DAYS_BEFORE_CLOSE }}"

.gitignore

@@ -3,6 +3,7 @@
 .php-cs-fixer.cache
 .php_cs.cache
 .phpactor.json
+.phpunit.cache
 .phpunit.result.cache
 bin/_*
 composer.lock

AGENTS.md

@@ -0,0 +1,76 @@
+# Yasumi — Agent Instructions
+
+Yasumi is a PHP library for calculating public holidays across countries and regions.
+It is calculation-driven (no database), provider-based (one class per country/region),
+and PSR-12/PSR-4 compliant.
+
+## Project Structure
+
+```
+src/Yasumi/
+  Yasumi.php              # Main entry point / factory
+  Holiday.php             # Represents a single holiday
+  SubstituteHoliday.php   # Substituted holiday
+  ProviderInterface.php   # Contract all providers must implement
+  Translations.php        # Holiday name translations
+  Provider/               # One file (or directory) per country/region
+    AbstractProvider.php  # Base class for all providers
+    CommonHolidays.php    # Reusable holiday calculations (New Year's, etc.)
+    ChristianHolidays.php # Easter and related calculations
+    *.php / */            # Country and sub-region providers
+  Filters/                # Holiday type filters (Official, Bank, etc.)
+  data/                   # Translation data files
+tests/                    # PHPUnit tests, mirroring src structure
+examples/                 # Usage examples
+```
+
+## Requirements
+
+- PHP 8.2+
+- `ext-json` (required), `ext-intl` (dev), `ext-calendar` (optional, for Easter)
+
+## Key Commands
+
+```shell
+composer test          # Run the full PHPUnit test suite
+composer cs            # Check coding standard (dry-run)
+composer cs-fix        # Auto-fix coding standard violations (alias: composer format)
+composer phpstan       # Run static analysis (level 8)
+```
+
+## Coding Conventions
+
+- **PSR-12** coding standard enforced via `php-cs-fixer`. Always run `composer cs-fix` after changes.
+- **PSR-4** autoloading: `Yasumi\` → `src/Yasumi/`, `Yasumi\tests\` → `tests/`.
+- Strict types (`declare(strict_types=1)`) are required in all PHP files.
+- Holiday providers extend `AbstractProvider` and implement `initialize()`.
+
+## Adding a New Holiday Provider
+
+1. Create `src/Yasumi/Provider/{CountryName}.php` extending `AbstractProvider`.
+2. Implement `initialize()`: call `addHoliday()` for each holiday.
+3. Implement `getSources()`: list of external resources.
+4. Add translations to `src/Yasumi/data/`.
+5. Create `tests/{CountryName}/{CountryName}BaseTestCase.php` (shared assertions).
+6. Create `tests/{CountryName}/{CountryName}Test.php` (country-level tests asserting all expected holidays).
+7. Add a `<testsuite>` entry in `phpunit.xml.dist`.
+8. Each test must cover multiple years; respect establishment/abolition years of holidays.
+
+## Testing
+
+- All new providers and holidays **must** have unit tests — PRs without tests are not accepted.
+- Tests use PHPUnit 11 and iterate over a range of years automatically.
+- Run a specific suite: `vendor/bin/phpunit --testsuite Netherlands`
+
+## Static Analysis
+
+- PHPStan at level 8. Run `composer phpstan` and fix all errors before committing.
+- Ignored errors are listed in `phpstan.neon.dist`; do not add new ignores without good reason.
+
+## Pull Request Guidelines
+
+- One PR per feature or country provider.
+- Run `composer test`, `composer cs`, and `composer phpstan` before submitting.
+- Adhere to conventional commits for commit conventions.
+- Squash intermediate commits; keep history meaningful.
+- Branch off `develop`; target `develop` for PRs.

CONTRIBUTING.md

@@ -10,15 +10,14 @@ When contributing there are a few guidelines we'd like you to keep in mind:
 - **[PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/)**
   Please use the following command after you have completed your work:
 
-  ```shell
-  composer format
-  ```
+    ```shell
+    composer format
+    ```
 
-  This will check/correct all the code for the PSR-12 Coding Standard using the
-  wonderful [php-cs-fixer](https://cs.symfony.com).
+    This will check/correct all the code for the PSR-12 Coding Standard using the
+    wonderful [php-cs-fixer](https://cs.symfony.com).
 
 - **Add unit tests!** - Your Pull Request won't be accepted if it does not have tests:
-
     1. Ensure your new Holiday Provider contains all the necessary unit tests.
     2. Next to the file `{REGIONNAME}BaseTestCase.php`, a file called `{REGIONNAME}Test.php` needs to be present. This
        file needs to include region/country level tests and requires assertion of all expected holidays.
@@ -37,6 +36,18 @@ When contributing there are a few guidelines we'd like you to keep in mind:
   please [squash them](https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_changing_multiple) before
   submitting.
 
+- **Use [Conventional Commits](https://www.conventionalcommits.org)** - Commit messages must follow the Conventional
+  Commits specification (e.g. `feat(Netherlands): add holiday X`, `fix(Germany): correct date for Y`).
+
+- **Sign your commits (DCO)** - Each commit must include a `Signed-off-by` trailer to certify you agree to the
+  [Developer Certificate of Origin](DCO):
+
+    ```shell
+    git commit -s -m "feat: your change"
+    ```
+
+- **Branch and PR target** - Always branch off `develop` and open your pull request against `develop`.
+
 ## Running Tests
 
 ```shell
@@ -48,3 +59,19 @@ Or, alternatively run with:
 ```shell
 vendor/bin/phpunit
 ```
+
+Run a specific suite by name:
+
+```shell
+vendor/bin/phpunit --testsuite Netherlands
+```
+
+## Before Submitting
+
+Always run all three checks before opening a pull request:
+
+```shell
+composer cs        # Check coding standard
+composer phpstan   # Static analysis (level 8)
+composer test      # Full test suite
+```

SECURITY.md

@@ -6,12 +6,11 @@ The following versions are supported with security updates:
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 2.9.0  | :white_check_mark: |
-| 2.8.0  | :white_check_mark: |
-| 2.7.0  | :white_check_mark: |
-| 2.6.0  | :x: |
-| 2.5.0  | :x: |
-| <2.4   | :x: |
+| 2.10.0  | :white_check_mark: |
+| 2.9.0   | :white_check_mark: |
+| 2.8.0   | :x:                |
+| 2.7.0   | :x:                |
+| <2.7    | :x:                |
 
 As for supported PHP versions, this project only supports the actively supported versions of PHP and versions of PHP
 that only receive critical security updates. Currently, that is PHP 8.2, 8.3, 8.4 and 8.5.
@@ -22,7 +21,8 @@ support of that retired PHP version.
 ## Reporting a Vulnerability
 
 If you would like to report a vulnerability or have any security concerns with this project,
-please [open an issue](https://github.com/azuyalabs/yasumi/issues/new?labels=security).
+please use [GitHub's private vulnerability reporting](https://github.com/azuyalabs/yasumi/security/advisories/new)
+to disclose it privately before a fix is available.
 
 To investigate your request as good as possible, please include any of the following when reporting:
 

composer.json

@@ -45,7 +45,7 @@
     "mikey179/vfsstream": "^1.6",
     "phpstan/phpstan": "^2.1",
     "phpstan/phpstan-deprecation-rules": "^2.0",
-    "phpunit/phpunit": "^8.5 || ^9.6"
+    "phpunit/phpunit": "^11.5"
   },
   "suggest": {
     "ext-calendar": "For calculating the date of Easter"

examples/basic.php

@@ -43,18 +43,20 @@
 // Get a holiday instance for Independence Day
 $independenceDay = $holidays->getHoliday('independenceDay');
 
-// Show the localized name
-echo 'Name of the holiday : ' . $independenceDay->getName() . PHP_EOL;
+if (null !== $independenceDay) {
+    // Show the localized name
+    echo 'Name of the holiday : ' . $independenceDay->getName() . PHP_EOL;
 
-// Show the date
-echo "Date of the holiday : {$independenceDay}" . PHP_EOL;
+    // Show the date
+    echo "Date of the holiday : {$independenceDay}" . PHP_EOL;
 
-// Show the type of holiday
-echo 'Type of holiday     : ' . $independenceDay->getType() . PHP_EOL;
+    // Show the type of holiday
+    echo 'Type of holiday     : ' . $independenceDay->getType() . PHP_EOL;
+}
 echo PHP_EOL;
 
 // Dump the holiday as a JSON object
 echo 'Holiday as a JSON object:' . PHP_EOL;
-echo json_encode($independenceDay, JSON_PRETTY_PRINT);
+echo json_encode($independenceDay ?? [], JSON_PRETTY_PRINT);
 
 echo PHP_EOL;

phpstan.neon.dist

@@ -1,14 +1,12 @@
 parameters:
-  level: 6
+  level: 8
   paths:
     - src
     - examples
   ignoreErrors:
     -
       message: '#Comparison operation "<=" between [0-9]+ and int<[0-9]+, max> is always true.#'
       path: src/Yasumi/Provider/Turkey.php
-    -
-      identifier: missingType.generics
   reportUnmatchedIgnoredErrors: true # Do not allow outdated errors in the baseline
   treatPhpDocTypesAsCertain: false
   tipsOfTheDay: false