Skip to content

VERSIONING.md

Latest commit

 

History

History
76 lines (57 loc) · 3.31 KB

VERSIONING.md

File metadata and controls

76 lines (57 loc) · 3.31 KB
Raw

Versioning Policy

pjson uses Semantic Versioning 2.0.0. The current stable version is 2.0.0. Historical 0.0.x releases used a release- tag prefix and predate this stability policy.

Version meaning

  • MAJOR changes may require users to update source code or intentionally change documented behavior.
  • MINOR changes add backward-compatible public functionality.
  • PATCH changes contain backward-compatible fixes, documentation, or internal improvements.

Security fixes normally use the smallest compatible version increment. When a safe fix cannot preserve compatibility, the security advisory and release notes must call that out explicitly.

Compatibility boundary

The public contract includes:

  • declarations, types, constants, and macros in the installed pjson.h;
  • documented behavior of parsing, serialization, validation, and mutation;
  • the pjson::pjson CMake target and installed package names; and
  • documented compile-time requirements, including C++11 support.

Private implementation details, tests, benchmarks, examples, diagnostics not documented as stable, and repository layout outside installed artifacts are not public API.

Beginning with 2.0.0, pjson also maintains ABI compatibility within a major release for the same compiler ABI, standard-library ABI, architecture, and compatible build settings. PJSON_ABI_VERSION identifies that ABI generation. The pjson, pJsonParser, and pJsonSchemaValidator object layouts are fixed opaque handles; their private implementations may change without changing those layouts. Public option/error structures, virtual interfaces, enum values, function signatures, and exported symbols remain ABI-bearing and must not be reordered, removed, or changed within the major release. A new compiler runtime, incompatible standard library mode, architecture, or compile-time ABI switch remains a rebuild boundary.

Deprecation

When practical, a public API scheduled for removal is deprecated for at least one minor release and documented in the changelog. Immediate removal is reserved for cases where retaining the behavior would be unsafe or materially misleading. Removal of a supported public API requires a major release.

Version sources

For each release, the following values must agree:

  • the top-level CMake project version;
  • PJSON_VERSION, PJSON_VERSION_MAJOR, PJSON_VERSION_MINOR, and PJSON_VERSION_PATCH in pjson.h;
  • PJSON_ABI_VERSION in pjson.h and the shared-library SOVERSION;
  • package-manager or distribution metadata; and
  • the release heading in CHANGELOG.md.

The release checklist verifies these values before a tag is created. A mismatch is a release-blocking defect.

Tags and pre-releases

Release tags use the plain Semantic Versioning MAJOR.MINOR.PATCH form, for example 1.0.0. Pre-release identifiers use Semantic Versioning syntax, for example 1.1.0-rc.1. Historical 0.0.x tags retain their original release- prefix. Published tags are immutable; a correction is released under a new version rather than moving an existing tag.

Development happens on main. Until a release tag is published, its changes remain under the Unreleased heading in CHANGELOG.md.