Skip to content

docs: clarify public API ownership and release review policy #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kazemek merged 1 commit into from
Oct 2, 2026
Merged

docs: clarify public API ownership and release review policy #255

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ Maven group: `com.kazforge`. Java packages: `com.kazforge.jsonapi.*`.

## Requirements

- JDK 21 (enforced via Gradle toolchain)
- Java 21 is the runtime and build minimum. Building from source requires a locally installed
JDK 21 for the Gradle compilation toolchain.

## Build

Expand Down
25 changes: 25 additions & 0 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,31 @@ The library represents, validates, reads, and writes JSON:API documents. Optiona
application values and parse query selections. Applications retain persistence, endpoints,
authorization, query execution, relationship mutation, and application of PATCH results.

## Public API ownership

The supported consumer API is the documented consumer-facing surface under `com.kazforge.jsonapi`,
including intended public/protected extension points. Module READMEs identify that surface; package
documentation and Javadoc own its responsibilities and contracts. Java visibility or artifact
publication alone does not imply consumer support. Packages beneath an `internal` segment and the
entire `jsonapi-java-mapping` artifact are unsupported implementation detail.

Normal API review assesses source and binary compatibility and documented observable behavior.
Internal changes have no separate compatibility promise, but changes to supported behavior still
require normal classification. Raising a supported runtime/dependency minimum or withdrawing a
supported line is breaking; [ADR-014](adr/014-unified-release-train.md) owns version and deprecation
rules. This policy relies on documented boundaries and review, not a bespoke signature-compatibility
mechanism.

Java 21 is the runtime and build minimum. CI deliberately exercises a newer LTS without
automatically raising that minimum. Jackson 2 and Jackson 3 are separate supported dependency lines;
concrete minimum/current versions and verification remain to be established and publicly documented
in a separate dependency-baseline increment before publication. Current catalog versions are build
inputs, not declared minimums or proof of compatibility with older versions.

Consumer/framework dependency management is authoritative within supported lines; `jsonapi-java`
must not pin applications to the repository's currently tested Jackson version. The future
Spring/Spring Boot integration owns its own tested Spring/Jackson compatibility matrix.

## Modules and dependency direction

`settings.gradle.kts` is the build-membership authority. The implemented modules compose downward:
Expand Down
5 changes: 4 additions & 1 deletion docs/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,10 @@ Publish job (same workflow run)
## Maintainer runbook

1. Review the release PR (`gradle.properties`, `CHANGELOG.md`, manifest) and
merge it. Merging is the release decision.
merge it. Check [supported API and behavior changes](architecture.md#public-api-ownership),
including support-floor or support-line changes, are classified in Conventional Commits and
release notes according to ADR-014. Before publication, establish, verify, and publicly document
concrete Jackson minimum/current support lines. Merging is the release decision.
2. release-please creates the `v<version>` tag and GitHub Release; the publish
job checks out that tag, then builds, signs, and uploads the bundle to the
Central Portal with automatic publishing.
Expand Down
Loading