Policies

The published policies that govern xrechnung-kit releases, deprecations, and what counts as a breaking change. These supersede any informal guidance elsewhere in the repo.

Semantic Versioning on emitted XML

xrechnung-kit ships valid XRechnung 3.0 XML. Output stability is part of the public contract.

Change type	Allowed in patch	Allowed in minor	Allowed in major
Bug fix that does not change emitted XML	yes	yes	yes
Bug fix that changes emitted XML	no	no	yes
New optional input field (BC-additive)	no	yes	yes
New required input field	no	no	yes
KoSIT scenarios bump that preserves pass / fail	no	yes	yes
KoSIT scenarios bump that changes pass / fail	no	no	yes
Public API method removal	no	no	yes
@deprecated marker added	yes	yes	yes
Internal class change	yes	yes	yes

In short: same MappingData produces the same XML bytes within a patch release. Within a minor, byte-equivalence may shift in ways that are still semantically equivalent and KoSIT-pass / fail equivalent.

Deprecation policy

• A public API marked @deprecated in MINOR release N is removable in MAJOR release N+1.
• The deprecation notice must include: the replacement, the version it was deprecated in, and the version it will be removed in.
• Deprecated APIs continue to work, with their existing semantics, for the entire MINOR series.
• Deprecation also surfaces at runtime via trigger_error(... E_USER_DEPRECATED) so consumers can wire it into their logger.

Internal API marker

Classes and methods marked @internal (PHPDoc) or living under XrechnungKit\Internal\* are not covered by SemVer.

• @internal classes may move, rename, or change signature in any release.
• Consumers who reach into @internal do so at their own risk and are not entitled to a deprecation cycle.

Supported PHP versions

• The latest 3 stable PHP versions are supported at any time.
• A PHP version drop (raising the floor) happens only in a MAJOR release.
• The current floor at v1.0 is PHP 8.1. PHP 8.1, 8.2, 8.3, 8.4 are tested in CI.

KoSIT scenarios

The KoSIT validator scenarios are pinned in vineethkrishnan/xrechnung-kit-kosit-bundle. Bumps happen via dedicated PRs (template: kosit-corpus-bump).

• A scenarios bump that preserves pass / fail equivalence across our fixture corpus -> ships in a minor.
• A scenarios bump that changes pass / fail behaviour for any fixture -> ships in a major.
• A scenarios bump that changes emitted XML expectations -> ships in a major across the whole vineethkrishnan/xrechnung-kit-* family.

Pinning policy lives in kosit-bundle/composer.json and is reflected in the bundle's CHANGELOG.

Sub-package SemVer coupling

Each sub-package (core, kosit-bundle, cli, adapters/*, mappers/*) versions independently on Packagist. They share a release-please workflow but their version lines are decoupled.

Coupling rules:

• An adapter package's require: vineethkrishnan/xrechnung-kit-core constraint is ^X.Y against the core version it was tested with.
• A core MAJOR triggers a coordinated MAJOR across all adapters that consume it.
• A core MINOR does not require an adapter bump unless the adapter intends to expose the new feature.

Security disclosure

Reporters get an acknowledgement within 3 business days, a triage assessment within 7 days, and a fix or mitigation plan within 14 days for high-severity issues. The embargo period is up to 90 days from report to public disclosure.

Full process in SECURITY.md.

Changelog

CHANGELOG.md is generated by release-please from Conventional Commits on main. Manual edits are overwritten on the next release. The format is Keep a Changelog 1.1.0.

Trademarks

"XRechnung" is a German federal e-invoicing standard maintained by KoSIT (Koordinierungsstelle fuer IT-Standards). xrechnung-kit is an independent open-source library and is neither affiliated with nor endorsed by KoSIT or any German government agency. The full disclaimer is in the README.