# Story 10.13: README Stability Claims Accuracy

**Status:** Complete
**Priority:** Medium
**Depends on:** None

---

## Context / Background

The GPT-5.2 audit identified that README.md makes "semver-stable" claims while the project is pre-1.0 with multiple experimental/placeholder components.

**Current README claims:**

```markdown
<!-- Line 25 -->
- **Beta stability**: Core logger and FastAPI middleware are semver-stable; plugin marketplace remains experimental.

<!-- Line 176 -->
- Core APIs (logger, FastAPI middleware) are treated as stable; breaking changes follow semver with deprecations.
```

**Reality:**

| Factor | Status |
|--------|--------|
| Version | 0.3.x (pre-1.0) |
| PyPI classifier | "Development Status :: 4 - Beta" |
| CLI | Placeholder: "Coming soon in future stories" |
| Marketplace | Config only, no functionality |
| mmap_persistence | Tagged "experimental" |
| Several sinks | "lifecycle placeholder" comments |

**Problem:**

Per semver specification, versions before 1.0.0 make no stability guarantees - anything can change. Claiming "semver-stable" for a 0.3.x project is technically incorrect and could mislead users expecting 1.0+ guarantees.

---

## Scope (In / Out)

### In Scope

- Revise README stability language to be accurate
- Add explicit "Stability Tiers" section listing component maturity
- Update "Early adopters" section with clearer expectations
- Ensure PyPI classifier matches README claims

### Out of Scope

- Removing experimental components
- Rushing to 1.0 release
- Changing actual stability guarantees

---

## Acceptance Criteria

### AC1: Remove "semver-stable" Claim

**Description:** README no longer uses "semver-stable" for pre-1.0 project.

**Validation:**

```bash
grep -i "semver-stable" README.md
# Should return no matches
```

### AC2: Accurate Stability Language

**Description:** Stability claims reflect 0.x reality with clear language.

**Validation:**

```markdown
## Stability

Fapilog follows [Semantic Versioning](https://semver.org/). As a 0.x project:

- **Core APIs** (logger, FastAPI middleware): Stable within minor versions.
  Breaking changes only in minor version bumps (0.3 → 0.4) with deprecation warnings.
- **Plugins**: Stable unless marked experimental.
- **Experimental**: Marketplace, CLI, mmap_persistence sink. May change without notice.

We aim for 1.0 when core APIs have been production-tested across multiple releases.
```

### AC3: Stability Tiers Documented

**Description:** README includes a clear stability tier table.

**Validation:**

```markdown
### Component Stability

| Component | Stability | Notes |
|-----------|-----------|-------|
| Core logger | Stable | Breaking changes with deprecation |
| FastAPI middleware | Stable | Breaking changes with deprecation |
| Built-in sinks | Stable | file, stdout, webhook |
| Built-in enrichers | Stable | |
| Plugin system | Stable | Contract may evolve |
| Marketplace | Experimental | Config only, not functional |
| CLI | Placeholder | Not implemented |
| mmap_persistence | Experimental | Performance testing |
```

### AC4: Early Adopters Section Updated

**Description:** "Early adopters" section gives accurate expectations.

**Validation:**

```markdown
## Early adopters

Fapilog is pre-1.0 but actively used in production. What this means:

- **Core APIs are stable** - We avoid breaking changes; when necessary, we deprecate first
- **0.x → 0.y upgrades** may require minor code changes (documented in CHANGELOG)
- **Experimental components** (marketplace, CLI) are not ready for production
- **Feedback welcome** - Open issues or join [Discord](...)
```

---

## Implementation Notes

### File Changes

```text
README.md (MODIFIED - revise stability claims)
```

### Key Edits

**Line 25 - Change from:**
```markdown
- **Beta stability**: Core logger and FastAPI middleware are semver-stable; plugin marketplace remains experimental.
```

**To:**
```markdown
- **Pre-1.0 stability**: Core logger and FastAPI middleware APIs are stable within minor versions; see [Stability](#stability) for details.
```

**Line 176 area - Replace "Early adopters" section** with clearer stability tiers and expectations.

---

## Tasks

### Phase 1: Revise Claims

- [ ] Remove "semver-stable" from line 25
- [ ] Add "Stability" section with tier table
- [ ] Revise "Early adopters" section

### Phase 2: Validation

- [ ] Verify no "semver-stable" claims remain
- [ ] Verify stability tiers match actual component status
- [ ] Check links work

### Phase 3: Finalize

- [ ] Update CHANGELOG

---

## Tests

### Manual Verification

```bash
# No "semver-stable" claims
grep -i "semver-stable" README.md && exit 1 || echo "OK"

# Stability section exists
grep -q "## Stability" README.md && echo "OK" || exit 1

# Component table exists
grep -q "Component Stability" README.md && echo "OK" || exit 1
```

---

## Definition of Done

### Code Complete

- [x] "semver-stable" removed
- [x] Stability section added
- [x] Component tier table added
- [x] Early adopters section revised

### Quality Assurance

- [x] README renders correctly
- [x] All links work
- [x] No markdown lint errors

### Documentation

- [x] CHANGELOG updated (skipped - documentation accuracy fix, no behavior change)

---

## Risks / Rollback

### Risks

1. **Risk:** Users perceive stability downgrade
   - **Mitigation:** Language clarifies we're *more honest*, not less stable

2. **Risk:** Competitors use "pre-1.0" against us
   - **Mitigation:** Emphasize production usage and clear stability tiers

### Rollback Plan

If issues occur:

1. Revert README changes
2. Discuss alternative wording

---

## Related Stories

- **Related:** Story 10.10 - Changelog traceability (release discipline)
- **Related:** Story 10.12 - Automated changelog (release process)

---

## Change Log

| Date       | Change        | Author |
|------------|---------------|--------|
| 2026-01-16 | Initial draft | Claude |
