# Known Issues — Format and Usage

This directory documents known bugs, regressions, and workarounds for specific OpenStack releases. Check the file for your target release before deploying or upgrading.

## When to Read This

- Before deploying a new release for the first time
- Before upgrading from one release to another (read the **target** release file)
- When investigating an unexpected behavior that appeared after an upgrade
- When a deployment step fails in a way that is not covered by standard documentation

## File Index

| File | Release | Code Name | Release Date |
|---|---|---|---|
| [2025.1.md](2025.1.md) | 2025.1 | Epoxy | April 2025 |
| [2025.2.md](2025.2.md) | 2025.2 | Flamingo | October 2025 |
| [2026.1.md](2026.1.md) | 2026.1 | Gazpacho | April 2026 |

## Entry Format

Each issue follows this template:

```
### [Short Description — the symptom in 8 words or fewer]

**Symptom:** What the operator sees — error messages, behavior, affected operations.

**Cause:** Why it happens — the underlying bug or design change.

**Workaround:** Exact steps to mitigate or resolve the issue. Include full commands.

**Affected versions:** Release range where the bug is present (e.g., "2025.1.0 through 2025.1.2").

**Status:** One of:
  - Open — no fix merged yet
  - Fixed in <version> — patch released; upgrade to resolve
  - Upstream fix pending — patch proposed, not yet merged
  - Won't fix — accepted limitation
```

## Issue Categories

Issues are grouped within each release file under these headings:

- **Upgrade Blockers** — must be addressed before upgrading to this release
- **Configuration Changes** — options renamed, removed, or changed in behavior that break existing configs
- **Deprecations Enforced** — items deprecated in a prior release that are now removed
- **Known Bugs** — bugs present in the release that operators may encounter
- **Security Advisories** — OSSAs (OpenStack Security Advisories) relevant to this release
- **Performance Notes** — regressions or new tuning requirements

## Sources

- Official OpenStack release notes: https://releases.openstack.org
- Launchpad bug tracker: https://bugs.launchpad.net/openstack
- OpenStack Security Advisories: https://security.openstack.org/ossalist.html
- Individual project release notes (e.g., https://docs.openstack.org/nova/latest/release-notes.html)

## Contributing New Issues

When you encounter a bug not documented here:

1. Reproduce it reliably on a clean deployment.
2. Identify the affected component and version range.
3. Write a workaround with exact commands.
4. Add the entry under the correct release file following the format above.
5. Link the upstream Launchpad bug if one exists.