> ## Documentation Index > Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt > Use this file to discover all available pages before exploring further. # Release notices # Doc Type: Release Notices > **Tier**: Reference | **Reader phase**: Refining & Details\ > **Back to tier overview**: [reference/index.md](index.md) *** ## What it is Release Notices are **structured records of changes** in a specific Aviatrix product release. They serve as the authoritative source of truth for what changed, what was fixed, and what known issues remain in a given version. Operators, engineers, and architects consult release notices before upgrading and when diagnosing unexpected behavior. There are two primary document types under Release Notices: * **Release Notes** — Per-version records of corrected issues and known issues. One document per product per version. * **Field Notices** — Alerts about specific issues that require operator action, issued independently of the release cycle. A third type exists but is less common: * **Security Advisories (PSIRT)** — Notices about security vulnerabilities, their severity, affected versions, and remediation. *** ## Goal After reading a Release Notice, the reader knows exactly what changed in this version, what known issues remain, and what workarounds are available. For troubleshooting: they can determine whether a known issue explains the behavior they are seeing. For upgrade planning: they have the issue and workaround detail they need to assess impact — the decision of which version to upgrade to belongs in the Upgrade Guide. *** ## Primary personas | Persona | How they use it | | - | - | | **Operator** | Reviews before upgrading; consults when diagnosing production issues | | **Engineer** | Checks for behavior changes affecting implementations | | **Technical Manager** | Reviews to assess upgrade risk and plan maintenance windows | *** ## When to create a new Release Notes document Create a new Release Notes document for every product release that ships to customers. One document per product per version. The document is created when the release ships and may be updated (with a "Last updated" timestamp) as new known issues are discovered or existing issues are resolved in subsequent releases. Do not combine multiple product releases into a single document. Do not combine release notes for different products (controller, CoPilot, VPN client) into a single document. *** ## Required sections — Release Notes 1. **Release metadata** — Immediately below the page title (rendered from frontmatter), as plain text (not a heading): * `Release date: [Month DD, YYYY]` * `Last updated: [Month DD, YYYY]` (update this when the document is revised) 2. **Corrected Issues** — An H2 section containing a two-column table of issues resolved in this release. Columns: **Issue ID** | **Description**. Each description should state: what the problem was, under what conditions it occurred, and (if relevant) what the workaround was before the fix. 3. **Known Issues** — An H2 section containing a two-column table of issues present in this release that are not yet resolved. Columns: **Issue ID** | **Description**. Include the workaround inline in the description where one exists. *** ## Required sections — Field Notices 1. **Summary** — 3–5 sentences: what the issue is, which versions and products are affected, what the impact is, and what action (if any) is required. 2. **Affected Versions** — A table or list of affected product versions. 3. **Resolution** — What has been done or will be done to resolve the issue. If a fix is available, link to the release notes for the fixing version. If operator action is required, link to the relevant Configuration or Operational Guide. 4. **Timeline** — Key dates: when the issue was discovered, when it was communicated, when a fix is expected. *** ## Required sections — Security Advisories (PSIRT) 1. **Severity** — CVSS score and severity rating (Critical / High / Medium / Low). 2. **Summary** — What the vulnerability is, how it can be exploited, and what the impact is. 3. **Affected Versions** — Table of affected products and versions. 4. **Remediation** — What operators must do: patch version, configuration change, or workaround. 5. **Timeline** — Discovery date, disclosure date, patch availability date. *** ## Tone & voice **Precise and formal.** Release Notices are records, not narratives. Issue descriptions should be specific: state the exact behavior, the conditions that trigger it, and the impact. Avoid vague descriptions like "fixed an issue that could cause instability." Instead: "Fixed an issue where the controller restart loop could occur when more than 500 gateways were registered and the database vacuum had not run in 30+ days." Use past tense for corrected issues ("Fixed...", "Resolved...", "Corrected..."). Use present tense for known issues ("The gateway health check incorrectly reports..."). *** ## Length guidance **Release Notes**: 50–2000+ lines depending on the number of issues. There is no target length — completeness takes priority. Structure and scannability (via table format) matter more than brevity. **Field Notices and Security Advisories**: 50–150 lines. These should be concise and action-oriented. *** ## Frontmatter See [Frontmatter Standards](../frontmatter.md) for field definitions and formatting rules. Title naming conventions by sub-type: * **Release Notes**: `[Product] Release [Version]`. Example: *Aviatrix Controller Release 8.2.0*. * **Field Notices**: `Field Notice: [Brief Description]`. Example: *Field Notice: CoPilot Session Timeout Behavior Change*. * **Security Advisories**: `Security Advisory: [CVE ID or Brief Description]`. ```yaml theme={null} --- title: "[Product] Release [Version]" description: "Release notes for Aviatrix [Product] version [X.Y.Z] — corrected issues, known issues, and workarounds." --- ``` *** ## Issue table format Both the Corrected Issues and Known Issues tables use pipe-delimited markdown: ```markdown theme={null} | Issue ID | Description | |---|---| | AVX-12345 | **Gateway health check false positives.** The gateway health check incorrectly reported gateways as unhealthy when the CoPilot polling interval was set below 30 seconds. This caused unnecessary failover events in HA configurations. Workaround (prior to this release): Set the polling interval to 30 seconds or higher. | ``` Guidelines for issue descriptions: * Lead with a **bolded short title** (3–6 words) summarizing the issue * Follow with the full description: what happened, under what conditions, and the impact * For known issues, include the workaround inline in the description * Use exact version numbers, setting names, and thresholds — no vague language *** ## Mintlify components See [Style Guide](../style-guide.md) for component definitions and usage rules. Keep to plain markdown. Use `` for high-impact known issues and tables for all issue tracking. Avoid decorative components. *** ## Linking * **Link in from**: The release notices index page * **Link out to**: Any internal or external document that provides relevant additional context — upgrade guides, configuration guides, support resources, third-party documentation. Release Notices are not bound by the no-upstream-linking rule that applies to other Reference docs. *** ## Dos and don'ts | Do | Don't | | - | - | | Use specific, technical issue descriptions | Write vague descriptions like "improved stability" | | Include workarounds for every known issue where one exists | Leave a known issue table row with no workaround guidance | | Update the "Last updated" timestamp whenever the document is revised | Silently update documents without signaling the change | | Use AVX issue IDs consistently for traceability | Omit issue IDs | | Write corrected issues in past tense, known issues in present tense | Mix tenses within the same document | | Create one document per product per version | Combine multiple versions or products in one document | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.