Skip to content

changelog.md

Latest commit

 

History

History
93 lines (69 loc) · 3.15 KB

changelog.md

File metadata and controls

93 lines (69 loc) · 3.15 KB
paths
news/**

Changelog Conventions

File Organization

  • One file per major.minor version: news/changelog-{version}.md (e.g., changelog-1.9.md)
  • Check configuration file for current QUARTO_VERSION
  • First line: All changes included in {version}:

Section Hierarchy (strict order)

  1. ## Regression fixes - Always FIRST if present
  2. ## Dependencies - Bundled tool updates
  3. ## Formats - By output format (H3 subsections)
  4. ## Projects - By project type (H3 subsections)
  5. ## Publishing - By platform (H3 subsections)
  6. ## Lua API - Filter API changes
  7. ## Commands - CLI commands (H3 subsections)
  8. ## Extensions - Extension system changes
  9. ## Engines - Execution engines (H3 subsections)
  10. ## Other fixes and improvements - Always LAST

Format Subsections

Use H3 headings with backtick-wrapped names:

### `html`
### `typst`
### `pdf`

Entry Format

- ([#issue](url)): Description ending with period.

For external contributors (not core team):

- ([#issue](url)): Description. (author: @username)

Variations:

  • Pull requests: ([#13441](https://github.com/quarto-dev/quarto-cli/pull/13441))
  • External repos: ([rstudio/tinytex-releases#49](url))
  • No issue/PR (rare): Reference commit hash instead: ([commit](https://github.com/quarto-dev/quarto-cli/commit/abc123))

Writing Entries

Language patterns:

  • Fixes: Start with "Fix" - describe what was broken
    • "Fix icon=false not working with typst format."
  • Enhancements: Start with "Add" or "Support" - describe what was added
    • "Add support for icon=false in callouts."
  • Updates: Start with "Update"
    • "Update pandoc to 3.8.3"

Style:

  • Use backticks for code/options: `icon=false`
  • Period at end of every description
  • Author attribution (author: @username) for external contributors only - do NOT add for quarto-cli core team members

Regression Fixes

What qualifies: Bugs introduced in a previous major.minor version (e.g., a 1.8 feature that broke in 1.9)

Skip changelog entirely when the regression was introduced by another change in the same version cycle. For example, if a 1.9 bug fix introduced a new bug also fixed in 1.9, the fix does not need a changelog entry — the original entry covers the feature area.

Placement: Always at TOP of the file, before Dependencies

Workflow: If you initially place an entry elsewhere and later determine it's a regression, move it to the Regression fixes section

Backports

When a fix is backported to a stable branch:

  1. Entry exists in current version changelog (e.g., changelog-1.9.md)
  2. Also add entry to stable version changelog (e.g., changelog-1.8.md)

What NOT to Put Here

Highlights are NOT changelog entries. They are:

  • Promotional content for release announcements
  • Managed in quarto-web: docs/prerelease/{version}/_highlights.qmd
  • Separate from technical changelog

Publication

Changelogs are published to quarto.org via:

  • GitHub release attaches changelog.md asset
  • quarto-web fetches and displays at /docs/download/changelog/{version}/