From 98d1aa455b1213409567d39e06a0ed1dedefdbe5 Mon Sep 17 00:00:00 2001 From: Chuck Smith Date: Wed, 27 May 2026 08:04:01 -0400 Subject: [PATCH] feat: document public API stability policy for v1.0.0 Adds a Versioning section to README defining what is/isn't covered by semver guarantees from 1.0 onwards, the deprecation policy (warn in minor, remove in major), and cross-references UPGRADING.md. UPGRADING.md gains a brief stability guarantee note linking back to the README section. Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 1 + README.md | 30 ++++++++++++++++++++++++++++++ ROADMAP.md | 1 - UPGRADING.md | 2 ++ 4 files changed, 33 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 67132ea..b8c8769 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Public API stability policy — `README.md#versioning` documents what is and is not covered by semver guarantees from v1.0.0; `UPGRADING.md` cross-references the policy - Deprecation warning infrastructure — `SolidStackWeb.deprecator` exposes a gem-scoped `ActiveSupport::Deprecation` instance registered with `app.deprecators`; a private `deprecated_config` helper generates forwarding writers with warnings for any config keys renamed before 1.0 ### Changed diff --git a/README.md b/README.md index fa8e223..6970ec9 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,36 @@ Filters are preserved when switching between status tabs (Ready / Scheduled / Ru - [turbo-rails](https://github.com/hotwired/turbo-rails) >= 2.0 - [importmap-rails](https://github.com/rails/importmap-rails) >= 1.2 +## Versioning + +SolidStackWeb follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +### Public API + +The following are considered stable public API from v1.0.0 onwards — breaking changes to any of these require a major version bump: + +- The `SolidStackWeb.configure` block and all documented configuration keys +- The `SolidStackWeb.mount_path` helper +- The `authenticate` block interface +- The `GET /metrics` JSON payload shape +- The `SolidStackWeb::Engine` class and its mount interface +- The `rails generate solid_stack_web:install` generator + +### Not part of the public API + +The following are internal and may change in any release without notice: + +- Internal service classes (`CacheStats`, `QueueStats`, etc.) +- View templates, partial names, and CSS class names +- Controller and helper internals +- Private methods on any class + +### Deprecation policy + +When a public API item is renamed or removed, the old interface is deprecated in a **minor** release — it continues to work but issues an `ActiveSupport::Deprecation` warning pointing to the replacement. The old interface is removed in the next **major** release. The [UPGRADING.md](UPGRADING.md) file documents every breaking change and the migration steps. + +--- + ## Contributing 1. Fork the repository diff --git a/ROADMAP.md b/ROADMAP.md index bab53db..fbb26c9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -12,7 +12,6 @@ The path to v1.0.0 is staged: first achieve feature parity with `solid_queue_das ### Added - Complete README with configuration reference, screenshot gallery, and security guidance -- Public API stability policy documented — breaking changes require a major version bump --- diff --git a/UPGRADING.md b/UPGRADING.md index a08dc34..779f441 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -2,6 +2,8 @@ This document covers breaking changes between versions and the steps required to upgrade. Only versions that introduce breaking changes are listed — if your current version is not mentioned, upgrading requires no configuration changes beyond adding the new gem version to your `Gemfile`. +From v1.0.0, SolidStackWeb follows semantic versioning: patch releases are bug-fix only, minor releases are additive, and breaking changes to the public API only occur in major releases. See the [Versioning](README.md#versioning) section of the README for what is and is not covered by this guarantee. + For a full list of changes in every release, see [CHANGELOG.md](CHANGELOG.md). ---