feat: document public API stability policy for v1.0.0

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

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

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
 
 ---
 

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).
 
 ---