vectordotdev/vector · error

exactly one `## Summary` section is required

Error message

exactly one `## Summary` section is required

What it means

`parse_breaking_sections` requires a breaking fragment to contain exactly one `## Summary` section. If the text after the H1 title contains zero or multiple occurrences of the SUMMARY_MARKER, it bails with this error. The Summary section feeds the release CUE, so its presence and uniqueness are enforced structurally.

Solutions

1. Add exactly one `## Summary` section after the H1 title.
2. Remove duplicate `## Summary` headings, merging their content.
3. Regenerate the fragment with `vdev changelog new <slug> --breaking` (or equivalent) to start from the correct template.

Example fix

// before
# My change
Some prose...
// after
# My change
## Summary
Describe the breaking change here.
## Migration
How to migrate.

let summary_count = text.matches("## Summary").count();
if summary_count != 1 {
    eprintln!("fragment must contain exactly one '## Summary' (found {summary_count})");
}

if let Err(e) = parse_breaking_sections(text) {
    eprintln!("fix fragment structure: {e}");
}

When it happens

Trigger: Parsing a breaking fragment (via vdev changelog validation) that omits `## Summary` entirely, spells it differently (e.g. `## summary`, `# Summary`), or duplicates the `## Summary` heading.

Common situations: Creating a fragment from scratch without using `vdev changelog new`'s template; copy-pasting sections and duplicating the Summary heading; hand-migrating old free-form fragments that never had Summary sections.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• content between the title and `## Summary` is not allowed —…
• exactly one `## Migration` section is required
• H1 title must not be empty
• invalid breaking fragment
• `## Summary` must not be empty

AI-assisted analysis of vectordotdev/vector@bdb87aeaa4 (2026-09-16). Data as JSON: /api/errors/a552bb627cf8e954. Report an issue: GitHub.

Appendix: source

Thrown at vdev/src/commands/changelog/mod.rs:134

    if !normalized.ends_with('\n') {
        normalized.push('\n');
    }
    let body: &str = &normalized;

    // 1) File must begin with an H1 title on the first line — no leading blank lines.
    let title_body = body
        .strip_prefix("# ")
        .ok_or_else(|| anyhow::anyhow!("first line must be an H1 title (`# ...`)"))?;
    let (title_line, after_title) = title_body.split_once('\n').unwrap_or((title_body, ""));
    let (title_text, anchor) = split_title_and_anchor(title_line);
    let title = title_text.to_string();
    if title.is_empty() {
        bail!("H1 title must not be empty");
    }

    // 2) Exactly one `## Summary` and one `## Migration`, in that order.
    if after_title.matches(SUMMARY_MARKER).count() != 1 {
        bail!("exactly one `## Summary` section is required");
    }
    if after_title.matches(MIGRATION_MARKER).count() != 1 {
        bail!("exactly one `## Migration` section is required");
    }
    let s_pos = after_title.find(SUMMARY_MARKER).unwrap();
    let m_pos = after_title.find(MIGRATION_MARKER).unwrap();
    if s_pos >= m_pos {
        bail!("`## Summary` must come before `## Migration`");
    }

    // Reject any prose between the H1 title and `## Summary`. Someone hand-migrating an
    // old free-form breaking fragment could carry over the previous body here and it
    // would silently disappear from both the release CUE and the upgrade guide.
    // Everything before Summary must be whitespace (`\n## Summary\n` starts with the
    // leading newline, so `s_pos` includes it).
    if let Some(prefix) = after_title.get(..s_pos)
        && !prefix.trim().is_empty()
    {

View on GitHub (pinned to bdb87aeaa4)